1# @ohos.multimedia.media (媒体服务) 2 3> **说明：** 4> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 5 6媒体子系统为开发者提供一套简单且易于理解的接口，使得开发者能够方便接入系统并使用系统的媒体资源。 7 8媒体子系统包含了音视频相关媒体业务，提供以下常用功能： 9 10- 音视频播放（[AVPlayer](#avplayer9)<sup>9+</sup>） 11 12- 音视频录制（[AVRecorder](#avrecorder9)<sup>9+</sup>） 13 14- 视频转码（[AVTranscoder](#avtranscoder12)<sup>12+</sup>） 15 16- 获取音视频元数据（[AVMetadataExtractor](#avmetadataextractor11)<sup>11+</sup>） 17 18- 获取视频缩略图（[AVImageGenerator](#avimagegenerator12)<sup>12+</sup>） 19 20- 屏幕录制（[AVScreenCaptureRecorder](#avscreencapturerecorder12)<sup>12+</sup>） 21 22## 导入模块 23 24```ts 25import { media } from '@kit.MediaKit'; 26``` 27 28## media.createAVPlayer<sup>9+</sup> 29 30createAVPlayer(callback: AsyncCallback\<AVPlayer>): void 31 32异步方式创建音视频播放实例，通过注册回调函数获取返回值。 33 34> **说明：** 35> 36> - 推荐单个应用创建的音视频播放实例（即音频、视频、音视频三类相加）不超过16个。<!--Del--> 37> - 可创建的音视频播放实例数量依赖于设备芯片的支持情况，如芯片支持创建的数量少于上述情况，请以芯片规格为准。如RK3568推荐单个应用创建6个以内的音视频播放实例。<!--DelEnd--> 38 39**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 42 43**参数：** 44 45| 参数名 | 类型 | 必填 | 说明 | 46| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 47| callback | AsyncCallback\<[AVPlayer](#avplayer9)> | 是 | 回调函数。异步返回AVPlayer实例，失败时返回null。可用于音视频播放。 | 48 49**错误码：** 50 51以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 52 53| 错误码ID | 错误信息 | 54| -------- | ------------------------------ | 55| 5400101 | No memory. Return by callback. | 56 57**示例：** 58 59```ts 60import { BusinessError } from '@kit.BasicServicesKit'; 61 62let avPlayer: media.AVPlayer; 63media.createAVPlayer((error: BusinessError, video: media.AVPlayer) => { 64 if (video != null) { 65 avPlayer = video; 66 console.info('Succeeded in creating AVPlayer'); 67 } else { 68 console.error(`Failed to create AVPlayer, error message:${error.message}`); 69 } 70}); 71``` 72 73## media.createAVPlayer<sup>9+</sup> 74 75createAVPlayer(): Promise\<AVPlayer> 76 77异步方式创建音视频播放实例，通过Promise获取返回值。 78 79> **说明：** 80> 81> - 推荐单个应用创建的音视频播放实例（即音频、视频、音视频三类相加）不超过16个。<!--Del--> 82> - 可创建的音视频播放实例数量依赖于设备芯片的支持情况，如芯片支持创建的数量少于上述情况，请以芯片规格为准。如RK3568推荐单个应用创建6个以内的音视频播放实例。<!--DelEnd--> 83 84**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 85 86**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 87 88**返回值：** 89 90| 类型 | 说明 | 91| ------------------------------- | ------------------------------------------------------------ | 92| Promise\<[AVPlayer](#avplayer9)> | Promise对象。异步返回AVPlayer实例，失败时返回null。可用于音视频播放。 | 93 94**错误码：** 95 96以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 97 98| 错误码ID | 错误信息 | 99| -------- | ----------------------------- | 100| 5400101 | No memory. Return by promise. | 101 102**示例：** 103 104```ts 105import { BusinessError } from '@kit.BasicServicesKit'; 106 107let avPlayer: media.AVPlayer; 108media.createAVPlayer().then((video: media.AVPlayer) => { 109 if (video != null) { 110 avPlayer = video; 111 console.info('Succeeded in creating AVPlayer'); 112 } else { 113 console.error('Failed to create AVPlayer'); 114 } 115}).catch((error: BusinessError) => { 116 console.error(`Failed to create AVPlayer, error message:${error.message}`); 117}); 118``` 119 120## media.createAVRecorder<sup>9+</sup> 121 122createAVRecorder(callback: AsyncCallback\<AVRecorder>): void 123 124异步方式创建音视频录制实例。通过注册回调函数获取返回值。 125 126> **说明：** 127> 128> 应用可创建多个音视频录制实例，但由于设备共用音频通路，一个设备仅能有一个实例进行音频录制。创建第二个实例录制音频时，将会因为音频通路冲突导致创建失败。 129 130**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 131 132**参数：** 133 134| 参数名 | 类型 | 必填 | 说明 | 135| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 136| callback | AsyncCallback\<[AVRecorder](#avrecorder9)> | 是 | 回调函数。异步返回AVRecorder实例，失败时返回null。可用于录制音视频媒体。 | 137 138**错误码：** 139 140以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 141 142| 错误码ID | 错误信息 | 143| -------- | ------------------------------ | 144| 5400101 | No memory. Return by callback. | 145 146**示例：** 147 148```ts 149import { BusinessError } from '@kit.BasicServicesKit'; 150let avRecorder: media.AVRecorder; 151 152media.createAVRecorder((error: BusinessError, recorder: media.AVRecorder) => { 153 if (recorder != null) { 154 avRecorder = recorder; 155 console.info('Succeeded in creating AVRecorder'); 156 } else { 157 console.error(`Failed to create AVRecorder, error message:${error.message}`); 158 } 159}); 160``` 161 162## media.createAVRecorder<sup>9+</sup> 163 164createAVRecorder(): Promise\<AVRecorder> 165 166异步方式创建音视频录制实例。通过Promise获取返回值。 167 168> **说明：** 169> 170> 应用可创建多个音视频录制实例，但由于设备共用音频通路，一个设备仅能有一个实例进行音频录制。创建第二个实例录制音频时，将会因为音频通路冲突导致创建失败。 171 172**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 173 174**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 175 176**返回值：** 177 178| 类型 | 说明 | 179| ------------------------------------ | ------------------------------------------------------------ | 180| Promise\<[AVRecorder](#avrecorder9)> | Promise对象。异步返回AVRecorder实例，失败时返回null。可用于录制音视频媒体。 | 181 182**错误码：** 183 184以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 185 186| 错误码ID | 错误信息 | 187| -------- | ----------------------------- | 188| 5400101 | No memory. Return by promise. | 189 190**示例：** 191 192```ts 193import { BusinessError } from '@kit.BasicServicesKit'; 194 195let avRecorder: media.AVRecorder; 196media.createAVRecorder().then((recorder: media.AVRecorder) => { 197 if (recorder != null) { 198 avRecorder = recorder; 199 console.info('Succeeded in creating AVRecorder'); 200 } else { 201 console.error('Failed to create AVRecorder'); 202 } 203}).catch((error: BusinessError) => { 204 console.error(`Failed to create AVRecorder, error message:${error.message}`); 205}); 206``` 207 208## media.createAVTranscoder<sup>12+</sup> 209 210createAVTranscoder(): Promise\<AVTranscoder> 211 212异步方式创建视频转码实例，通过Promise获取返回值。 213 214> **说明：** 215 216> 可创建的视频转码实例不能超过2个。 217 218**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 219 220**返回值：** 221 222| 类型 | 说明 | 223| ------------------------------- | ------------------------------------------------------------ | 224| Promise\<[AVTranscoder](#avtranscoder12)> | Promise对象。异步返回AVTranscoder实例，失败时返回null。可用于视频转码。 | 225 226**错误码：** 227 228以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 229 230| 错误码ID | 错误信息 | 231| -------- | ----------------------------- | 232| 5400101 | No memory. Return by promise. | 233 234**示例：** 235 236```ts 237import { BusinessError } from '@kit.BasicServicesKit'; 238 239let avTranscoder: media.AVTranscoder | undefined = undefined; 240media.createAVTranscoder().then((transcoder: media.AVTranscoder) => { 241 if (transcoder != null) { 242 avTranscoder = transcoder; 243 console.info('Succeeded in creating AVTranscoder'); 244 } else { 245 console.error('Failed to create AVTranscoder'); 246 } 247}).catch((error: BusinessError) => { 248 console.error(`Failed to create AVTranscoder, error message:${error.message}`); 249}); 250``` 251 252## media.createAVMetadataExtractor<sup>11+</sup> 253 254createAVMetadataExtractor(callback: AsyncCallback\<AVMetadataExtractor>): void 255 256异步方式创建AVMetadataExtractor实例，通过注册回调函数获取返回值。 257 258**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 259 260**参数：** 261 262| 参数名 | 类型 | 必填 | 说明 | 263| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 264| callback | AsyncCallback\<[AVMetadataExtractor](#avmetadataextractor11)> | 是 | 回调函数。当创建AVMetadataExtractor实例成功，err为undefined，data为获取到的AVMetadataExtractor实例，否则为错误对象。 | 265 266**错误码：** 267 268以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 269 270| 错误码ID | 错误信息 | 271| -------- | ------------------------------ | 272| 5400101 | No memory. Returned by callback. | 273 274**示例：** 275 276```ts 277import { BusinessError } from '@kit.BasicServicesKit'; 278 279let avMetadataExtractor: media.AVMetadataExtractor; 280media.createAVMetadataExtractor((error: BusinessError, extractor: media.AVMetadataExtractor) => { 281 if (extractor != null) { 282 avMetadataExtractor = extractor; 283 console.info('Succeeded in creating AVMetadataExtractor'); 284 } else { 285 console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`); 286 } 287}); 288``` 289 290## media.createAVMetadataExtractor<sup>11+</sup> 291 292createAVMetadataExtractor(): Promise\<AVMetadataExtractor> 293 294异步方式创建AVMetadataExtractor实例，通过Promise获取返回值。 295 296**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 297 298**返回值：** 299 300| 类型 | 说明 | 301| -------------- | ---------------------------------------- | 302| Promise\<[AVMetadataExtractor](#avmetadataextractor11)> | Promise对象。异步返回元数据获取类对象（AVMetadataExtractor）。 | 303 304**错误码：** 305 306以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 307 308| 错误码ID | 错误信息 | 309| -------- | ------------------------------ | 310| 5400101 | No memory. Returned by promise. | 311 312**示例：** 313 314```ts 315import { BusinessError } from '@kit.BasicServicesKit'; 316 317let avMetadataExtractor: media.AVMetadataExtractor; 318media.createAVMetadataExtractor().then((extractor: media.AVMetadataExtractor) => { 319 if (extractor != null) { 320 avMetadataExtractor = extractor; 321 console.info('Succeeded in creating AVMetadataExtractor'); 322 } else { 323 console.error(`Failed to create AVMetadataExtractor`); 324 } 325}).catch((error: BusinessError) => { 326 console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`); 327}); 328``` 329 330## media.createSoundPool<sup>10+</sup> 331 332createSoundPool(maxStreams: number, audioRenderInfo: audio.AudioRendererInfo, callback: AsyncCallback\<SoundPool>): void 333 334创建音频池实例，使用callback方式异步获取返回值。 335 336> **说明：** 337> 338> - API 18以下版本，创建的SoundPool对象底层为单实例模式，一个应用进程只能够创建1个SoundPool实例。 339> - API 18及API 18以上版本，创建的SoundPool对象底层为多实例模式，一个应用进程最多能够创建128个SoundPool实例。 340 341**系统能力：** SystemCapability.Multimedia.Media.SoundPool 342 343**参数：** 344 345| 参数名 | 类型 | 必填 | 说明 | 346| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 347| maxStreams | number | 是 | soundPool实例的最大播放的流数，设置范围为1-32的正整数。 | 348| audioRenderInfo | [audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8) | 是 | 音频播放参数信息。其中audioRenderInfo中的参数usage取值为STREAM_USAGE_UNKNOWN，STREAM_USAGE_MUSIC，STREAM_USAGE_MOVIE，STREAM_USAGE_AUDIOBOOK时，SoundPool播放短音时为混音模式，不会打断其他音频播放。 | 349| callback | AsyncCallback<[SoundPool](js-apis-inner-multimedia-soundPool.md)> | 是 | 回调函数。异步返回SoundPool实例，失败时返回null。用于音频池实例的加载播放功能。 | 350 351**错误码：** 352 353以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 354 355| 错误码ID | 错误信息 | 356| -------- | ------------------------------ | 357| 5400101 | No memory. Return by callback. | 358 359**示例：** 360 361```js 362import { audio } from '@kit.AudioKit'; 363 364let soundPool: media.SoundPool; 365let audioRendererInfo: audio.AudioRendererInfo = { 366 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 367 rendererFlags : 0 368}; 369 370media.createSoundPool(5, audioRendererInfo, (error, soundPool_: media.SoundPool) => { 371 if (error) { 372 console.error(`Failed to createSoundPool`); 373 return; 374 } else { 375 soundPool = soundPool_; 376 console.info(`Succeeded in createSoundPool`); 377 } 378}); 379``` 380 381## media.createSoundPool<sup>10+</sup> 382 383createSoundPool(maxStreams: number, audioRenderInfo: audio.AudioRendererInfo): Promise\<SoundPool> 384 385创建音频池实例，通过Promise获取返回值。 386 387> **说明：** 388> 389> - API 18以下版本，创建的SoundPool对象底层为单实例模式，一个应用进程只能够创建1个SoundPool实例。 390> - API 18及API 18以上版本，创建的SoundPool对象底层为多实例模式，一个应用进程最多能够创建128个SoundPool实例。 391 392**系统能力：** SystemCapability.Multimedia.Media.SoundPool 393 394**参数：** 395 396| 参数名 | 类型 | 必填 | 说明 | 397| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 398| maxStreams | number | 是 | soundPool实例的最大播放的流数，设置范围为1-32的正整数。 | 399| audioRenderInfo | [audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8) | 是 | 音频播放参数信息 | 400 401**返回值：** 402 403| 类型 | 说明 | 404| ----------------------------------------- | ------------------------------------------------------------ | 405| Promise<[SoundPool](js-apis-inner-multimedia-soundPool.md)> | Promise对象。异步返回SoundPool实例，失败时返回null。用于音频池实例的加载播放功能。 | 406 407**错误码：** 408 409以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 410 411| 错误码ID | 错误信息 | 412| -------- | ----------------------------- | 413| 5400101 | No memory. Return by promise. | 414 415**示例：** 416 417```js 418import { audio } from '@kit.AudioKit'; 419import { BusinessError } from '@kit.BasicServicesKit'; 420 421let soundPool: media.SoundPool; 422let audioRendererInfo: audio.AudioRendererInfo = { 423 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 424 rendererFlags : 0 425}; 426 427media.createSoundPool(5, audioRendererInfo).then((soundpool_: media.SoundPool) => { 428 if (soundpool_ != null) { 429 soundPool = soundpool_; 430 console.info('Succceeded in creating SoundPool'); 431 } else { 432 console.error('Failed to create SoundPool'); 433 } 434}, (error: BusinessError) => { 435 console.error(`soundpool catchCallback, error message:${error.message}`); 436}); 437``` 438 439## media.createAVScreenCaptureRecorder<sup>12+</sup> 440 441createAVScreenCaptureRecorder(): Promise\<AVScreenCaptureRecorder> 442 443创建屏幕录制实例，通过Promise获取返回值。 444 445**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 446 447**返回值：** 448 449| 类型 | 说明 | 450| ------------------------------------------------------------ | ------------------------------------------------------------ | 451| Promise\<[AVScreenCaptureRecorder](#avscreencapturerecorder12)> | Promise对象。异步返回AVScreenCaptureRecorder实例，失败时返回null。可用于进行屏幕录制。 | 452 453**错误码：** 454 455| 错误码ID | 错误信息 | 456| -------- | ------------------------------ | 457| 5400101 | No memory. Return by promise. | 458 459**示例：** 460 461```ts 462import { BusinessError } from '@kit.BasicServicesKit'; 463 464let avScreenCaptureRecorder: media.AVScreenCaptureRecorder; 465media.createAVScreenCaptureRecorder().then((captureRecorder: media.AVScreenCaptureRecorder) => { 466 if (captureRecorder != null) { 467 avScreenCaptureRecorder = captureRecorder; 468 console.info('Succeeded in createAVScreenCaptureRecorder'); 469 } else { 470 console.error('Failed to createAVScreenCaptureRecorder'); 471 } 472}).catch((error: BusinessError) => { 473 console.error(`createAVScreenCaptureRecorder catchCallback, error message:${error.message}`); 474}); 475``` 476 477## SoundPool<sup>10+</sup> 478 479type SoundPool = _SoundPool 480 481音频池，提供了系统声音的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能。 482 483**系统能力：** SystemCapability.Multimedia.Media.SoundPool 484 485| 类型 | 说明 | 486| -------- | ------------------------------ | 487| [_SoundPool](js-apis-inner-multimedia-soundPool.md#soundpool) | 音频池，提供了系统声音的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能。 | 488 489## PlayParameters<sup>10+</sup> 490 491type PlayParameters = _PlayParameters 492 493表示音频池播放参数设置。 494 495**系统能力：** SystemCapability.Multimedia.Media.SoundPool 496 497| 类型 | 说明 | 498| -------- | ------------------------------ | 499| [_PlayParameters](js-apis-inner-multimedia-soundPool.md#playparameters) | 表示音频池播放参数设置。 | 500 501## AVErrorCode<sup>9+</sup> 502 503[媒体错误码](errorcode-media.md)类型枚举 504 505**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 506 507**系统能力：** SystemCapability.Multimedia.Media.Core 508 509| 名称 | 值 | 说明 | 510| :------------------------------------ | ------- | ------------------------------------ | 511| AVERR_OK | 0 | 表示操作成功。 | 512| AVERR_NO_PERMISSION | 201 | 表示无权限执行此操作。 | 513| AVERR_INVALID_PARAMETER | 401 | 表示传入入参无效。 | 514| AVERR_UNSUPPORT_CAPABILITY | 801 | 表示当前版本不支持该API能力。 | 515| AVERR_NO_MEMORY | 5400101 | 表示系统内存不足或服务数量达到上限。 | 516| AVERR_OPERATE_NOT_PERMIT | 5400102 | 表示当前状态不允许或无权执行此操作。 | 517| AVERR_IO | 5400103 | 表示数据流异常信息。 | 518| AVERR_TIMEOUT | 5400104 | 表示系统或网络响应超时。 | 519| AVERR_SERVICE_DIED | 5400105 | 表示服务进程死亡。 | 520| AVERR_UNSUPPORT_FORMAT | 5400106 | 表示不支持当前媒体资源的格式。 | 521| AVERR_AUDIO_INTERRUPTED<sup>11+</sup> | 5400107 | 表示音频焦点被抢占 | 522| AVERR_IO_HOST_NOT_FOUND<sup>14+</sup> | 5411001 | 表示解析或链接服务端地址错误。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 523| AVERR_IO_CONNECTION_TIMEOUT<sup>14+</sup> | 5411002 | 表示网络连接超时。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 524| AVERR_IO_NETWORK_ABNORMAL<sup>14+</sup> | 5411003 | 表示网络异常导致的数据或链路异常。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 525| AVERR_IO_NETWORK_UNAVAILABLE<sup>14+</sup> | 5411004 | 表示网络被禁用。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 526| AVERR_IO_NO_PERMISSION<sup>14+</sup> | 5411005 | 表示无访问权限。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 527| AVERR_IO_REQUEST_DENIED<sup>14+</sup> | 5411006 | 表示客户端请求参数错误或超出处理能力。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 528| AVERR_IO_RESOURCE_NOT_FOUND<sup>14+</sup> | 5411007 | 表示无可用网络资源。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 529| AVERR_IO_SSL_CLIENT_CERT_NEEDED<sup>14+</sup> | 5411008 | 表示服务端校验客户端证书失败。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 530| AVERR_IO_SSL_CONNECTION_FAILED<sup>14+</sup> | 5411009 | 表示SSL连接失败。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 531| AVERR_IO_SSL_SERVER_CERT_UNTRUSTED<sup>14+</sup> | 5411010 | 表示客户端校验服务端证书失败。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 532| AVERR_IO_UNSUPPORTED_REQUEST<sup>14+</sup> | 5411011 | 表示网络协议的原因导致请求不受支持。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 533| AVERR_SEEK_CONTINUOUS_UNSUPPORTED<sup>18+</sup> | 5410002 | 表示不支持SEEK_CONTINUOUS模式的seek。 <br> **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 534| AVERR_SUPER_RESOLUTION_UNSUPPORTED<sup>18+</sup> | 5410003 | 表示不支持超分。 <br> **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 535| AVERR_SUPER_RESOLUTION_NOT_ENABLED<sup>18+</sup> | 5410004 | 表示未使能超分。 <br> **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 536 537## MediaType<sup>8+</sup> 538 539媒体类型枚举。 540 541**系统能力：** SystemCapability.Multimedia.Media.Core 542 543| 名称 | 值 | 说明 | 544| -------------- | --------------------- | ------------------- | 545| MEDIA_TYPE_AUD | 0 | 表示音频。 <br> **原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 | 546| MEDIA_TYPE_VID | 1 | 表示视频。 <br> **原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 | 547| MEDIA_TYPE_SUBTITLE<sup>12+</sup> | 2 | 表示字幕。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 548 549## CodecMimeType<sup>8+</sup> 550 551Codec MIME类型枚举。 552 553**系统能力：** SystemCapability.Multimedia.Media.Core 554 555| 名称 | 值 | 说明 | 556| ------------ | --------------------- | ------------------------ | 557| VIDEO_H263 | 'video/h263' | 表示视频/h263类型。 | 558| VIDEO_AVC | 'video/avc' | 表示视频/avc类型。 | 559| VIDEO_MPEG2 | 'video/mpeg2' | 表示视频/mpeg2类型。 | 560| VIDEO_MPEG4 | 'video/mp4v-es' | 表示视频/mpeg4类型。 | 561| VIDEO_VP8 | 'video/x-vnd.on2.vp8' | 表示视频/vp8类型。 | 562| VIDEO_HEVC<sup>11+</sup> | 'video/hevc' | 表示视频/H265类型。| 563| AUDIO_AAC | 'audio/mp4a-latm' | 表示音频/mp4a-latm类型。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 564| AUDIO_VORBIS | 'audio/vorbis' | 表示音频/vorbis类型。 | 565| AUDIO_FLAC | 'audio/flac' | 表示音频/flac类型。 | 566| AUDIO_MP3<sup>12+</sup> | 'audio/mpeg' | 表示音频/mpeg类型。 | 567| AUDIO_G711MU<sup>12+</sup> | 'audio/g711mu' | 表示音频/G711-mulaw类型。 | 568| AUDIO_AMR_NB<sup>18+</sup> | 'audio/3gpp' | 表示音频/amr-nb类型。 | 569| AUDIO_AMR_WB<sup>18+</sup> | 'audio/amr-wb' | 表示音频/amr-wb类型。 | 570 571## MediaDescriptionKey<sup>8+</sup> 572 573媒体信息描述枚举。 574 575**系统能力：** SystemCapability.Multimedia.Media.Core 576 577| 名称 | 值 | 说明 | 578| ------------------------ | --------------- | ------------------------------------------------------------ | 579| MD_KEY_TRACK_INDEX | 'track_index' | 表示轨道序号，其对应键值类型为number。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 580| MD_KEY_TRACK_TYPE | 'track_type' | 表示轨道类型，其对应键值类型为number，参考[MediaType](#mediatype8)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 581| MD_KEY_CODEC_MIME | 'codec_mime' | 表示codec_mime类型，其对应键值类型为string。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 582| MD_KEY_DURATION | 'duration' | 表示媒体时长，其对应键值类型为number，单位为毫秒（ms）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 583| MD_KEY_BITRATE | 'bitrate' | 表示比特率，其对应键值类型为number，单位为比特率（bps）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 584| MD_KEY_WIDTH | 'width' | 表示视频宽度，其对应键值类型为number，单位为像素（px）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 585| MD_KEY_HEIGHT | 'height' | 表示视频高度，其对应键值类型为number，单位为像素（px）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 586| MD_KEY_FRAME_RATE | 'frame_rate' | 表示视频帧率，其对应键值类型为number，单位为每100秒的帧数。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 587| MD_KEY_AUD_CHANNEL_COUNT | 'channel_count' | 表示声道数，其对应键值类型为number。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 588| MD_KEY_AUD_SAMPLE_RATE | 'sample_rate' | 表示采样率，其对应键值类型为number，单位为赫兹（Hz）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 589| MD_KEY_AUD_SAMPLE_DEPTH<sup>12+</sup> | 'sample_depth' | 表示位深，其对应键值类型为number，单位为位（bit）。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 590| MD_KEY_LANGUAGE<sup>12+</sup> | 'language' | 表示字幕语言，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 591| MD_KEY_TRACK_NAME<sup>12+</sup> | 'track_name' | 表示track名称，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 592| MD_KEY_HDR_TYPE<sup>12+</sup> | 'hdr_type' | 表示视频轨类型，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 593 594## PlaybackInfoKey<sup>12+</sup> 595 596播放信息描述枚举。 597 598**系统能力：** SystemCapability.Multimedia.Media.Core 599 600| 名称 | 值 | 说明 | 601| ------------------------ | --------------- | ------------------------------------------------------------ | 602| SERVER_IP_ADDRESS | 'server_ip_address' | 表示服务器IP地址，其对应键值类型为string。 | 603| AVG_DOWNLOAD_RATE | 'average_download_rate'| 表示平均下载速率，其对应键值类型为number，单位为比特率（bps）。 | 604| DOWNLOAD_RATE | 'download_rate' | 表示1s的下载速率，其对应键值类型为number，单位为比特率（bps）。| 605| IS_DOWNLOADING | 'is_downloading' | 表示下载状态，1表示在下载状态，0表示非下载状态（下载完成），其对应键值类型为number。| 606| BUFFER_DURATION | 'buffer_duration' | 表示缓存数据的可播放时长，其对应键值类型为number，单位为秒（s）。| 607 608## BufferingInfoType<sup>8+</sup> 609 610缓存事件类型枚举。 611 612**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 613 614**系统能力：** SystemCapability.Multimedia.Media.Core 615 616| 名称 | 值 | 说明 | 617| ----------------- | ---- | -------------------------------- | 618| BUFFERING_START | 1 | 表示开始缓冲。当上报BUFFERING_START时，播放器会暂停播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 619| BUFFERING_END | 2 | 表示结束缓冲。当上报BUFFERING_END时，播放器会恢复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 620| BUFFERING_PERCENT | 3 | 表示缓冲百分比。可参考该事件感知缓冲进度。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 621| CACHED_DURATION | 4 | 表示已缓冲数据预估可播放时长，单位为毫秒（ms）。缓冲区中的数据变化量大于500ms，上报一次。可参考该事件做进度条。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 622 623## StateChangeReason<sup>9+</sup> 624 625表示播放或录制实例状态机切换原因的枚举，伴随state一起上报。 626 627**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 628 629**系统能力：** SystemCapability.Multimedia.Media.Core 630 631| 名称 | 值 | 说明 | 632| ---------- | ---- | ------------------------------------------------------------ | 633| USER | 1 | 表示用户行为造成的状态切换，由用户或客户端主动调用接口产生。 | 634| BACKGROUND | 2 | 表示后台系统行为造成的状态切换，比如应用未注册播控中心权限，退到后台时被系统强制暂停或停止。 | 635 636## AVPlayer<sup>9+</sup> 637 638播放管理类，用于管理和播放媒体资源。在调用AVPlayer的方法前，需要先通过[createAVPlayer()](#mediacreateavplayer9)构建一个AVPlayer实例。 639 640Audio/Video播放demo可参考：[音频播放开发指导](../../media/media/using-avplayer-for-playback.md)、[视频播放开发指导](../../media/media/video-playback.md)。 641 642> **说明：** 643> 644> 在使用AVPlayer实例的方法时，建议开发者注册相关回调，主动获取当前状态变化。 645> - [on('stateChange')](#onstatechange9)：监听播放状态机AVPlayerState切换。 646> - [on('error')](#onerror9)：监听错误事件。 647 648### 属性 649 650**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 651 652| 名称 | 类型 | 只读 | 可选 | 说明 | 653| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 654| url<sup>9+</sup> | string | 否 | 是 | 媒体URL，只允许在**idle**状态下设置。<br/>支持的视频格式(mp4、mpeg-ts、mkv)。<br>支持的音频格式(m4a、aac、mp3、ogg、wav、flac、amr)。<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开始，该接口支持在原子化服务中使用。 | 655| fdSrc<sup>9+</sup> | [AVFileDescriptor](#avfiledescriptor9) | 否 | 是 | 媒体文件描述，只允许在**idle**状态下设置。<br/>使用场景：应用中的媒体资源被连续存储在同一个文件中。<br/>支持的视频格式(mp4、mpeg-ts、mkv)。<br>支持的音频格式(m4a、aac、mp3、ogg、wav、flac、amr)。<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开始，该接口支持在原子化服务中使用。 | 656| dataSrc<sup>10+</sup> | [AVDataSrcDescriptor](#avdatasrcdescriptor10) | 否 | 是 | 流式媒体资源描述，只允许在**idle**状态下设置。<br/>使用场景：应用播放从远端下载到本地的文件，在应用未下载完整音视频资源时，提前播放已获取的资源文件。<br/>支持的视频格式(mp4、mpeg-ts、mkv)。<br>支持的音频格式(m4a、aac、mp3、ogg、wav、flac、amr)。<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开始，该接口支持在原子化服务中使用。 | 657| 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开始，该接口支持在原子化服务中使用。 | 658| loop<sup>9+</sup> | boolean | 否 | 否 | 视频循环播放属性，默认'false'，设置为'true'表示循环播放，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。<br/>直播场景不支持loop设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 659| videoScaleType<sup>9+</sup> | [VideoScaleType](#videoscaletype9) | 否 | 是 | 视频缩放模式，默认VIDEO_SCALE_TYPE_FIT，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 660| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9) | 否 | 是 | 音频焦点模型，默认SHARE_MODE，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。<br/>在第一次调用[play()](#play9)之前设置， 以便此后中断模式生效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 661| audioRendererInfo<sup>10+</sup> | [audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8) | 否 | 是 | 设置音频渲染信息。若媒体源包含视频，则usage默认值为STREAM_USAGE_MOVIE，否则usage默认值为STREAM_USAGE_MUSIC。rendererFlags默认值为0。若默认usage不满足需求，则须主动配置[audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8)。<br/>只允许在**initialized**状态下设置。<br/>在第一次调用[prepare()](#prepare9)之前设置，以便音频渲染器信息在之后生效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 662| audioEffectMode<sup>10+</sup> | [audio.AudioEffectMode](../apis-audio-kit/js-apis-audio.md#audioeffectmode10) | 否 | 是 | 设置音频音效模式，默认值为EFFECT_DEFAULT，动态属性。audioRendererInfo的usage变动时会恢复为默认值，只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 663| state<sup>9+</sup> | [AVPlayerState](#avplayerstate9) | 是 | 否 | 音视频播放的状态，全状态有效，可查询参数。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 664| currentTime<sup>9+</sup> | number | 是 | 否 | 视频的当前播放位置，单位为毫秒（ms），可查询参数。<br/>返回为(-1)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 665| duration<sup>9+</sup> | number | 是 | 否 | 视频时长，单位为毫秒（ms），可查询参数。<br/>返回为(-1)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 666| width<sup>9+</sup> | number | 是 | 否 | 视频宽，单位为像素（px），可查询参数。<br/>返回为(0)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 667| height<sup>9+</sup> | number | 是 | 否 | 视频高，单位为像素（px），可查询参数。<br/>返回为(0)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 668 669### on('stateChange')<sup>9+</sup> 670 671on(type: 'stateChange', callback: OnAVPlayerStateChangeHandle): void 672 673监听播放状态机AVPlayerState切换的事件。 674 675**原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 676 677**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 678 679**参数：** 680 681| 参数名 | 类型 | 必填 | 说明 | 682| -------- | -------- | ---- | ------------------------------------------------------------ | 683| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 684| callback | [OnAVPlayerStateChangeHandle](#onavplayerstatechangehandle12) | 是 | 状态机切换事件回调方法。 | 685 686**示例：** 687 688```ts 689avPlayer.on('stateChange', async (state: string, reason: media.StateChangeReason) => { 690 switch (state) { 691 case 'idle': 692 console.info('state idle called'); 693 break; 694 case 'initialized': 695 console.info('initialized prepared called'); 696 break; 697 case 'prepared': 698 console.info('state prepared called'); 699 break; 700 case 'playing': 701 console.info('state playing called'); 702 break; 703 case 'paused': 704 console.info('state paused called'); 705 break; 706 case 'completed': 707 console.info('state completed called'); 708 break; 709 case 'stopped': 710 console.info('state stopped called'); 711 break; 712 case 'released': 713 console.info('state released called'); 714 break; 715 case 'error': 716 console.info('state error called'); 717 break; 718 default: 719 console.info('unknown state :' + state); 720 break; 721 } 722}); 723``` 724 725### off('stateChange')<sup>9+</sup> 726 727off(type: 'stateChange', callback?: OnAVPlayerStateChangeHandle): void 728 729取消监听播放状态机[AVPlayerState](#avplayerstate9)切换的事件。 730 731**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 732 733**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 734 735**参数：** 736 737| 参数名 | 类型 | 必填 | 说明 | 738| ------ | ------ | ---- | ----------------------------------------------------- | 739| type | string | 是 | 状态机切换事件回调类型，取消注册的事件：'stateChange' | 740| callback | [OnAVPlayerStateChangeHandle](#onavplayerstatechangehandle12) | 否 | 状态机切换事件回调方法。<br/>从API version 12开始支持此参数。 | 741 742**示例：** 743 744```ts 745avPlayer.off('stateChange'); 746``` 747 748### on('error')<sup>9+</sup> 749 750on(type: 'error', callback: ErrorCallback): void 751 752监听[AVPlayer](#avplayer9)的错误事件，该事件仅用于错误提示，不需要用户停止播控动作。如果此时[AVPlayerState](#avplayerstate9)也切至error状态，用户需要通过[reset()](#reset9)或者[release()](#release9)退出播放操作。 753 754**原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 755 756**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 757 758**参数：** 759 760| 参数名 | 类型 | 必填 | 说明 | 761| -------- | -------- | ---- | ------------------------------------------------------------ | 762| type | string | 是 | 错误事件回调类型，支持的事件：'error'，用户操作和系统都会触发此事件。 | 763| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 错误事件回调方法，使用播放器的过程中发生错误，会提供错误码ID和错误信息。 | 764 765**错误码：** 766 767以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 768 769在API version 9-13，针对网络、服务器等数据流异常，接口上报5400103；从API version 14开始，对应错误细化为错误码5411001-5411011。 770 771| 错误码ID | 错误信息 | 772| -------- | --------------------- | 773| 201 | Permission denied. | 774| 401 | The parameter check failed. | 775| 801 | Capability not supported. | 776| 5400101 | No memory. | 777| 5400102 | Operation not allowed.| 778| 5400103 | I/O error. | 779| 5400104 | Time out. | 780| 5400105 | Service died. | 781| 5400106 | Unsupported format. | 782| 5411001 | IO can not find host. | 783| 5411002 | IO connection timeout. | 784| 5411003 | IO network abnormal. | 785| 5411004 | IO network unavailable. | 786| 5411005 | IO no permission. | 787| 5411006 | IO request denied. | 788| 5411007 | IO resource not found. | 789| 5411008 | IO SSL client cert needed. | 790| 5411009 | IO SSL connect fail. | 791| 5411010 | IO SSL server cert untrusted. | 792| 5411011 | IO unsupported request. | 793 794**示例：** 795 796```ts 797import { BusinessError } from '@kit.BasicServicesKit'; 798 799avPlayer.on('error', (error: BusinessError) => { 800 console.info('error happened,and error message is :' + error.message); 801 console.info('error happened,and error code is :' + error.code); 802}); 803``` 804 805### off('error')<sup>9+</sup> 806 807off(type: 'error', callback?: ErrorCallback): void 808 809取消监听播放的错误事件。 810 811**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 812 813**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 814 815**参数：** 816 817| 参数名 | 类型 | 必填 | 说明 | 818| ------ | ------ | ---- | ----------------------------------------- | 819| type | string | 是 | 错误事件回调类型，取消注册的事件：'error' | 820| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 错误事件回调方法，使用播放器的过程中发生错误，会提供错误码ID和错误信息。<br/>从API version 12开始支持此参数。 | 821 822**示例：** 823 824```ts 825avPlayer.off('error'); 826``` 827 828### setMediaSource<sup>12+</sup> 829 830setMediaSource(src:MediaSource, strategy?: PlaybackStrategy): Promise\<void> 831 832流媒体预下载资源设置，下载url对应的流媒体数据，并暂存在内存中。[视频播放开发指导](../../media/media/video-playback.md)。通过Promise获取返回值。 833 834**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 835 836**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 837 838**参数：** 839 840| 参数名 | 类型 | 必填 | 说明 | 841| -------- | -------- | ---- | -------------------- | 842| src | [MediaSource](#mediasource12) | 是 | 流媒体预下载媒体来源。 | 843| strategy | [PlaybackStrategy](#playbackstrategy12) | 否 | 流媒体预下载播放策略。 | 844 845**返回值：** 846 847| 类型 | 说明 | 848| -------------- | ------------------------------------------ | 849| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 850 851**错误码：** 852 853以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 854 855| 错误码ID | 错误信息 | 856| -------- | ----------------------------------------- | 857| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 858| 5400102 | Operation not allowed. Return by promise. | 859 860**示例：** 861 862<!--code_no_check--> 863```ts 864let player = await media.createAVPlayer(); 865let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 866let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 867let playStrategy : media.PlaybackStrategy = { 868 preferredWidth: 1, 869 preferredHeight: 2, 870 preferredBufferDuration: 3, 871 preferredHdr: false, 872 preferredBufferDurationForPlaying: 1, 873 thresholdForAutoQuickPlay: 5 874}; 875player.setMediaSource(mediaSource, playStrategy); 876``` 877 878### setPlaybackStrategy<sup>12+</sup> 879 880setPlaybackStrategy(strategy: PlaybackStrategy): Promise\<void> 881 882设置播放策略，只能在initialized状态下调用。 883 884**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 885 886**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 887 888**参数：** 889 890| 参数名 | 类型 | 必填 | 说明 | 891| -------- | -------- | ---- | -------------------- | 892| strategy | [PlaybackStrategy](#playbackstrategy12) | 是 | 播放策略。 | 893 894**返回值：** 895 896| 类型 | 说明 | 897| -------------- | ------------------------------------ | 898| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 899 900**错误码：** 901 902以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 903 904| 错误码ID | 错误信息 | 905| -------- | ----------------------------------------- | 906| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. | 907| 5400102 | Operation not allowed. Return by promise. | 908 909**示例：** 910 911<!--code_no_check--> 912```ts 913import { common } from '@kit.AbilityKit'; 914 915private context: Context | undefined; 916constructor(context: Context) { 917 this.context = context; // this.getUIContext().getHostContext(); 918} 919 920let player = await media.createAVPlayer(); 921let fileDescriptor = await this.context.resourceManager.getRawFd('xxx.mp4'); 922player.fdSrc = fileDescriptor 923let playStrategy : media.PlaybackStrategy = { 924 preferredWidth: 1, 925 preferredHeight: 2, 926 preferredBufferDuration: 3, 927 preferredHdr: false, 928 mutedMediaType: media.MediaType.MEDIA_TYPE_AUD, 929 preferredBufferDurationForPlaying: 1, 930 thresholdForAutoQuickPlay: 5 931}; 932player.setPlaybackStrategy(playStrategy); 933``` 934 935### setPlaybackRange<sup>18+</sup> 936 937setPlaybackRange(startTimeMs: number, endTimeMs: number, mode?: SeekMode) : Promise\<void> 938 939设置播放区间，并通过指定的[SeekMode](#seekmode8)跳转到区间开始位置。设置之后，只播放音视频文件设定区间内的内容。该方法异步方式返回执行结果，通过Promise获取返回值。可在**initialized**/**prepared**/**paused**/**stopped**/**completed**状态下使用。 940 941**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 942 943**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 944 945**参数：** 946 947| 参数名 | 类型 | 必填 | 说明 | 948| -------- | ---------------------- | ---- | --------------------------- | 949| startTimeMs | number | 是 | 区间开始位置，单位ms，取值[0, duration)。可以设置-1值，系统将会从0位置开始播放。| 950| endTimeMs | number | 是 | 区间结束位置，单位ms，取值(startTimeMs, duration]。可以设置-1值，系统将会播放到资源末尾。| 951| mode | [SeekMode](#seekmode8) | 否 | 支持SeekMode.SEEK_PREV_SYNC和SeekMode.SEEK_CLOSEST, <br/>默认值: SeekMode.SEEK_PREV_SYNC。| 952 953**错误码：** 954 955以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 956 957| 错误码ID | 错误信息 | 958| -------- | ------------------------------------------ | 959| 401 | The parameter check failed. Return by promise. | 960| 5400102 | Operation not allowed. Return by promise. | 961 962**示例：** 963 964```ts 965import { media } from '@kit.MediaKit'; 966import { BusinessError } from '@kit.BasicServicesKit'; 967 968avPlayer.setPlaybackRange(0, 6000, media.SeekMode.SEEK_CLOSEST).then(() => { 969 console.info('Succeeded setPlaybackRange'); 970}).catch((err: BusinessError) => { 971 console.error('Failed to setPlaybackRange' + err.message); 972}); 973``` 974 975### prepare<sup>9+</sup> 976 977prepare(callback: AsyncCallback\<void>): void 978 979准备播放音频/视频，需在[stateChange](#onstatechange9)事件成功触发至initialized状态后，才能调用。使用callback方式异步获取返回值。 980 981**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 982 983**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 984 985**参数：** 986 987| 参数名 | 类型 | 必填 | 说明 | 988| -------- | -------- | ---- | -------------------- | 989| callback | AsyncCallback\<void> | 是 | 准备播放的回调方法。 | 990 991**错误码：** 992 993以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 994 995| 错误码ID | 错误信息 | 996| -------- | ------------------------------------------ | 997| 5400102 | Operation not allowed. Return by callback. | 998| 5400106 | Unsupported format. Return by callback. | 999 1000**示例：** 1001 1002```ts 1003import { BusinessError } from '@kit.BasicServicesKit'; 1004 1005avPlayer.prepare((err: BusinessError) => { 1006 if (err) { 1007 console.error('Failed to prepare,error message is :' + err.message); 1008 } else { 1009 console.info('Succeeded in preparing'); 1010 } 1011}); 1012``` 1013 1014### prepare<sup>9+</sup> 1015 1016prepare(): Promise\<void> 1017 1018准备播放音频/视频，需在[stateChange](#onstatechange9)事件成功触发至initialized状态后，才能调用。通过Promise获取返回值。 1019 1020如果应用使用到多个短视频频繁切换的场景，为了提升切换性能，可以考虑创建多个AVPlayer对象，提前准备下一个视频，详情参见[在线短视频流畅切换](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-smooth-switching)。 1021 1022**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1023 1024**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1025 1026**返回值：** 1027 1028| 类型 | 说明 | 1029| -------------- | ------------------------- | 1030| Promise\<void> | 准备播放的Promise返回值。 | 1031 1032**错误码：** 1033 1034以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1035 1036| 错误码ID | 错误信息 | 1037| -------- | ----------------------------------------- | 1038| 5400102 | Operation not allowed. Return by promise. | 1039| 5400106 | Unsupported format. Return by promise. | 1040 1041**示例：** 1042 1043```ts 1044import { BusinessError } from '@kit.BasicServicesKit'; 1045 1046avPlayer.prepare().then(() => { 1047 console.info('Succeeded in preparing'); 1048}, (err: BusinessError) => { 1049 console.error('Failed to prepare,error message is :' + err.message); 1050}); 1051``` 1052 1053### setMediaMuted<sup>12+</sup> 1054 1055setMediaMuted(mediaType: MediaType, muted: boolean ): Promise\<void> 1056 1057设置音频静音/取消音频静音。只能在prepared/playing/paused/completed状态下调用。仅支持设置mediaType为音频格式。 1058 1059**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1060 1061**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1062 1063**参数：** 1064 1065| 参数名 | 类型 | 必填 | 说明 | 1066| -------- | -------- | ---- | -------------------- | 1067| mediaType | [MediaType](#mediatype8) | 是 | 播放策略。 | 1068| muted | boolean | 是 | 是否静音播放。true表示是静音播放，false表示不是静音播放。| 1069 1070**返回值：** 1071 1072| 类型 | 说明 | 1073| -------------- | ------------------------- | 1074| Promise\<void> | 准备播放的Promise返回值。 | 1075 1076**错误码：** 1077 1078以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1079 1080| 错误码ID | 错误信息 | 1081| -------- | ----------------------------------------- | 1082| 401 | The parameter check failed. Return by promise. | 1083| 5400102 | Operation not allowed. Return by promise. | 1084 1085**示例：** 1086 1087```ts 1088import { BusinessError } from '@kit.BasicServicesKit'; 1089 1090avPlayer.prepare().then(() => { 1091 console.info('Succeeded in preparing'); 1092 avPlayer.setMediaMuted(media.MediaType.MEDIA_TYPE_AUD, true); 1093}, (err: BusinessError) => { 1094 console.error('Failed to prepare,error message is :' + err.message); 1095}); 1096``` 1097 1098### play<sup>9+</sup> 1099 1100play(callback: AsyncCallback\<void>): void 1101 1102开始播放音视频资源，只能在prepared/paused/completed状态调用。使用callback方式异步获取返回值。 1103 1104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1105 1106**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1107 1108**参数：** 1109 1110| 参数名 | 类型 | 必填 | 说明 | 1111| -------- | -------- | ---- | -------------------- | 1112| callback | AsyncCallback\<void> | 是 | 开始播放的回调方法。 | 1113 1114**错误码：** 1115 1116以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1117 1118| 错误码ID | 错误信息 | 1119| -------- | ------------------------------------------ | 1120| 5400102 | Operation not allowed. Return by callback. | 1121 1122**示例：** 1123 1124```ts 1125import { BusinessError } from '@kit.BasicServicesKit'; 1126 1127avPlayer.play((err: BusinessError) => { 1128 if (err) { 1129 console.error('Failed to play,error message is :' + err.message); 1130 } else { 1131 console.info('Succeeded in playing'); 1132 } 1133}); 1134``` 1135 1136### play<sup>9+</sup> 1137 1138play(): Promise\<void> 1139 1140开始播放音视频资源，只能在prepared/paused/completed状态调用。通过Promise获取返回值。 1141 1142**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1143 1144**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1145 1146**返回值：** 1147 1148| 类型 | 说明 | 1149| -------------- | ------------------------- | 1150| Promise\<void> | 开始播放的Promise返回值。 | 1151 1152**错误码：** 1153 1154以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1155 1156| 错误码ID | 错误信息 | 1157| -------- | ----------------------------------------- | 1158| 5400102 | Operation not allowed. Return by promise. | 1159 1160**示例：** 1161 1162```ts 1163import { BusinessError } from '@kit.BasicServicesKit'; 1164 1165avPlayer.play().then(() => { 1166 console.info('Succeeded in playing'); 1167}, (err: BusinessError) => { 1168 console.error('Failed to play,error message is :' + err.message); 1169}); 1170``` 1171 1172### pause<sup>9+</sup> 1173 1174pause(callback: AsyncCallback\<void>): void 1175 1176暂停播放音视频资源，只能在playing状态调用。使用callback方式异步获取返回值。 1177 1178**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1179 1180**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1181 1182**参数：** 1183 1184| 参数名 | 类型 | 必填 | 说明 | 1185| -------- | -------- | ---- | -------------------- | 1186| callback | AsyncCallback\<void> | 是 | 暂停播放的回调方法。 | 1187 1188**错误码：** 1189 1190以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1191 1192| 错误码ID | 错误信息 | 1193| -------- | ------------------------------------------ | 1194| 5400102 | Operation not allowed. Return by callback. | 1195 1196**示例：** 1197 1198```ts 1199import { BusinessError } from '@kit.BasicServicesKit'; 1200 1201avPlayer.pause((err: BusinessError) => { 1202 if (err) { 1203 console.error('Failed to pause,error message is :' + err.message); 1204 } else { 1205 console.info('Succeeded in pausing'); 1206 } 1207}); 1208``` 1209 1210### pause<sup>9+</sup> 1211 1212pause(): Promise\<void> 1213 1214暂停播放音视频资源，只能在playing状态调用。通过Promise获取返回值。 1215 1216**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1217 1218**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1219 1220**返回值：** 1221 1222| 类型 | 说明 | 1223| -------------- | ------------------------- | 1224| Promise\<void> | 暂停播放的Promise返回值。 | 1225 1226**错误码：** 1227 1228以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1229 1230| 错误码ID | 错误信息 | 1231| -------- | ----------------------------------------- | 1232| 5400102 | Operation not allowed. Return by promise. | 1233 1234**示例：** 1235 1236```ts 1237import { BusinessError } from '@kit.BasicServicesKit'; 1238 1239avPlayer.pause().then(() => { 1240 console.info('Succeeded in pausing'); 1241}, (err: BusinessError) => { 1242 console.error('Failed to pause,error message is :' + err.message); 1243}); 1244``` 1245 1246### stop<sup>9+</sup> 1247 1248stop(callback: AsyncCallback\<void>): void 1249 1250停止播放音视频资源，只能在prepared/playing/paused/completed状态调用。使用callback方式异步获取返回值。 1251 1252**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1253 1254**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1255 1256**参数：** 1257 1258| 参数名 | 类型 | 必填 | 说明 | 1259| -------- | -------- | ---- | -------------------- | 1260| callback | AsyncCallback\<void> | 是 | 停止播放的回调方法。 | 1261 1262**错误码：** 1263 1264以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1265 1266| 错误码ID | 错误信息 | 1267| -------- | ------------------------------------------ | 1268| 5400102 | Operation not allowed. Return by callback. | 1269 1270**示例：** 1271 1272```ts 1273import { BusinessError } from '@kit.BasicServicesKit'; 1274 1275avPlayer.stop((err: BusinessError) => { 1276 if (err) { 1277 console.error('Failed to stop,error message is :' + err.message); 1278 } else { 1279 console.info('Succeeded in stopping'); 1280 } 1281}); 1282``` 1283 1284### stop<sup>9+</sup> 1285 1286stop(): Promise\<void> 1287 1288停止播放音视频资源，只能在prepared/playing/paused/completed状态调用。通过Promise获取返回值。 1289 1290**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1291 1292**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1293 1294**返回值：** 1295 1296| 类型 | 说明 | 1297| -------------- | ------------------------- | 1298| Promise\<void> | 停止播放的Promise返回值。 | 1299 1300**错误码：** 1301 1302以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1303 1304| 错误码ID | 错误信息 | 1305| -------- | ----------------------------------------- | 1306| 5400102 | Operation not allowed. Return by promise. | 1307 1308**示例：** 1309 1310```ts 1311import { BusinessError } from '@kit.BasicServicesKit'; 1312 1313avPlayer.stop().then(() => { 1314 console.info('Succeeded in stopping'); 1315}, (err: BusinessError) => { 1316 console.error('Failed to stop,error message is :' + err.message); 1317}); 1318``` 1319 1320### reset<sup>9+</sup> 1321 1322reset(callback: AsyncCallback\<void>): void 1323 1324重置播放，只能在initialized/prepared/playing/paused/completed/stopped/error状态调用。使用callback方式异步获取返回值。 1325 1326**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1327 1328**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1329 1330**参数：** 1331 1332| 参数名 | 类型 | 必填 | 说明 | 1333| -------- | -------- | ---- | -------------------- | 1334| callback | AsyncCallback\<void> | 是 | 重置播放的回调方法。 | 1335 1336**错误码：** 1337 1338以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1339 1340| 错误码ID | 错误信息 | 1341| -------- | ------------------------------------------ | 1342| 5400102 | Operation not allowed. Return by callback. | 1343 1344**示例：** 1345 1346```ts 1347import { BusinessError } from '@kit.BasicServicesKit'; 1348 1349avPlayer.reset((err: BusinessError) => { 1350 if (err) { 1351 console.error('Failed to reset,error message is :' + err.message); 1352 } else { 1353 console.info('Succeeded in resetting'); 1354 } 1355}); 1356``` 1357 1358### reset<sup>9+</sup> 1359 1360reset(): Promise\<void> 1361 1362重置播放，只能在initialized/prepared/playing/paused/completed/stopped/error状态调用。通过Promise获取返回值。 1363 1364**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1365 1366**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1367 1368**返回值：** 1369 1370| 类型 | 说明 | 1371| -------------- | ------------------------- | 1372| Promise\<void> | 重置播放的Promise返回值。 | 1373 1374**错误码：** 1375 1376以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1377 1378| 错误码ID | 错误信息 | 1379| -------- | ----------------------------------------- | 1380| 5400102 | Operation not allowed. Return by promise. | 1381 1382**示例：** 1383 1384```ts 1385import { BusinessError } from '@kit.BasicServicesKit'; 1386 1387avPlayer.reset().then(() => { 1388 console.info('Succeeded in resetting'); 1389}, (err: BusinessError) => { 1390 console.error('Failed to reset,error message is :' + err.message); 1391}); 1392``` 1393 1394### release<sup>9+</sup> 1395 1396release(callback: AsyncCallback\<void>): void 1397 1398销毁播放资源，除released状态外，均可以调用。使用callback方式异步获取返回值。 1399 1400**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1401 1402**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1403 1404**参数：** 1405 1406| 参数名 | 类型 | 必填 | 说明 | 1407| -------- | -------- | ---- | -------------------- | 1408| callback | AsyncCallback\<void> | 是 | 销毁播放的回调方法。 | 1409 1410**错误码：** 1411 1412以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1413 1414| 错误码ID | 错误信息 | 1415| -------- | ------------------------------------------ | 1416| 5400102 | Operation not allowed. Return by callback. | 1417 1418**示例：** 1419 1420```ts 1421import { BusinessError } from '@kit.BasicServicesKit'; 1422 1423avPlayer.release((err: BusinessError) => { 1424 if (err) { 1425 console.error('Failed to release,error message is :' + err.message); 1426 } else { 1427 console.info('Succeeded in releasing'); 1428 } 1429}); 1430``` 1431 1432### release<sup>9+</sup> 1433 1434release(): Promise\<void> 1435 1436销毁播放资源，除released状态，都可以调用。通过Promise获取返回值。 1437 1438**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1439 1440**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1441 1442**返回值：** 1443 1444| 类型 | 说明 | 1445| -------------- | ------------------------- | 1446| Promise\<void> | 销毁播放的Promise返回值。 | 1447 1448**错误码：** 1449 1450以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1451 1452| 错误码ID | 错误信息 | 1453| -------- | ----------------------------------------- | 1454| 5400102 | Operation not allowed. Return by promise. | 1455 1456**示例：** 1457 1458```ts 1459import { BusinessError } from '@kit.BasicServicesKit'; 1460 1461avPlayer.release().then(() => { 1462 console.info('Succeeded in releasing'); 1463}, (err: BusinessError) => { 1464 console.error('Failed to release,error message is :' + err.message); 1465}); 1466``` 1467 1468### getTrackDescription<sup>9+</sup> 1469 1470getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 1471 1472获取音视频轨道信息，可以在prepared/playing/paused状态调用。获取所有音视轨道信息，应在数据加载回调后调用。使用callback方式异步获取返回值。 1473 1474**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1475 1476**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1477 1478**参数：** 1479 1480| 参数名 | 类型 | 必填 | 说明 | 1481| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1482| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是 | 回调函数，当获取音视频轨道信息成功，err为undefined，data为获取到的MediaDescription数组；否则为错误对象。| 1483 1484**错误码：** 1485 1486以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1487 1488| 错误码ID | 错误信息 | 1489| -------- | ------------------------------------------ | 1490| 5400102 | Operation not allowed. Return by callback. | 1491 1492**示例：** 1493 1494```ts 1495import { BusinessError } from '@kit.BasicServicesKit'; 1496 1497avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1498 if ((arrList) != null) { 1499 console.info('Succeeded in doing getTrackDescription'); 1500 } else { 1501 console.error(`Failed to do getTrackDescription, error:${error}`); 1502 } 1503}); 1504``` 1505 1506### getTrackDescription<sup>9+</sup> 1507 1508getTrackDescription(): Promise\<Array\<MediaDescription>> 1509 1510获取音视频轨道信息，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1511 1512**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1513 1514**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1515 1516**返回值：** 1517 1518| 类型 | 说明 | 1519| ------------------------------------------------------ | ------------------------------------------------- | 1520| Promise<Array<[MediaDescription](#mediadescription8)>> | Promise对象，返回音视频轨道信息MediaDescription数组。 | 1521 1522**错误码：** 1523 1524以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1525 1526| 错误码ID | 错误信息 | 1527| -------- | ----------------------------------------- | 1528| 5400102 | Operation not allowed. Return by promise. | 1529 1530**示例：** 1531 1532```ts 1533import { BusinessError } from '@kit.BasicServicesKit'; 1534 1535avPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 1536 console.info('Succeeded in getting TrackDescription'); 1537}).catch((error: BusinessError) => { 1538 console.error(`Failed to get TrackDescription, error:${error}`); 1539}); 1540``` 1541 1542### getSelectedTracks<sup>12+</sup> 1543 1544getSelectedTracks(): Promise\<Array\<number>> 1545 1546获取已选择的音视频轨道索引，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1547 1548**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1549 1550**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1551 1552**返回值：** 1553 1554| 类型 | 说明 | 1555| ------------------------------------------------------ | ------------------------------------------------- | 1556| Promise\<Array\<number>> | Promise对象，返回已选择音视频轨道索引数组。 | 1557 1558**错误码：** 1559 1560以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1561 1562| 错误码ID | 错误信息 | 1563| -------- | ----------------------------------------- | 1564| 5400102 | Operation not allowed. | 1565 1566**示例：** 1567 1568```ts 1569import { BusinessError } from '@kit.BasicServicesKit'; 1570 1571avPlayer.getSelectedTracks().then((arrList: Array<number>) => { 1572 console.info('Succeeded in getting SelectedTracks'); 1573}).catch((error: BusinessError) => { 1574 console.error(`Failed to get SelectedTracks, error:${error}`); 1575}); 1576``` 1577 1578### getPlaybackInfo<sup>12+</sup> 1579 1580getPlaybackInfo(): Promise\<PlaybackInfo> 1581 1582获取播放过程信息，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1583 1584**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1585 1586**返回值：** 1587 1588| 类型 | 说明 | 1589| ------------------------------------------------------ | ------------------------------------------------- | 1590| Promise<[PlaybackInfo](#playbackinfo12)> | Promise对象，返回播放器信息PlaybackInfo。 | 1591 1592**示例：** 1593 1594```ts 1595import { BusinessError } from '@kit.BasicServicesKit'; 1596 1597let avPlayer: media.AVPlayer | undefined = undefined; 1598let playbackInfo: media.PlaybackInfo | undefined = undefined; 1599media.createAVPlayer(async (err: BusinessError, player: media.AVPlayer) => { 1600 if (player != null) { 1601 avPlayer = player; 1602 console.info(`Succeeded in creating AVPlayer`); 1603 if (avPlayer) { 1604 try { 1605 playbackInfo = await avPlayer.getPlaybackInfo(); 1606 console.info(`AVPlayer getPlaybackInfo = ${JSON.stringify(playbackInfo)}`); // 打印整个PlaybackInfo的值。 1607 } catch (error) { 1608 console.error(`error = ${error}`); 1609 } 1610 } 1611 } else { 1612 console.error(`Failed to create AVPlayer, error message:${err.message}`); 1613 } 1614}); 1615``` 1616 1617### getPlaybackPosition<sup>18+</sup> 1618 1619getPlaybackPosition(): number 1620 1621获取当前播放位置，可以在prepared/playing/paused/completed状态调用。 1622 1623**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1624 1625**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1626 1627**返回值：** 1628 1629| 类型 | 说明 | 1630| ------------------------------------------------------ | ------------------------------------------------- | 1631| number | 返回当前播放位置的时间，单位：毫秒（ms）。| 1632 1633**错误码：** 1634 1635以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1636 1637| 错误码ID | 错误信息 | 1638| -------- | ----------------------------------------- | 1639| 5400102 | Operation not allowed. | 1640 1641**示例：** 1642 1643```ts 1644import { BusinessError } from '@kit.BasicServicesKit'; 1645 1646avPlayer.prepare().then(() => { 1647 console.info('Succeeded in preparing'); 1648 let playbackPosition: number = avPlayer.getPlaybackPosition(); 1649 console.info(`AVPlayer getPlaybackPosition== ${playbackPosition}`); 1650}, (err: BusinessError) => { 1651 console.error('Failed to prepare,error message is :' + err.message); 1652}); 1653``` 1654 1655### selectTrack<sup>12+</sup> 1656 1657selectTrack(index: number, mode?: SwitchMode): Promise\<void> 1658 1659使用AVPlayer播放多音视频轨资源时，选择指定轨道播放，通过Promise获取返回值。 1660 1661**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1662 1663**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1664 1665**参数：** 1666 1667| 参数名 | 类型 | 必填 | 说明 | 1668| -------- | -------- | ---- | -------------------- | 1669| index | number | 是 | 多音视频资源的轨道索引，可通过[getTrackDescription](#gettrackdescription9-1)接口获取当前资源的所有轨道信息[MediaDescription](#mediadescription8)。 | 1670| mode | [SwitchMode](#switchmode12) | 否 | 切换视频轨道模式，默认为SMOOTH模式，**仅在DASH协议网络流视频轨切换时生效**，其他场景当前暂不支持。 | 1671 1672**返回值：** 1673 1674| 类型 | 说明 | 1675| -------------- | ------------------------- | 1676| Promise\<void> | 选择轨道完成的Promise返回值。 | 1677 1678**错误码：** 1679 1680以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1681 1682| 错误码ID | 错误信息 | 1683| -------- | ----------------------------------------- | 1684| 401 | The parameter check failed. Return by promise. | 1685| 5400102 | Operation not allowed. Return by promise. | 1686 1687**示例：** 1688 1689<!--code_no_check--> 1690```ts 1691import { BusinessError } from '@kit.BasicServicesKit'; 1692 1693let avPlayer: media.AVPlayer = await media.createAVPlayer(); 1694let audioTrackIndex: Object = 0; 1695avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1696 if (arrList != null) { 1697 for (let i = 0; i < arrList.length; i++) { 1698 if (i != 0) { 1699 // 获取音频轨道列表。 1700 audioTrackIndex = arrList[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 1701 } 1702 } 1703 } else { 1704 console.error(`Failed to get TrackDescription, error:${error}`); 1705 } 1706}); 1707 1708// 选择其中一个音频轨道。 1709avPlayer.selectTrack(parseInt(audioTrackIndex.toString())); 1710``` 1711 1712### deselectTrack<sup>12+</sup> 1713 1714deselectTrack(index: number): Promise\<void> 1715 1716使用AVPlayer播放多音轨视频时取消指定音视频轨道播放，通过Promise获取返回值。 1717 1718**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1719 1720**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1721 1722**参数：** 1723 1724| 参数名 | 类型 | 必填 | 说明 | 1725| -------- | -------- | ---- | -------------------- | 1726| index | number | 是 | 多音视频资源的轨道索引，来自[getTrackDescription](#gettrackdescription9-1)接口所获取的轨道信息[MediaDescription](#mediadescription8)。 | 1727 1728**返回值：** 1729 1730| 类型 | 说明 | 1731| -------------- | ------------------------- | 1732| Promise\<void> | 取消选择曲目完成的Promise返回值。 | 1733 1734**错误码：** 1735 1736以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1737 1738| 错误码ID | 错误信息 | 1739| -------- | ----------------------------------------- | 1740| 401 | The parameter check failed. Return by promise. | 1741| 5400102 | Operation not allowed. Return by promise. | 1742 1743**示例：** 1744 1745<!--code_no_check--> 1746```ts 1747import { BusinessError } from '@kit.BasicServicesKit'; 1748 1749let avPlayer: media.AVPlayer = await media.createAVPlayer(); 1750let audioTrackIndex: Object = 0; 1751avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1752 if (arrList != null) { 1753 for (let i = 0; i < arrList.length; i++) { 1754 if (i != 0) { 1755 // 获取音频轨道列表。 1756 audioTrackIndex = arrList[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 1757 } 1758 } 1759 } else { 1760 console.error(`Failed to get TrackDescription, error:${error}`); 1761 } 1762}); 1763 1764// 选择其中一个音频轨道。 1765avPlayer.selectTrack(parseInt(audioTrackIndex.toString())); 1766// 取消选择上次选中的音频轨道，并恢复到默认音频轨道。 1767avPlayer.deselectTrack(parseInt(audioTrackIndex.toString())); 1768``` 1769 1770### setDecryptionConfig<sup>11+</sup> 1771 1772setDecryptionConfig(mediaKeySession: drm.MediaKeySession, secureVideoPath: boolean): void 1773 1774设置解密配置。当收到[mediaKeySystemInfoUpdate事件](#onmediakeysysteminfoupdate11)时，需根据事件上报的信息创建相关配置并设置解密配置，否则无法播放。 1775 1776**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1777 1778**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1779 1780**参数：** 1781 1782| 参数名 | 类型 | 必填 | 说明 | 1783| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1784| mediaKeySession | [drm.MediaKeySession](../apis-drm-kit/arkts-apis-drm-MediaKeySession.md) | 是 | 解密会话 | 1785| secureVideoPath | boolean | 是 | 安全视频通路，true表示选择安全视频通路，false表示选择非安全视频通路 | 1786 1787**错误码：** 1788 1789以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1790 1791| 错误码ID | 错误信息 | 1792| -------- | ----------------------------------------- | 1793| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1794 1795**示例：** 1796 1797关于drm模块的示例具体可见[@ohos.multimedia.drm](../apis-drm-kit/arkts-apis-drm.md)。 1798```ts 1799import { drm } from '@kit.DrmKit'; 1800 1801// 创建MediaKeySystem系统。 1802let keySystem:drm.MediaKeySystem = drm.createMediaKeySystem('com.clearplay.drm'); 1803// 创建MediaKeySession解密会话。 1804let keySession:drm.MediaKeySession = keySystem.createMediaKeySession(drm.ContentProtectionLevel.CONTENT_PROTECTION_LEVEL_SW_CRYPTO); 1805// 生成许可证请求、设置许可证响应等。 1806// 安全视频通路标志。 1807let secureVideoPath:boolean = false; 1808// 设置解密配置。 1809avPlayer.setDecryptionConfig(keySession, secureVideoPath); 1810``` 1811 1812### getMediaKeySystemInfos<sup>11+</sup> 1813 1814getMediaKeySystemInfos(): Array\<drm.MediaKeySystemInfo> 1815 1816获取当前播放的媒体资源的MediaKeySystemInfo。需要在[mediaKeySystemInfoUpdate事件](#onmediakeysysteminfoupdate11)触发成功后才能调用。 1817 1818**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1819 1820**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1821 1822**返回值：** 1823 1824| 类型 | 说明 | 1825| ------------------------------------------------------ | ------------------------------------------------- | 1826| Array<[drm.MediaKeySystemInfo](../apis-drm-kit/arkts-apis-drm-i.md#mediakeysysteminfo)> | MediaKeySystemInfo数组，MediaKeySystemInfo具有uuid和pssh两个属性。 | 1827 1828**示例：** 1829 1830```ts 1831import { drm } from '@kit.DrmKit'; 1832 1833const infos = avPlayer.getMediaKeySystemInfos(); 1834console.info('GetMediaKeySystemInfos count: ' + infos.length); 1835for (let i = 0; i < infos.length; i++) { 1836 console.info('GetMediaKeySystemInfos uuid: ' + infos[i]["uuid"]); 1837 console.info('GetMediaKeySystemInfos pssh: ' + infos[i]["pssh"]); 1838} 1839``` 1840 1841### seek<sup>9+</sup> 1842 1843seek(timeMs: number, mode?:SeekMode): void 1844 1845跳转到指定播放位置，只能在prepared/playing/paused/completed状态调用，可以通过[seekDone事件](#onseekdone9)确认是否生效。 1846注：直播场景不支持seek。 1847 1848**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1849 1850**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1851 1852**参数：** 1853 1854| 参数名 | 类型 | 必填 | 说明 | 1855| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 1856| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, [duration](#属性)]。SEEK_CONTINUOU模式可以额外取值-1，用于表示SEEK_CONTINUOUS模式结束。 | 1857| mode | [SeekMode](#seekmode8) | 否 | 基于视频I帧的跳转模式，默认为SEEK_PREV_SYNC模式，**仅在视频资源播放时设置**。 | 1858 1859**示例：** 1860 1861```ts 1862let seekTime: number = 1000; 1863avPlayer.seek(seekTime, media.SeekMode.SEEK_PREV_SYNC); 1864``` 1865 1866```ts 1867// SEEK_CONTINUOUS 可以结合Slider的onChange回调方法进行对应处理，当slideMode为Moving时，触发拖动过程的SeekContinuous。 1868let slideMovingTime: number = 2000; 1869avPlayer.seek(slideMovingTime, media.SeekMode.SEEK_CONTINUOUS); 1870 1871// 当slideMode为End时，调用seek(-1, media.SeekMode.SEEK_CONTINUOUS)结束seek。 1872avPlayer.seek(-1, media.SeekMode.SEEK_CONTINUOUS); 1873``` 1874 1875### isSeekContinuousSupported<sup>18+</sup> 1876 1877isSeekContinuousSupported() : boolean 1878 1879查询媒体源是否支持以SEEK_CONTINUOUS模式[SeekMode](#seekmode8)进行[seek](#seek9)，在prepared/playing/paused/completed状态调用返回实际值，其余状态调用返回false。对于不支持SEEK_CONTINUOUS模式进行seek的设备，返回false。 1880 1881**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1882 1883**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1884 1885**返回值：** 1886 1887| 类型 | 说明 | 1888| -------------- | ------------------------------------------ | 1889| boolean | 媒体源是否支持以SEEK_CONTINUOUS模式进行seek。 | 1890 1891**示例：** 1892 1893```ts 1894let isSupported = avPlayer.isSeekContinuousSupported(); 1895``` 1896 1897### on('seekDone')<sup>9+</sup> 1898 1899on(type: 'seekDone', callback: Callback\<number>): void 1900 1901监听seek生效的事件。 1902 1903**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1904 1905**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1906 1907**参数：** 1908 1909| 参数名 | 类型 | 必填 | 说明 | 1910| -------- | -------- | ---- | ------------------------------------------------------------ | 1911| type | string | 是 | seek生效的事件回调类型，支持的事件：'seekDone'，除SEEK_CONTINUOUS外的[SeekMode](#seekmode8)每次调用seek后都会回调此事件。 | 1912| callback | Callback\<number> | 是 | 回调函数。seek生效的事件回调方法，只会上报用户请求的time位置。<br/>**视频播放：**[SeekMode](#seekmode8)会造成实际跳转位置与用户设置产生偏差，精准位置需要通过currentTime获取，事件回调的time仅代表完成用户某一次请求。 | 1913 1914**示例：** 1915 1916```ts 1917avPlayer.on('seekDone', (seekDoneTime:number) => { 1918 console.info('seekDone called,and seek time is:' + seekDoneTime); 1919}); 1920``` 1921 1922### off('seekDone')<sup>9+</sup> 1923 1924off(type: 'seekDone', callback?: Callback\<number>): void 1925 1926取消监听seek生效的事件。 1927 1928**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1929 1930**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1931 1932**参数：** 1933 1934| 参数名 | 类型 | 必填 | 说明 | 1935| ------ | ------ | ---- | ---------------------------------------------------- | 1936| type | string | 是 | seek生效的事件回调类型，取消注册的事件：'seekDone'。 | 1937| callback | Callback\<number> | 否 | 回调函数。seek生效的事件回调方法，只会上报用户请求的time位置。<br/>**视频播放：**[SeekMode](#seekmode8)会造成实际跳转位置与用户设置产生偏差，精准位置需要通过currentTime获取，事件回调的time仅代表完成用户某一次请求。<br/>从API version 12开始支持此参数。 | 1938 1939**示例：** 1940 1941```ts 1942avPlayer.off('seekDone'); 1943``` 1944 1945### setSpeed<sup>9+</sup> 1946 1947setSpeed(speed: PlaybackSpeed): void 1948 1949设置倍速模式，只能在prepared/playing/paused/completed状态调用，可以通过[speedDone事件](#onspeeddone9)确认是否生效。 1950注：直播场景不支持setSpeed。 1951 1952**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1953 1954**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1955 1956**参数：** 1957 1958| 参数名 | 类型 | 必填 | 说明 | 1959| ------ | -------------------------------- | ---- | ------------------ | 1960| speed | [PlaybackSpeed](#playbackspeed8) | 是 | 指定播放倍速模式。 | 1961 1962**示例：** 1963 1964```ts 1965avPlayer.setSpeed(media.PlaybackSpeed.SPEED_FORWARD_2_00_X); 1966``` 1967 1968### on('speedDone')<sup>9+</sup> 1969 1970on(type: 'speedDone', callback: Callback\<number>): void 1971 1972监听setSpeed生效的事件 1973 1974**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1975 1976**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1977 1978**参数：** 1979 1980| 参数名 | 类型 | 必填 | 说明 | 1981| -------- | -------- | ---- | ------------------------------------------------------------ | 1982| type | string | 是 | setSpeed生效的事件回调类型，支持的事件：'speedDone'，每次调用setSpeed后都会回调此事件。 | 1983| callback | Callback\<number> | 是 | 回调函数。当setSpeed成功，上报生效的倍速模式，具体见[PlaybackSpeed](#playbackspeed8)。 | 1984 1985**示例：** 1986 1987```ts 1988avPlayer.on('speedDone', (speed:number) => { 1989 console.info('speedDone called,and speed value is:' + speed); 1990}); 1991``` 1992 1993### off('speedDone')<sup>9+</sup> 1994 1995off(type: 'speedDone', callback?: Callback\<number>): void 1996 1997取消监听setSpeed生效的事件。 1998 1999**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2000 2001**参数：** 2002 2003| 参数名 | 类型 | 必填 | 说明 | 2004| ------ | ------ | ---- | --------------------------------------------------------- | 2005| type | string | 是 | setSpeed生效的事件回调类型，取消注册的事件：'speedDone'。 | 2006| callback | Callback\<number> | 否 | 回调函数。当setSpeed成功，上报生效的倍速模式，具体见[PlaybackSpeed](#playbackspeed8)。<br/>从API version 12开始支持此参数。 | 2007 2008**示例：** 2009 2010```ts 2011avPlayer.off('speedDone'); 2012``` 2013 2014 2015### setPlaybackRate<sup>20+</sup> 2016 2017setPlaybackRate(rate: number): void 2018 2019设置倍速模式。只能在prepared/playing/paused/completed状态调用，取值范围是[0.125, 4.0]，可以通过[playbackRateDone](#onplaybackratedone20)事件确认是否生效。<br> 2020>**注意：** 2021> 2022>直播场景不支持setPlaybackRate。 2023 2024**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2025 2026**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2027 2028**参数：** 2029 2030| 参数名 | 类型 | 必填 | 说明 | 2031| ------ | -------------------------------- | ---- | ------------------ | 2032| rate | number | 是 | 指定播放倍速速率。 | 2033 2034**错误码：** 2035 2036以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 2037 2038| 错误码ID | 错误信息 | 2039| -------- | ------------------------------------------ | 2040| 5400108 | The parameter check failed, parameter value out of range. | 2041| 5400102 | Operation not allowed，if invalid state or live stream. | 2042 2043**示例：** 2044 2045```ts 2046avPlayer.setPlaybackRate(2.0); 2047``` 2048 2049 2050### on('playbackRateDone')<sup>20+</sup> 2051 2052on(type: 'playbackRateDone', callback: OnPlaybackRateDone): void 2053 2054监听[setPlaybackRate](#setplaybackrate20)生效的事件。 2055 2056**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2057 2058**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2059 2060**参数：** 2061 2062| 参数名 | 类型 | 必填 | 说明 | 2063| -------- | -------- | ---- | ------------------------------------------------------------ | 2064| type | string | 是 | setPlaybackRate生效的事件回调类型，支持的事件：'playbackRateDone'，每次调用setPlaybackRate后都会回调此事件。 | 2065| callback | [OnPlaybackRateDone](#onplaybackratedone20) | 是 | setPlaybackRate生效的事件回调方法，上报设置后的播放速率。<br/>从API version 20开始支持此参数。 | 2066 2067**示例：** 2068 2069```ts 2070avPlayer.on('playbackRateDone', (rate:number) => { 2071 console.info('playbackRateDone called,and rate value is:' + rate); 2072}); 2073``` 2074 2075### off('playbackRateDone')<sup>20+</sup> 2076 2077off(type: 'playbackRateDone', callback?: OnPlaybackRateDone): void 2078 2079取消监听[setPlaybackRate](#setplaybackrate20)生效的事件。 2080 2081**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 2082 2083**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2084 2085**参数：** 2086 2087| 参数名 | 类型 | 必填 | 说明 | 2088| ------ | ------ | ---- | --------------------------------------------------------- | 2089| type | string | 是 | setPlaybackRate生效的事件回调类型，取消注册的事件：'playbackRateDone'。 | 2090| callback | [OnPlaybackRateDone](#onplaybackratedone20) | 否 | setPlaybackRate生效的事件回调方法，上报设置后的播放速率。如填写该参数，则仅取消注册此回调方法，否则取消注册playbackRateDone事件的所有回调方法。<br/>从API version 20开始支持此参数。 | 2091 2092**示例：** 2093 2094```ts 2095avPlayer.off('playbackRateDone'); 2096``` 2097 2098 2099### setBitrate<sup>9+</sup> 2100 2101setBitrate(bitrate: number): void 2102 2103设置比特率，以播放所指定比特率的流媒体资源，当前仅对**HLS/DASH协议网络流**有效。默认情况下，AVPlayer会根据网络连接速度选择合适的比特率。只能在prepared/playing/paused/completed状态调用，可以通过[bitrateDone](#onbitratedone9)事件确认是否生效。 2104 2105**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2106 2107**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2108 2109**参数：** 2110 2111| 参数名 | 类型 | 必填 | 说明 | 2112| ------- | ------ | ---- | ------------------------------------------------------------ | 2113| bitrate | number | 是 | 指定比特率，须通过[availableBitrates](#onavailablebitrates9)事件获得当前HLS/DASH协议网络流可用的比特率列表，如果用户指定的比特率不在此列表中，则播放器将从可用比特率列表中选择最接近的比特率。如果通过availableBitrates事件获得的比特率列表长度为0，则不支持指定比特率，也不会产生bitrateDone回调。 | 2114 2115**示例：** 2116 2117```ts 2118let bitrate: number = 96000; 2119avPlayer.setBitrate(bitrate); 2120``` 2121 2122### on('bitrateDone')<sup>9+</sup> 2123 2124on(type: 'bitrateDone', callback: Callback\<number>): void 2125 2126监听setBitrate生效的事件。 2127 2128**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2129 2130**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2131 2132**参数：** 2133 2134| 参数名 | 类型 | 必填 | 说明 | 2135| -------- | -------- | ---- | ------------------------------------------------------------ | 2136| type | string | 是 | setBitrate生效的事件回调类型，支持的事件：'bitrateDone'，每次调用setBitrate后都会回调此事件。 | 2137| callback | Callback\<number> | 是 | setBitrate生效的事件回调方法，上报生效的比特率。 | 2138 2139**示例：** 2140 2141```ts 2142avPlayer.on('bitrateDone', (bitrate:number) => { 2143 console.info('bitrateDone called,and bitrate value is:' + bitrate); 2144}); 2145``` 2146 2147### off('bitrateDone')<sup>9+</sup> 2148 2149off(type: 'bitrateDone', callback?: Callback\<number>): void 2150 2151取消监听setBitrate生效的事件。 2152 2153**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2154 2155**参数：** 2156 2157| 参数名 | 类型 | 必填 | 说明 | 2158| ------ | ------ | ---- | ------------------------------------------------------------ | 2159| type | string | 是 | setBitrate生效的事件回调类型，取消注册的事件：'bitrateDone'。 | 2160| callback | Callback\<number> | 否 | setBitrate生效的事件回调方法，上报生效的比特率。<br/>从API version 12开始支持此参数。 | 2161 2162**示例：** 2163 2164```ts 2165avPlayer.off('bitrateDone'); 2166``` 2167 2168### on('availableBitrates')<sup>9+</sup> 2169 2170on(type: 'availableBitrates', callback: Callback\<Array\<number>>): void 2171 2172监听HLS/DASH协议网络流可用的比特率列表，只会在切换prepared状态后上报。 2173 2174**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2175 2176**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2177 2178**参数：** 2179 2180| 参数名 | 类型 | 必填 | 说明 | 2181| -------- | -------- | ---- | ------------------------------------------------------------ | 2182| type | string | 是 | HLS/DASH协议网络流可用比特率上报事件回调类型，支持的事件：'availableBitrates'，只会在prepared之后上报一次。 | 2183| callback | Callback\<Array\<number>> | 是 | HLS/DASH协议网络流可用比特率上报事件回调方法，使用数组存放支持的比特率。如果数组长度为0，则不支持指定比特率。 | 2184 2185**示例：** 2186 2187```ts 2188avPlayer.on('availableBitrates', (bitrates: Array<number>) => { 2189 console.info('availableBitrates called,and availableBitrates length is:' + bitrates.length); 2190}); 2191``` 2192 2193### off('availableBitrates')<sup>9+</sup> 2194 2195off(type: 'availableBitrates', callback?: Callback\<Array\<number>>): void 2196 2197取消监听HLS/DASH协议网络流可用的比特率列表，调用[prepare](#prepare9)后，上报此事件。 2198 2199**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2200 2201**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2202 2203**参数：** 2204 2205| 参数名 | 类型 | 必填 | 说明 | 2206| ------ | ------ | ---- | ------------------------------------------------------------ | 2207| type | string | 是 | HLS/DASH协议网络流可用比特率上报事件回调类型，取消注册的事件：'availableBitrates'。 | 2208| callback | Callback\<Array\<number>> | 否 | HLS/DASH协议网络流可用比特率上报事件回调方法，使用数组存放支持的比特率。如果数组长度为0，则不支持指定比特率。<br/>从API version 12开始支持此参数。 | 2209 2210**示例：** 2211 2212```ts 2213avPlayer.off('availableBitrates'); 2214``` 2215 2216 2217### on('mediaKeySystemInfoUpdate')<sup>11+</sup> 2218 2219on(type: 'mediaKeySystemInfoUpdate', callback: Callback\<Array\<drm.MediaKeySystemInfo>>): void 2220 2221监听mediaKeySystemInfoUpdate事件。 2222 2223**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2224 2225**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2226 2227**参数：** 2228 2229| 参数名 | 类型 | 必填 | 说明 | 2230| -------- | -------- | ---- | ------------------------------------------------------------ | 2231| type | string | 是 | 版权保护信息更新上报事件回调类型，支持的事件：'mediaKeySystemInfoUpdate'，当播放内容的版权保护信息更新时上报事件。 | 2232| callback | Callback\<Array\<drm.[MediaKeySystemInfo](../apis-drm-kit/arkts-apis-drm-i.md#mediakeysysteminfo)>> | 是 | 版权保护信息更新上报事件回调方法，上报MediaKeySystemInfo数组。 | 2233 2234**示例：** 2235 2236```ts 2237import { drm } from '@kit.DrmKit'; 2238 2239avPlayer.on('mediaKeySystemInfoUpdate', (mediaKeySystemInfo: Array<drm.MediaKeySystemInfo>) => { 2240 for (let i = 0; i < mediaKeySystemInfo.length; i++) { 2241 console.info('mediaKeySystemInfoUpdate happened uuid: ' + mediaKeySystemInfo[i]["uuid"]); 2242 console.info('mediaKeySystemInfoUpdate happened pssh: ' + mediaKeySystemInfo[i]["pssh"]); 2243 } 2244}); 2245``` 2246 2247### off('mediaKeySystemInfoUpdate')<sup>11+</sup> 2248 2249off(type: 'mediaKeySystemInfoUpdate', callback?: Callback\<Array\<drm.MediaKeySystemInfo>>): void; 2250 2251取消监听mediaKeySystemInfoUpdate事件。 2252 2253**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2254 2255**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2256 2257**参数：** 2258 2259| 参数名 | 类型 | 必填 | 说明 | 2260| ------ | ------ | ---- | ------------------------------------------------------------ | 2261| type | string | 是 | 版权保护信息更新上报事件回调类型，取消注册的事件：'mediaKeySystemInfoUpdate'。 | 2262| callback | Callback\<Array\<drm.[MediaKeySystemInfo](../apis-drm-kit/arkts-apis-drm-i.md#mediakeysysteminfo)>> | 否 | 版权保护信息更新上报事件回调方法，上报版权保护信息数组。如填写该参数，则仅取消注册此回调方法，否则取消注册mediaKeySystemInfoUpdate事件的所有回调方法。 | 2263 2264**示例：** 2265 2266```ts 2267avPlayer.off('mediaKeySystemInfoUpdate'); 2268``` 2269 2270### setVolume<sup>9+</sup> 2271 2272setVolume(volume: number): void 2273 2274设置媒体播放音量，只能在prepared/playing/paused/completed状态调用，可以通过[volumeChange事件](#onvolumechange9)确认是否生效。 2275 2276**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2277 2278**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2279 2280**参数：** 2281 2282| 参数名 | 类型 | 必填 | 说明 | 2283| ------ | ------ | ---- | ------------------------------------------------------------ | 2284| volume | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 2285 2286**示例：** 2287 2288```ts 2289let volume: number = 1.0; 2290avPlayer.setVolume(volume); 2291``` 2292 2293### on('volumeChange')<sup>9+</sup> 2294 2295on(type: 'volumeChange', callback: Callback\<number>): void 2296 2297监听setVolume生效的事件。 2298 2299**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2300 2301**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2302 2303**参数：** 2304 2305| 参数名 | 类型 | 必填 | 说明 | 2306| -------- | -------- | ---- | ------------------------------------------------------------ | 2307| type | string | 是 | setVolume生效的事件回调类型，支持的事件：'volumeChange'，每次调用setVolume后都会回调此事件。 | 2308| callback | Callback\<number> | 是 | setVolume生效的事件回调方法，上报生效的媒体音量。 | 2309 2310**示例：** 2311 2312```ts 2313avPlayer.on('volumeChange', (vol: number) => { 2314 console.info('volumeChange called,and new volume is :' + vol); 2315}); 2316``` 2317 2318### off('volumeChange')<sup>9+</sup> 2319 2320off(type: 'volumeChange', callback?: Callback\<number>): void 2321 2322取消监听setVolume生效的事件。 2323 2324**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2325 2326**参数：** 2327 2328| 参数名 | 类型 | 必填 | 说明 | 2329| ------ | ------ | ---- | ------------------------------------------------------------ | 2330| type | string | 是 | setVolume生效的事件回调类型，取消注册的事件：'volumeChange'。 | 2331| callback | Callback\<number> | 否 | setVolume生效的事件回调方法，上报生效的媒体音量。<br/>从API version 12开始支持此参数。 | 2332 2333**示例：** 2334 2335```ts 2336avPlayer.off('volumeChange'); 2337``` 2338 2339### on('endOfStream')<sup>9+</sup> 2340 2341on(type: 'endOfStream', callback: Callback\<void>): void 2342 2343监听资源播放至结尾的事件；如果用户设置[loop](#属性)=true，播放会跳转至开头重播；如果用户没有设置loop，会通过[stateChange](#onstatechange9)上报completed状态。 2344 2345**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2346 2347**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2348 2349**参数：** 2350 2351| 参数名 | 类型 | 必填 | 说明 | 2352| -------- | -------- | ---- | ------------------------------------------------------------ | 2353| type | string | 是 | 资源播放至结尾的事件回调类型，支持的事件：'endOfStream'，当播放至结尾时会上报此事件。 | 2354| callback | Callback\<void> | 是 | 资源播放至结尾的事件回调方法。 | 2355 2356**示例：** 2357 2358```ts 2359avPlayer.on('endOfStream', () => { 2360 console.info('endOfStream called'); 2361}); 2362``` 2363 2364### off('endOfStream')<sup>9+</sup> 2365 2366off(type: 'endOfStream', callback?: Callback\<void>): void 2367 2368取消监听资源播放至结尾的事件。 2369 2370**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2371 2372**参数：** 2373 2374| 参数名 | 类型 | 必填 | 说明 | 2375| ------ | ------ | ---- | ------------------------------------------------------------ | 2376| type | string | 是 | 资源播放至结尾的事件回调类型，取消注册的事件：'endOfStream'。 | 2377| callback | Callback\<void> | 否 | 资源播放至结尾的事件回调方法。<br/>从API version 12开始支持此参数。 | 2378 2379**示例：** 2380 2381```ts 2382avPlayer.off('endOfStream'); 2383``` 2384 2385### on('timeUpdate')<sup>9+</sup> 2386 2387on(type: 'timeUpdate', callback: Callback\<number>): void 2388 2389监听资源播放当前时间，单位为毫秒（ms），用于刷新进度条当前位置，默认间隔100ms时间上报，因用户操作(seek)产生的时间变化会立刻上报。 2390 2391注：直播场景不支持timeUpdate上报。 2392 2393**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2394 2395**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2396 2397**参数：** 2398 2399| 参数名 | 类型 | 必填 | 说明 | 2400| -------- | -------- | ---- | ---------------------------------------------- | 2401| type | string | 是 | 时间更新的回调类型，支持的事件：'timeUpdate'。 | 2402| callback | Callback\<number> | 是 | 回调函数。返回当前时间。 | 2403 2404**示例：** 2405 2406```ts 2407avPlayer.on('timeUpdate', (time:number) => { 2408 console.info('timeUpdate called,and new time is :' + time); 2409}); 2410``` 2411 2412### off('timeUpdate')<sup>9+</sup> 2413 2414off(type: 'timeUpdate', callback?: Callback\<number>): void 2415 2416取消监听资源播放当前时间。 2417 2418**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2419 2420**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2421 2422**参数：** 2423 2424| 参数名 | 类型 | 必填 | 说明 | 2425| ------ | ------ | ---- | -------------------------------------------------- | 2426| type | string | 是 | 时间更新的回调类型，取消注册的事件：'timeUpdate'。 | 2427| callback | Callback\<number> | 否 | 回调函数。返回当前时间。<br/>从API version 12开始支持此参数。 | 2428 2429**示例：** 2430 2431```ts 2432avPlayer.off('timeUpdate'); 2433``` 2434 2435### on('durationUpdate')<sup>9+</sup> 2436 2437 2438on(type: 'durationUpdate', callback: Callback\<number>): void 2439 2440监听资源播放资源的时长，单位为毫秒（ms），用于刷新进度条长度，默认只在prepared上报一次，同时允许一些特殊码流刷新多次时长。 2441注：直播场景不支持durationUpdate上报。 2442 2443**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2444 2445**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2446 2447**参数：** 2448 2449| 参数名 | 类型 | 必填 | 说明 | 2450| -------- | -------- | ---- | -------------------------------------------------- | 2451| type | string | 是 | 时长更新的回调类型，支持的事件：'durationUpdate'。 | 2452| callback | Callback\<number> | 是 | 回调函数。返回资源时长。 | 2453 2454**示例：** 2455 2456```ts 2457avPlayer.on('durationUpdate', (duration: number) => { 2458 console.info('durationUpdate called,new duration is :' + duration); 2459}); 2460``` 2461 2462### off('durationUpdate')<sup>9+</sup> 2463 2464off(type: 'durationUpdate', callback?: Callback\<number>): void 2465 2466取消监听资源播放资源的时长。 2467 2468**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2469 2470**参数：** 2471 2472| 参数名 | 类型 | 必填 | 说明 | 2473| ------ | ------ | ---- | ------------------------------------------------------ | 2474| type | string | 是 | 时长更新的回调类型，取消注册的事件：'durationUpdate'。 | 2475| callback | Callback\<number> | 否 | 回调函数。返回资源时长。<br/>从API version 12开始支持此参数。 | 2476 2477**示例：** 2478 2479```ts 2480avPlayer.off('durationUpdate'); 2481``` 2482 2483### on('bufferingUpdate')<sup>9+</sup> 2484 2485on(type: 'bufferingUpdate', callback: OnBufferingUpdateHandler): void 2486 2487订阅音视频缓存更新事件，仅网络播放支持该订阅事件。 2488 2489**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2490 2491**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2492 2493**参数：** 2494 2495| 参数名 | 类型 | 必填 | 说明 | 2496| -------- | -------- | ---- | ------------------------------------------------------------ | 2497| type | string | 是 | 播放缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 2498| callback | [OnBufferingUpdateHandler](#onbufferingupdatehandler12) | 是 | 播放缓存事件回调方法。 | 2499 2500**示例：** 2501 2502```ts 2503avPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 2504 console.info('bufferingUpdate called,and infoType value is:' + infoType + ', value is :' + value); 2505}); 2506``` 2507 2508### off('bufferingUpdate')<sup>9+</sup> 2509 2510off(type: 'bufferingUpdate', callback?: OnBufferingUpdateHandler): void 2511 2512取消监听音视频缓存更新事件。 2513 2514**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2515 2516**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2517 2518**参数：** 2519 2520| 参数名 | 类型 | 必填 | 说明 | 2521| ------ | ------ | ---- | --------------------------------------------------------- | 2522| type | string | 是 | 播放缓存事件回调类型，取消注册的事件：'bufferingUpdate'。 | 2523| callback | [OnBufferingUpdateHandler](#onbufferingupdatehandler12) | 否 | 播放缓存事件回调方法。 | 2524 2525**示例：** 2526 2527```ts 2528avPlayer.off('bufferingUpdate'); 2529``` 2530 2531### on('startRenderFrame')<sup>9+</sup> 2532 2533on(type: 'startRenderFrame', callback: Callback\<void>): void 2534 2535订阅视频播放开始首帧渲染的更新事件，仅视频播放支持该订阅事件，该事件仅代表播放服务将第一帧画面送显示模块，实际效果依赖显示服务渲染性能。 2536 2537**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2538 2539**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2540 2541**参数：** 2542 2543| 参数名 | 类型 | 必填 | 说明 | 2544| -------- | -------- | ---- | ------------------------------------------------------------ | 2545| type | string | 是 | 视频播放开始首帧渲染事件回调类型，支持的事件：'startRenderFrame'。 | 2546| callback | Callback\<void> | 是 | 视频播放开始首帧渲染事件回调方法。 | 2547 2548**示例：** 2549 2550```ts 2551avPlayer.on('startRenderFrame', () => { 2552 console.info('startRenderFrame called'); 2553}); 2554``` 2555 2556### off('startRenderFrame')<sup>9+</sup> 2557 2558off(type: 'startRenderFrame', callback?: Callback\<void>): void 2559 2560取消监听视频播放开始首帧渲染的更新事件。 2561 2562**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2563 2564**参数：** 2565 2566| 参数名 | 类型 | 必填 | 说明 | 2567| ------ | ------ | ---- | ------------------------------------------------------------ | 2568| type | string | 是 | 视频播放开始首帧渲染事件回调类型，取消注册的事件：'startRenderFrame'。 | 2569| callback | Callback\<void> | 否 | 视频播放开始首帧渲染事件回调方法。<br/>从API version 12开始支持此参数。 | 2570 2571**示例：** 2572 2573```ts 2574avPlayer.off('startRenderFrame'); 2575``` 2576 2577### on('videoSizeChange')<sup>9+</sup> 2578 2579on(type: 'videoSizeChange', callback: OnVideoSizeChangeHandler): void 2580 2581监听视频播放宽高变化事件，仅视频播放支持该订阅事件，默认只在prepared状态上报一次，但HLS协议码流会在切换分辨率时上报。 2582 2583**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2584 2585**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2586 2587**参数：** 2588 2589| 参数名 | 类型 | 必填 | 说明 | 2590| -------- | -------- | ---- | ------------------------------------------------------------ | 2591| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChange'。 | 2592| callback | [OnVideoSizeChangeHandler](#onvideosizechangehandler12) | 是 | 视频播放宽高变化事件回调方法。 | 2593 2594**示例：** 2595 2596```ts 2597avPlayer.on('videoSizeChange', (width: number, height: number) => { 2598 console.info('videoSizeChange called,and width is:' + width + ', height is :' + height); 2599}); 2600``` 2601 2602### off('videoSizeChange')<sup>9+</sup> 2603 2604off(type: 'videoSizeChange', callback?: OnVideoSizeChangeHandler): void 2605 2606取消监听视频播放宽高变化事件。 2607 2608**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2609 2610**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2611 2612**参数：** 2613 2614| 参数名 | 类型 | 必填 | 说明 | 2615| ------ | ------ | ---- | ------------------------------------------------------------ | 2616| type | string | 是 | 视频播放宽高变化事件回调类型，取消注册的事件：'videoSizeChange'。 | 2617| callback | [OnVideoSizeChangeHandler](#onvideosizechangehandler12) | 否 | 视频播放宽高变化事件回调方法。<br/>从API version 12开始支持此参数。 | 2618 2619**示例：** 2620 2621```ts 2622avPlayer.off('videoSizeChange'); 2623``` 2624 2625### on('audioInterrupt')<sup>9+</sup> 2626 2627on(type: 'audioInterrupt', callback: Callback\<audio.InterruptEvent>): void 2628 2629监听音频焦点变化事件，多个音视频资源同时播放时，会根据音频焦点模型[audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9)触发此事件。应用需根据不同焦点变化事件作相应处理。具体可参考[处理音频焦点事件](../../media/audio/audio-playback-concurrency.md)。 2630 2631**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2632 2633**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2634 2635**参数：** 2636 2637| 参数名 | 类型 | 必填 | 说明 | 2638| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 2639| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 2640| callback | Callback\<[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)> | 是 | 音频焦点变化事件回调方法。 | 2641 2642**示例：** 2643 2644```ts 2645import { audio } from '@kit.AudioKit'; 2646 2647avPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 2648 console.info('audioInterrupt called,and InterruptEvent info is:' + info); 2649}); 2650``` 2651 2652### off('audioInterrupt')<sup>9+</sup> 2653 2654off(type: 'audioInterrupt', callback?: Callback<audio.InterruptEvent>): void 2655 2656取消监听音频焦点变化事件。 2657 2658**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2659 2660**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2661 2662**参数：** 2663 2664| 参数名 | 类型 | 必填 | 说明 | 2665| ------ | ------ | ---- | ------------------------------------------------------------ | 2666| type | string | 是 | 音频焦点变化事件回调类型，取消注册的事件：'audioInterrupt'。 | 2667| callback | Callback\<[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)> | 否 | 音频焦点变化事件回调方法。<br/>从API version 12开始支持此参数。 | 2668 2669**示例：** 2670 2671```ts 2672avPlayer.off('audioInterrupt'); 2673``` 2674 2675### on('audioOutputDeviceChangeWithInfo')<sup>11+</sup> 2676 2677on(type: 'audioOutputDeviceChangeWithInfo', callback: Callback\<audio.AudioStreamDeviceChangeInfo>): void 2678 2679订阅监听音频流输出设备变化及原因，使用callback方式返回结果。 2680 2681在订阅此监听时，建议参考[响应音频流输出设备变更](../../media/audio/audio-output-device-change.md)自行实现设备连接或者断开时的播放器行为。 2682 2683**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2684 2685**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2686 2687**参数：** 2688 2689| 参数名 | 类型 | 必填 | 说明 | 2690| :------- | :------------------------- | :--- | :------------------------------------------ | 2691| type | string | 是 | 事件回调类型，支持的事件为：'audioOutputDeviceChangeWithInfo'。 | 2692| callback | Callback\<[audio.AudioStreamDeviceChangeInfo](../apis-audio-kit/js-apis-audio.md#audiostreamdevicechangeinfo11)> | 是 | 回调函数，返回当前音频流的输出设备描述信息及变化原因。 | 2693 2694**错误码：** 2695 2696| 错误码ID | 错误信息 | 2697| -------- | ------------------------------------------ | 2698| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2699 2700**示例：** 2701 2702```ts 2703import { audio } from '@kit.AudioKit'; 2704 2705avPlayer.on('audioOutputDeviceChangeWithInfo', (data: audio.AudioStreamDeviceChangeInfo) => { 2706 console.info(`${JSON.stringify(data)}`); 2707}); 2708``` 2709 2710### off('audioOutputDeviceChangeWithInfo')<sup>11+</sup> 2711 2712off(type: 'audioOutputDeviceChangeWithInfo', callback?: Callback\<audio.AudioStreamDeviceChangeInfo>): void 2713 2714取消订阅监听音频流输出设备变化及原因，使用callback方式返回结果。 2715 2716**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2717 2718**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2719 2720**参数：** 2721 2722| 参数名 | 类型 | 必填 | 说明 | 2723| :------- | :------------------------- | :--- | :------------------------------------------ | 2724| type | string | 是 | 事件回调类型，支持的事件为：'audioOutputDeviceChangeWithInfo'。 | 2725| callback | Callback\<[audio.AudioStreamDeviceChangeInfo](../apis-audio-kit/js-apis-audio.md#audiostreamdevicechangeinfo11)> | 否 | 回调函数，返回当前音频流的输出设备描述信息及变化原因。 | 2726 2727**错误码：** 2728 2729| 错误码ID | 错误信息 | 2730| -------- | ------------------------------------------ | 2731| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2732 2733**示例：** 2734 2735```ts 2736avPlayer.off('audioOutputDeviceChangeWithInfo'); 2737``` 2738 2739### addSubtitleFromFd<sup>12+</sup> 2740 2741addSubtitleFromFd(fd: number, offset?: number, length?: number): Promise\<void> 2742 2743依据fd为视频添加外挂字幕，当前仅支持与视频资源同时设置（在avplayer设置fdSrc视频资源后设置外挂字幕）。使用Promise方式返回结果。 2744 2745**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2746 2747**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2748 2749**参数：** 2750 2751| 参数名 | 类型 | 必填 | 说明 | 2752| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 2753| fd | number | 是 | 资源句柄，通过[resourceManager.getRawFd](../apis-localization-kit/js-apis-resource-manager.md#getrawfd9)获取。 | 2754| offset | number | 否 | 资源偏移量，需要基于预置资源的信息输入，非法值会造成字幕频资源解析错误，默认值:0。 | 2755| length | number | 否 | 资源长度，默认值为文件中从偏移量开始的剩余字节，需要基于预置资源的信息输入，非法值会造成字幕频资源解析错误，默认值:0。 | 2756 2757**返回值：** 2758 2759| 类型 | 说明 | 2760| -------------- | ------------------------------------------ | 2761| Promise\<void> | 添加外挂字幕addSubtitleFromFd方法的Promise返回值。 | 2762 2763**错误码：** 2764 2765| 错误码ID | 错误信息 | 2766| -------- | ------------------------------------------ | 2767| 401 | The parameter check failed. Return by promise. | 2768| 5400102 | Operation not allowed. Return by promise. | 2769 2770**示例：** 2771 2772<!--code_no_check--> 2773```ts 2774import { common } from '@kit.AbilityKit' 2775 2776private context: Context | undefined; 2777constructor(context: Context) { 2778 this.context = context; // this.getUIContext().getHostContext(); 2779} 2780let fileDescriptor = await this.context.resourceManager.getRawFd('xxx.srt'); 2781 2782avPlayer.addSubtitleFromFd(fileDescriptor.fd, fileDescriptor.offset, fileDescriptor.length); 2783``` 2784 2785### addSubtitleFromUrl<sup>12+</sup> 2786 2787addSubtitleFromUrl(url: string): Promise\<void> 2788 2789依据url为视频添加外挂字幕，当前仅支持与视频资源同时设置（在avplayer设置fdSrc视频资源后设置外挂字幕）。使用Promise方式返回结果。 2790 2791**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2792 2793**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2794 2795**参数：** 2796 2797| 参数名 | 类型 | 必填 | 说明 | 2798| ------ | ------ | ---- | ------------------------------------------------------------ | 2799| url | string | 是 | 外挂字幕文件地址。 | 2800 2801**返回值：** 2802 2803| 类型 | 说明 | 2804| -------------- | ------------------------------------------ | 2805| Promise\<void> | 添加外挂字幕addSubtitleFromUrl方法的Promise返回值。 | 2806 2807**错误码：** 2808 2809| 错误码ID | 错误信息 | 2810| -------- | ------------------------------------------ | 2811| 401 | The parameter check failed. Return by promise. | 2812| 5400102 | Operation not allowed. Return by promise. | 2813 2814**示例：** 2815 2816<!--code_no_check--> 2817```ts 2818let fdUrl:string = 'http://xxx.xxx.xxx/xx/index.srt'; 2819 2820let avPlayer: media.AVPlayer = await media.createAVPlayer(); 2821avPlayer.addSubtitleFromUrl(fdUrl); 2822``` 2823 2824### on('subtitleUpdate')<sup>12+</sup> 2825 2826on(type: 'subtitleUpdate', callback: Callback\<SubtitleInfo>): void 2827 2828订阅获取外挂字幕的事件，当有外挂字幕时，会通过订阅的回调方法通知用户。用户只能订阅一个外挂字幕事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2829 2830**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2831 2832**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2833 2834**参数：** 2835 2836| 参数名 | 类型 | 必填 | 说明 | 2837| -------- | -------- | ---- | ------------------------------------------------------------ | 2838| type | string | 是 | 事件回调类型，支持的事件为：'subtitleUpdate'。 | 2839| callback | function | 是 | 外挂字幕事件回调方法。 | 2840 2841**示例：** 2842 2843```ts 2844avPlayer.on('subtitleUpdate', async (info: media.SubtitleInfo) => { 2845 if (info) { 2846 let text = (!info.text) ? '' : info.text 2847 let startTime = (!info.startTime) ? 0 : info.startTime 2848 let duration = (!info.duration) ? 0 : info.duration 2849 console.info('subtitleUpdate info: text=' + text + ' startTime=' + startTime +' duration=' + duration); 2850 } else { 2851 console.info('subtitleUpdate info is null'); 2852 } 2853}); 2854``` 2855 2856### off('subtitleUpdate')<sup>12+</sup> 2857 2858off(type: 'subtitleUpdate', callback?: Callback\<SubtitleInfo>): void 2859 2860取消订阅获取外挂字幕的事件。 2861 2862**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2863 2864**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2865 2866**参数：** 2867 2868| 参数名 | 类型 | 必填 | 说明 | 2869| -------- | -------- | ---- | ------------------------------------------------------------ | 2870| type | string | 是 | 事件回调类型，支持的事件为：'subtitleUpdate'。 | 2871| callback | function | 否 | 取消外挂字幕事件的回调方法。 | 2872 2873**示例：** 2874 2875```ts 2876avPlayer.off('subtitleUpdate'); 2877``` 2878 2879### on('trackChange')<sup>12+</sup> 2880 2881on(type: 'trackChange', callback: OnTrackChangeHandler): void 2882 2883订阅获取轨道变更的事件，当播放的轨道变更时，会通过订阅的回调方法通知用户。用户只能订阅一个轨道变更事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2884 2885**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2886 2887**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2888 2889**参数：** 2890 2891| 参数名 | 类型 | 必填 | 说明 | 2892| -------- | -------- | ---- | ------------------------------------------------------------ | 2893| type | string | 是 | 事件回调类型，支持的事件为：'trackChange'。 | 2894| callback | [OnTrackChangeHandler](#ontrackchangehandler12) | 是 | 轨道变更事件回调方法。 | 2895 2896**示例：** 2897 2898```ts 2899avPlayer.on('trackChange', (index: number, isSelect: boolean) => { 2900 console.info('trackChange info: index=' + index + ' isSelect=' + isSelect); 2901}); 2902``` 2903 2904### off('trackChange')<sup>12+</sup> 2905 2906off(type: 'trackChange', callback?: OnTrackChangeHandler): void 2907 2908取消订阅获取轨道变更的事件。 2909 2910**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2911 2912**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2913 2914**参数：** 2915 2916| 参数名 | 类型 | 必填 | 说明 | 2917| -------- | -------- | ---- | ------------------------------------------------------------ | 2918| type | string | 是 | 事件回调类型，支持的事件为：'trackChange'。 | 2919| callback | [OnTrackChangeHandler](#ontrackchangehandler12) | 否 | 取消轨道变更事件的回调方法。 | 2920 2921**示例：** 2922 2923```ts 2924avPlayer.off('trackChange'); 2925``` 2926 2927### on('trackInfoUpdate')<sup>12+</sup> 2928 2929on(type: 'trackInfoUpdate', callback: Callback\<Array\<MediaDescription>>): void 2930 2931订阅获取轨道信息更新的事件，当播放的轨道有更新时，会通过订阅的回调方法通知用户。用户只能订阅一个轨道变更事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2932 2933**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2934 2935**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2936 2937**参数：** 2938 2939| 参数名 | 类型 | 必填 | 说明 | 2940| -------- | -------- | ---- | ------------------------------------------------------------ | 2941| type | string | 是 | 事件回调类型，支持的事件为：'trackInfoUpdate'。 | 2942| callback | Callback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 轨道信息更新事件回调方法。 | 2943 2944**示例：** 2945 2946```ts 2947avPlayer.on('trackInfoUpdate', (info: Array<media.MediaDescription>) => { 2948 if (info) { 2949 for (let i = 0; i < info.length; i++) { 2950 let propertyIndex: Object = info[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 2951 let propertyType: Object = info[i][media.MediaDescriptionKey.MD_KEY_TRACK_TYPE]; 2952 console.info('track info: index=' + propertyIndex + ' tracktype=' + propertyType); 2953 } 2954 } else { 2955 console.info('track info is null'); 2956 } 2957}); 2958``` 2959 2960### off('trackInfoUpdate')<sup>12+</sup> 2961 2962off(type: 'trackInfoUpdate', callback?: Callback\<Array\<MediaDescription>>): void 2963 2964取消订阅获取轨道变更的事件。 2965 2966**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2967 2968**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2969 2970**参数：** 2971 2972| 参数名 | 类型 | 必填 | 说明 | 2973| -------- | -------- | ---- | ------------------------------------------------------------ | 2974| type | string | 是 | 事件回调类型，支持的事件为：'trackInfoUpdate'。 | 2975| callback | Callback\<Array\<[MediaDescription](#mediadescription8)>> | 否 | 取消轨道信息更新事件的回调方法。 | 2976 2977**示例：** 2978 2979```ts 2980avPlayer.off('trackInfoUpdate'); 2981``` 2982 2983### on('amplitudeUpdate')<sup>13+</sup> 2984 2985on(type: 'amplitudeUpdate', callback: Callback\<Array\<number>>): void 2986 2987订阅音频最大电平值，音频资源播放时定时上报。 2988 2989**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2990 2991**参数：** 2992 2993| 参数名 | 类型 | 必填 | 说明 | 2994| -------- | -------- | ---- | ------------------------------------------------------------ | 2995| type | string | 是 | 事件回调类型，支持的事件为：'amplitudeUpdate'。 | 2996| callback | Callback\<Array\<number>> | 是 | 音频最大电平值更新事件回调方法。 | 2997 2998**示例：** 2999 3000```ts 3001avPlayer.on('amplitudeUpdate', (value: Array<number>) => { 3002 console.info('amplitudeUpdate called,and amplitudeUpdate = ${value}'); 3003}); 3004``` 3005 3006### off('amplitudeUpdate')<sup>13+</sup> 3007 3008off(type: 'amplitudeUpdate', callback?: Callback\<Array\<number>>): void 3009 3010取消订阅获取音频最大电平值事件。 3011 3012**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3013 3014**参数：** 3015 3016| 参数名 | 类型 | 必填 | 说明 | 3017| ------ | ------ | ---- | ------------------------------------------------------------ | 3018| type | string | 是 | 事件回调类型，支持的事件为：'amplitudeUpdate'。 | 3019| callback | Callback\<Array\<number>> | 否 | 取消音频最大电平值更新事件回调方法。 | 3020 3021**示例：** 3022 3023```ts 3024avPlayer.off('amplitudeUpdate'); 3025``` 3026 3027### on('seiMessageReceived')<sup>18+</sup> 3028 3029on(type: 'seiMessageReceived', payloadTypes: Array\<number>, callback: OnSeiMessageHandle): void 3030 3031订阅获取SEI信息事件，仅适用于HTTP-FLV直播，视频流中包含SEI信息时上报。需在prepare之前订阅，当用户重复订阅时，以最后一次订阅的回调接口为准。 3032 3033**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3034 3035**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3036 3037**参数：** 3038 3039| 参数名 | 类型 | 必填 | 说明 | 3040| -------- | -------- | ---- | ------------------------------------------------------------ | 3041| type | string | 是 | 事件回调类型，支持的事件为：'seiMessageReceived'。 | 3042| payloadTypes | Array\<number> | 是 | SEI信息的订阅负载类型数组。当前仅支持负载类型为5，即payloadType = 5。| 3043| callback | [OnSeiMessageHandle](#onseimessagehandle18) | 是 | 用于监听SEI信息事件的回调函数，接收订阅的负载类型。 | 3044 3045**示例：** 3046 3047```ts 3048import util from '@ohos.util'; 3049 3050avPlayer.on('seiMessageReceived', [5], (messages: Array<media.SeiMessage>, playbackPosition?: number) => 3051{ 3052 console.info('seiMessageReceived playbackPosition ' + playbackPosition); 3053 3054 for (let key = 0; key < messages.length; key++) { 3055 console.info('seiMessageReceived messages payloadType ' + messages[key].payloadType + ' payload size ' + messages[key].payload.byteLength); 3056 3057 let textDecoder = util.TextDecoder.create("utf-8",{ignoreBOM: true}); 3058 let ab = messages[key]?.payload?.slice(16, messages[key].payload.byteLength); 3059 let result: Uint8Array = new Uint8Array(ab); 3060 let retStr: string = textDecoder.decodeToString(result); 3061 console.info('seiMessageReceived messages payload ' + retStr); 3062 } 3063}); 3064``` 3065 3066### off('seiMessageReceived')<sup>18+</sup> 3067 3068off(type: 'seiMessageReceived', payloadTypes?: Array\<number>, callback?: OnSeiMessageHandle): void 3069 3070取消订阅获取SEI信息事件。 3071 3072**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3073 3074**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3075 3076**参数：** 3077 3078| 参数名 | 类型 | 必填 | 说明 | 3079| ------ | ------ | ---- | ------------------------------------------------------------ | 3080| type | string | 是 | 事件回调类型，支持的事件为：'seiMessageReceived'。 | 3081| payloadTypes | Array\<number> | 否 | SEI信息的订阅负载类型。 | 3082| callback | [OnSeiMessageHandle](#onseimessagehandle18) | 否 | 用于监听SEI信息事件的回调函数，接收订阅的负载类型。 | 3083 3084**示例：** 3085 3086```ts 3087avPlayer.off('seiMessageReceived'); 3088``` 3089 3090### setSuperResolution<sup>18+</sup> 3091 3092setSuperResolution(enabled: boolean) : Promise\<void> 3093 3094动态开启/关闭超分算法，可以在 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' 状态调用。使用Promise方式返回结果。 3095 3096在调用[prepare()](#prepare9)前先通过[PlaybackStrategy](#playbackstrategy12)使能超分。 3097 3098**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3099 3100**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3101 3102**参数：** 3103 3104| 参数名 | 类型 | 必填 | 说明 | 3105| ------ | ------ | ---- | ------------------------------------------------------------ | 3106| enabled | boolean | 是 | 表示是否开启超分。true表示开启超分，false表示关闭超分。 | 3107 3108**返回值：** 3109 3110| 类型 | 说明 | 3111| -------------- | ------------------------------------------ | 3112| Promise\<void> | 开启/关闭超分setSuperResolution方法的Promise返回值。 | 3113 3114**错误码：** 3115 3116以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3117 3118| 错误码ID | 错误信息 | 3119| -------- | ------------------------------------------ | 3120| 5400102 | Operation not allowed. Return by promise. | 3121| 5410003 | Super-resolution not supported. Return by promise. | 3122| 5410004 | Missing enable super-resolution feature in [PlaybackStrategy](#playbackstrategy12). Return by promise. | 3123 3124**示例：** 3125 3126```ts 3127avPlayer.setSuperResolution(true); 3128``` 3129 3130### setVideoWindowSize<sup>18+</sup> 3131 3132setVideoWindowSize(width: number, height: number) : Promise\<void> 3133 3134动态设置超分算法的输出分辨率，可以在 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' 状态调用。使用Promise方式返回结果。输入参数须在 320x320 ~ 1920x1080 范围内，单位为像素。 3135 3136在调用[prepare()](#prepare9)前先通过[PlaybackStrategy](#playbackstrategy12)使能超分。 3137 3138**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3139 3140**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3141 3142**参数：** 3143 3144| 参数名 | 类型 | 必填 | 说明 | 3145| ------ | ------ | ---- | ------------------------------------------------------------ | 3146| width | number | 是 | 超分算法的目标输出视频宽度，取值范围为[320-1920]，单位为像素。 | 3147| height | number | 是 | 超分算法的目标输出视频高度，取值范围为[320-1080]，单位为像素。 | 3148 3149**返回值：** 3150 3151| 类型 | 说明 | 3152| -------------- | ------------------------------------------ | 3153| Promise\<void> | 配置超分目标输出分辨率setVideoWindowSize方法的Promise返回值。 | 3154 3155**错误码：** 3156 3157以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体错误码](errorcode-media.md)。 3158 3159| 错误码ID | 错误信息 | 3160| -------- | ------------------------------------------ | 3161| 401 | Parameter error. Return by promise. | 3162| 5400102 | Operation not allowed. Return by promise. | 3163| 5410003 | Super-resolution not supported. Return by promise. | 3164| 5410004 | Missing enable super-resolution feature in [PlaybackStrategy](#playbackstrategy12). Return by promise. | 3165 3166**示例：** 3167 3168```ts 3169avPlayer.setVideoWindowSize(1920, 1080); 3170``` 3171 3172### on('superResolutionChanged')<sup>18+</sup> 3173 3174on(type:'superResolutionChanged', callback: OnSuperResolutionChanged): void 3175 3176订阅监听超分算法开启/关闭事件。 3177 3178**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3179 3180**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3181 3182**参数：** 3183 3184| 参数名 | 类型 | 必填 | 说明 | 3185| -------- | -------- | ---- | ------------------------------------------------------------ | 3186| type | string | 是 | 事件回调类型，支持的事件为：'superResolutionChanged'，当超分算法开启/关闭状态变化时，触发该事件。 | 3187| callback | [OnSuperResolutionChanged](#onsuperresolutionchanged-18) | 是 | 超分开关事件回调方法。 | 3188 3189**示例：** 3190 3191```ts 3192avPlayer.on('superResolutionChanged', (enabled: boolean) => { 3193 console.info('superResolutionChanged called, and enabled is:' + enabled); 3194}); 3195``` 3196 3197### off('superResolutionChanged')<sup>18+</sup> 3198 3199off(type:'superResolutionChanged', callback?: OnSuperResolutionChanged): void 3200 3201取消监听超分算法开启/关闭事件。 3202 3203**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3204 3205**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3206 3207**参数：** 3208 3209| 参数名 | 类型 | 必填 | 说明 | 3210| -------- | -------- | ---- | ------------------------------------------------------------ | 3211| type | string | 是 | 事件回调类型，支持的事件为：'superResolutionChanged'，当超分算法开启/关闭状态变化时，触发该事件。 | 3212| callback | [OnSuperResolutionChanged](#onsuperresolutionchanged-18) | 否 | 超分开关事件回调方法。 | 3213 3214**示例：** 3215 3216```ts 3217avPlayer.off('superResolutionChanged'); 3218``` 3219 3220## AVPlayerState<sup>9+</sup> 3221 3222type AVPlayerState = 'idle' | 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' | 'released' | 'error' 3223 3224[AVPlayer](#avplayer9)的状态机，可通过state属性主动获取当前状态，也可通过监听[stateChange](#onstatechange9)事件上报当前状态，状态机之间的切换规则，可参考[音频播放开发指导](../../media/media/using-avplayer-for-playback.md)。 3225 3226**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3227 3228**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3229 3230| 类型 | 说明 | 3231| :-----------------------------: | :----------------------------------------------------------- | 3232| 'idle' | 闲置状态，AVPlayer刚被创建[createAVPlayer()](#mediacreateavplayer9)或者调用了[reset()](#reset9)方法之后，进入idle状态。<br/>首次创建[createAVPlayer()](#mediacreateavplayer9)，所有属性都为默认值。<br/>调用[reset()](#reset9)方法，url<sup>9+</sup> 或 fdSrc<sup>9+</sup>或dataSrc<sup>10+</sup>属性及loop属性会被重置，其他用户设置的属性将被保留。 | 3233| 'initialized' | 资源初始化，在idle 状态设置 url<sup>9+</sup> 或 fdSrc<sup>9+</sup>属性，AVPlayer会进入initialized状态，此时可以配置窗口、音频等静态属性。 | 3234| 'prepared' | 已准备状态，在initialized状态调用[prepare()](#prepare9)方法，AVPlayer会进入prepared状态，此时播放引擎的资源已准备就绪。 | 3235| 'playing' | 正在播放状态，在prepared/paused/completed状态调用[play()](#play9)方法，AVPlayer会进入playing状态。 | 3236| 'paused' | 暂停状态，在playing状态调用pause方法，AVPlayer会进入paused状态。 | 3237| 'completed' | 播放至结尾状态，当媒体资源播放至结尾时，如果用户未设置循环播放（loop = true），AVPlayer会进入completed状态，此时调用[play()](#play9)会进入playing状态和重播，调用[stop()](#stop9)会进入stopped状态。 | 3238| 'stopped' | 停止状态，在prepared/playing/paused/completed状态调用[stop()](#stop9)方法，AVPlayer会进入stopped状态，此时播放引擎只会保留属性，但会释放内存资源，可以调用[prepare()](#prepare9)重新准备，也可以调用[reset()](#reset9)重置，或者调用[release()](#release9)彻底销毁。 | 3239| 'released' | 销毁状态，销毁与当前AVPlayer关联的播放引擎，无法再进行状态转换，调用[release()](#release9)方法后，会进入released状态，结束流程。 | 3240| 'error' | 错误状态，当**播放引擎**发生**不可逆的错误**（详见[媒体错误码](errorcode-media.md)），则会转换至当前状态，可以调用[reset()](#reset9)重置，也可以调用[release()](#release9)销毁重建。<br/>**注意：** 区分error状态和 [on('error')](#onerror9) ：<br/>1、进入error状态时，会触发on('error')监听事件，可以通过on('error')事件获取详细错误信息；<br/>2、处于error状态时，播放服务进入不可播控的状态，要求客户端设计容错机制，使用[reset()](#reset9)重置或者[release()](#release9)销毁重建；<br/>3、如果客户端收到on('error')，但未进入error状态：<br/>原因1：客户端未按状态机调用API或传入参数错误，被AVPlayer拦截提醒，需要客户端调整代码逻辑；<br/>原因2：播放过程发现码流问题，导致容器、解码短暂异常，不影响连续播放和播控操作的，不需要客户端设计容错机制。 | 3241 3242## OnTrackChangeHandler<sup>12+</sup> 3243 3244type OnTrackChangeHandler = (index: number, isSelected: boolean) => void 3245 3246track变更事件回调方法。 3247 3248**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3249 3250**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3251 3252| 参数名 | 类型 | 必填 | 说明 | 3253| ------ | ------ | ------ | ---------------------------------------------------------- | 3254| index | number | 是 | 当前变更的track索引。 | 3255| isSelected | boolean | 是 | 当前变更的track索引是否被选中。true表示处于选中状态，false表示处于非选中状态。 | 3256 3257## OnAVPlayerStateChangeHandle<sup>12+</sup> 3258 3259type OnAVPlayerStateChangeHandle = (state: AVPlayerState, reason: StateChangeReason) => void 3260 3261状态机切换事件回调方法。 3262 3263**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3264 3265**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3266 3267| 参数名 | 类型 | 必填 | 说明 | 3268| ------ | ------ | ------ | ---------------------------------------------------------- | 3269| state | [AVPlayerState](#avplayerstate9) | 是 | 当前播放状态。 | 3270| reason | [StateChangeReason](#statechangereason9) | 是 | 当前播放状态的切换原因。 | 3271 3272## OnBufferingUpdateHandler<sup>12+</sup> 3273 3274type OnBufferingUpdateHandler = (infoType: BufferingInfoType, value: number) => void 3275 3276播放缓存事件回调方法。 3277 3278**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3279 3280**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3281 3282| 参数名 | 类型 | 必填 | 说明 | 3283| ------ | ------ | ------ | ------------------------------------------------------------ | 3284| infoType | [BufferingInfoType](#bufferinginfotype8) | 是 | 缓存时间类型。 | 3285| value | number | 是 | value值固定为0。 | 3286 3287## OnVideoSizeChangeHandler<sup>12+</sup> 3288 3289type OnVideoSizeChangeHandler = (width: number, height: number) => void 3290 3291视频播放宽高变化事件回调方法。 3292 3293**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3294 3295**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3296 3297| 参数名 | 类型 | 必填 | 说明 | 3298| ------ | ------ | ------ | ------------------------------------------------------------ | 3299| width | number | 是 | 视频宽度，单位为像素（px）。| 3300| height | number | 是 | 视频高度，单位为像素（px）。| 3301 3302## OnSeiMessageHandle<sup>18+</sup> 3303 3304type OnSeiMessageHandle = (messages: Array\<SeiMessage>, playbackPosition?: number) => void 3305 3306获取SEI信息，使用场景：订阅SEI信息事件，回调返回SEI详细信息。 3307 3308**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3309 3310**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3311 3312**参数：** 3313 3314| 参数名 | 类型 | 必填 | 说明 | 3315| ------ | ------ | ---- | ------------------------------------------------------------ | 3316| messages | Array\<[SeiMessage](#seimessage18)> | 是 | SEI信息。 | 3317| playbackPosition | number | 否 | 获取当前播放位置（单位：毫秒）。 | 3318 3319## OnSuperResolutionChanged <sup>18+</sup> 3320 3321type OnSuperResolutionChanged = (enabled: boolean) => void 3322 3323视频超分开关事件回调方法。若通过[PlaybackStrategy](#playbackstrategy12)正确使能超分，超分算法状态变化时会通过此回调上报，视频起播时也会上报超分初始开启/关闭状态。若未使能超分，不会触发该回调。 3324 3325出现以下两种情况，超分算法会自动关闭。 3326* 目前超分算法最高仅支持30帧及以下的视频。若视频帧率超过30帧，或者在倍速播放等场景下导致输入帧率超出超分算法处理能力，超分会自动关闭。 3327* 目前超分算法支持输入分辨率范围为320x320 ~ 1920x1080，单位为像素。若播放过程中输入视频分辨率超出此范围，超分算法会自动关闭。 3328 3329**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3330 3331**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3332 3333| 参数名 | 类型 | 必填 | 说明 | 3334| ------ | ------ | ------ | ------------------------------------------------------------ | 3335| enabled | boolean | 是 | 表示当前超分是否开启。true表示超分开启，false表示超分关闭。 | 3336 3337## OnPlaybackRateDone<sup>20+</sup> 3338 3339type OnPlaybackRateDone = (rate: number) => void 3340 3341播放速率设置完成事件回调方法。 3342 3343**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 3344 3345**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3346 3347| 参数名 | 类型 | 必填 | 说明 | 3348| ------ | ------ | ------ | ------------------------------------------------------------ | 3349| rate | number | 是 | 播放速率。 | 3350 3351## AVFileDescriptor<sup>9+</sup> 3352 3353音视频文件资源描述，一种特殊资源的播放方式，使用场景：应用中的音频资源被连续存储在同一个文件中，需要根据偏移量和长度进行播放。 3354 3355**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3356 3357**系统能力：** SystemCapability.Multimedia.Media.Core 3358 3359| 名称 | 类型 | 必填 | 说明 | 3360| ------ | ------ | ---- | ------------------------------------------------------------ | 3361| fd | number | 是 | 资源句柄，通过[resourceManager.getRawFd](../apis-localization-kit/js-apis-resource-manager.md#getrawfd9)获取,也可以通过[fs.open](../apis-core-file-kit/js-apis-file-fs.md#fsopen)获取。 | 3362| offset | number | 否 | 资源偏移量，默认值为0，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 3363| length | number | 否 | 资源长度，默认值为文件中从偏移量开始的剩余字节，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 3364 3365## AVDataSrcDescriptor<sup>10+</sup> 3366 3367音视频文件资源描述，用于DataSource播放方式，使用场景：应用在未获取完整音视频资源时，允许用户创建播放实例并开始播放，达到提前播放的目的。 3368 3369**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3370 3371**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3372 3373| 名称 | 类型 | 必填 | 说明 | 3374| ------ | ------ | ---- | ------------------------------------------------------------ | 3375| fileSize | number | 是 | 待播放文件大小（字节），-1代表大小未知。如果fileSize设置为-1, 播放模式类似于直播，不能进行seek及setSpeed操作，不能设置loop属性，因此不能重新播放。 | 3376| callback | (buffer: ArrayBuffer, length: number, pos?: number) => number | 是 | 用户设置的回调函数，用于填写数据。<br>- 函数列式：callback: (buffer: ArrayBuffer, length: number, pos?:number) => number;<br>- buffer，ArrayBuffer类型，表示被填写的内存，必选。<br>- length，number类型，表示被填写内存的最大长度，必选。<br>- pos，number类型，表示填写的数据在资源文件中的位置，可选，当fileSize设置为-1时，该参数禁止被使用。 <br>- 返回值，number类型，返回填充数据的长度，返回-1表示到达流的末尾，返回-2表示遇到不可恢复的错误。| 3377 3378## SubtitleInfo<sup>12+</sup> 3379 3380外挂字幕信息，使用场景：订阅外挂字幕事件，回调返回外挂字幕详细信息。 3381 3382**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3383 3384**系统能力：** SystemCapability.Multimedia.Media.Core 3385 3386| 名称 | 类型 | 必填 | 说明 | 3387| ------ | ------ | ---- | ------------------------------------------------------------ | 3388| text | string | 否 | 字幕文本信息。 | 3389| startTime | number | 否 | 显示当前字幕文本的开始时间（单位：毫秒）。 | 3390| duration | number | 否 | 显示当前字幕文本的持续时间（单位：毫秒）。 | 3391 3392## SeiMessage<sup>18+</sup> 3393 3394SEI信息内容，描述SEI信息的负载类型和数据。 3395 3396**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3397 3398**系统能力：** SystemCapability.Multimedia.Media.Core 3399 3400| 名称 | 类型 | 只读 | 可选 | 说明 | 3401| ------ | ------ | ---- | ---- | ------------------------------------------------------------ | 3402| payloadType | number | 否 | 否 | SEI信息的负载类型。 | 3403| payload | ArrayBuffer | 否 | 否 | SEI信息的负载数据。 | 3404 3405## SeekMode<sup>8+</sup> 3406 3407视频播放的Seek模式枚举，可通过seek方法作为参数传递下去。 3408 3409**系统能力：** SystemCapability.Multimedia.Media.Core 3410 3411| 名称 | 值 | 说明 | 3412| -------------- | ---- | ------------------------------------------------------------ | 3413| SEEK_NEXT_SYNC | 0 | 表示跳转到指定时间点的下一个关键帧，建议向后快进的时候用这个枚举值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 3414| SEEK_PREV_SYNC | 1 | 表示跳转到指定时间点的上一个关键帧，建议向前快进的时候用这个枚举值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 3415| SEEK_CLOSEST<sup>12+</sup> | 2 | 表示跳转到距离指定时间点最近的帧，建议精准跳转进度的时候用这个枚举值。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3416| SEEK_CONTINUOUS<sup>18+</sup> | 3 | 该模式提供了一种画面平滑流畅变化的Seek体验，应用可以结合进度条控件持续调用Seek方法，AVPlayer根据Seek调用持续流畅地更新画面。<br>应用可以调用[isSeekContinuousSupported](#isseekcontinuoussupported18)方法根据返回结果感知视频源是否支持该模式Seek。<br>对于不支持该Seek模式的视频源调用该模式Seek时，会上报AVERR_SEEK_CONTINUOUS_UNSUPPORTED错误([媒体错误码](#averrorcode9))，同时画面更新的流畅性会降低。<br>该Seek模式不会触发[seekDone事件](#onseekdone9)。<br>当应用需要退出该模式下的Seek时，需要调用`seek(-1, SeekMode.SEEK_CONTINUOUS)`来结束该模式下的Seek。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 3417 3418## SwitchMode<sup>12+</sup> 3419 3420视频播放的selectTrack模式枚举，可通过selectTrack方法作为参数传递下去，当前仅DASH协议视频轨支持该扩展参数。 3421 3422**系统能力：** SystemCapability.Multimedia.Media.Core 3423 3424| 名称 | 值 | 说明 | 3425| -------------- | ---- | ------------------------------------------------------------ | 3426| SMOOTH | 0 | 表示切换后视频平滑播放，该模式切换存在延迟，不会立即生效。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3427| SEGMENT | 1 | 表示切换后从当前分片开始位置播放，该模式立即切换，会有重复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3428| CLOSEST | 2 | 表示从距离当前播放时间点最近的帧开始播放，该模式立即切换，切换后会卡住3到5s，然后恢复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3429 3430## PlaybackSpeed<sup>8+</sup> 3431 3432视频播放的倍速枚举，可通过setSpeed方法作为参数传递下去。 3433 3434**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3435 3436**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 3437 3438| 名称 | 值 | 说明 | 3439| -------------------- | ---- | ------------------------------ | 3440| SPEED_FORWARD_0_75_X | 0 | 表示视频播放正常播速的0.75倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3441| SPEED_FORWARD_1_00_X | 1 | 表示视频播放正常播速。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3442| SPEED_FORWARD_1_25_X | 2 | 表示视频播放正常播速的1.25倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3443| SPEED_FORWARD_1_75_X | 3 | 表示视频播放正常播速的1.75倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3444| SPEED_FORWARD_2_00_X | 4 | 表示视频播放正常播速的2.00倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3445| SPEED_FORWARD_0_50_X<sup>12+</sup> | 5 | 表示视频播放正常播速的0.50倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3446| SPEED_FORWARD_1_50_X<sup>12+</sup> | 6 | 表示视频播放正常播速的1.50倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3447| SPEED_FORWARD_3_00_X<sup>13+</sup> | 7 | 表示视频播放正常播速的3.00倍。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 3448| SPEED_FORWARD_0_25_X<sup>12+</sup> | 8 | 表示视频播放正常播速的0.25倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3449| SPEED_FORWARD_0_125_X<sup>12+</sup> | 9 | 表示视频播放正常播速的0.125倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3450 3451## VideoScaleType<sup>9+</sup> 3452 3453枚举，视频缩放模式。 3454 3455**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3456 3457**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 3458 3459| 名称 | 值 | 说明 | 3460| ----------------------------| ---- | ------------------------------------------------ | 3461| VIDEO_SCALE_TYPE_FIT | 0 | 默认比例类型，视频拉伸至与窗口等大。 | 3462| VIDEO_SCALE_TYPE_FIT_CROP | 1 | 保持视频宽高比缩放至最短边填满窗口，长边超出窗口部分被裁剪。 | 3463| VIDEO_SCALE_TYPE_FIT_ASPECT<sup>20+</sup> | 2 | 保持视频宽高比缩放至长边填满窗口，短边居中对齐，未填满部分留黑。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 3464 3465## MediaDescription<sup>8+</sup> 3466 3467通过key-value方式获取媒体信息。 3468 3469**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3470 3471**系统能力：** SystemCapability.Multimedia.Media.Core 3472 3473| 名称 | 类型 | 必填 | 说明 | 3474| ------------- | ------ | ---- | ------------------------------------------------------------ | 3475| [key: string] | Object | 是 | 该键值对支持的key取值范围，请参考[MediaDescriptionKey](#mediadescriptionkey8);每个key值的Object类型和范围，请参考[MediaDescriptionKey](#mediadescriptionkey8)对应Key值的说明 | 3476 3477**示例：** 3478 3479```ts 3480import { BusinessError } from '@kit.BasicServicesKit'; 3481 3482function printfItemDescription(obj: media.MediaDescription, key: string) { 3483 let property: Object = obj[key]; 3484 console.info('audio key is ' + key); // 通过key值获取对应的value。key值具体可见[MediaDescriptionKey]。 3485 console.info('audio value is ' + property); //对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[MediaDescriptionKey]。 3486} 3487 3488let avPlayer: media.AVPlayer | undefined = undefined; 3489media.createAVPlayer((err: BusinessError, player: media.AVPlayer) => { 3490 if(player != null) { 3491 avPlayer = player; 3492 console.info(`Succeeded in creating AVPlayer`); 3493 avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 3494 if (arrList != null) { 3495 for (let i = 0; i < arrList.length; i++) { 3496 printfItemDescription(arrList[i], media.MediaDescriptionKey.MD_KEY_TRACK_TYPE); //打印出每条轨道MD_KEY_TRACK_TYPE的值。 3497 } 3498 } else { 3499 console.error(`Failed to get TrackDescription, error:${error}`); 3500 } 3501 }); 3502 } else { 3503 console.error(`Failed to create AVPlayer, error message:${err.message}`); 3504 } 3505}); 3506``` 3507 3508## PlaybackInfo<sup>12+</sup> 3509 3510通过key-value方式获取播放信息。 3511 3512**系统能力：** SystemCapability.Multimedia.Media.Core 3513 3514| 名称 | 类型 | 必填 | 说明 | 3515| ------------- | ------ | ---- | ------------------------------------------------------------ | 3516| [key: string] | Object | 是 | 该键值对支持的key取值范围，请参考[PlaybackInfoKey](#playbackinfokey12);每个key值的Object类型和范围，请参考[PlaybackInfoKey](#playbackinfokey12)对应Key值的说明。 | 3517 3518**示例：** 3519 3520```ts 3521import { BusinessError } from '@kit.BasicServicesKit'; 3522 3523function printfPlaybackInfo(obj: media.PlaybackInfo, key: string) { 3524 let property: Object = obj[key]; 3525 console.info('key is ' + key); // 通过key值获取对应的value。key值具体可见[PlaybackInfoKey]。 3526 console.info('value is ' + property); //对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[PlaybackInfoKey]。 3527} 3528 3529let avPlayer: media.AVPlayer | undefined = undefined; 3530let playbackInfo: media.PlaybackInfo | undefined = undefined; 3531media.createAVPlayer(async (err: BusinessError, player: media.AVPlayer) => { 3532 if (player != null) { 3533 avPlayer = player; 3534 console.info(`Succeeded in creating AVPlayer`); 3535 if (avPlayer) { 3536 try { 3537 playbackInfo = await avPlayer.getPlaybackInfo(); 3538 console.info(`AVPlayer getPlaybackInfo = ${JSON.stringify(playbackInfo)}`); // 打印整个PlaybackInfo的值。 3539 printfPlaybackInfo(playbackInfo, media.PlaybackInfoKey.SERVER_IP_ADDRESS); // 打印ip的值。 3540 } catch (error) { 3541 console.error(`error = ${error}`); 3542 } 3543 } 3544 } else { 3545 console.error(`Failed to create AVPlayer, error message:${err.message}`); 3546 } 3547}); 3548``` 3549 3550## AVRecorder<sup>9+</sup> 3551 3552音视频录制管理类，用于音视频媒体录制。在调用AVRecorder的方法前，需要先通过[createAVRecorder()](#mediacreateavrecorder9)构建一个AVRecorder实例。 3553 3554音视频录制demo可参考：[音频录制开发指导](../../media/media/using-avrecorder-for-recording.md)、[视频录制开发指导](../../media/media/video-recording.md)。 3555 3556> **说明：** 3557> 3558> 使用相机进行视频录制时，需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/arkts-apis-camera.md)。 3559 3560### 属性 3561 3562**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3563 3564| 名称 | 类型 | 只读 | 可选 | 说明 | 3565| ------- | ------------------------------------ | ---- | ---- | ------------------ | 3566| state9+ | [AVRecorderState](#avrecorderstate9) | 是 | 否 | 音视频录制的状态。<br>**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 3567 3568### prepare<sup>9+</sup> 3569 3570prepare(config: AVRecorderConfig, callback: AsyncCallback\<void>): void 3571 3572异步方式进行音视频录制的参数设置。通过注册回调函数获取返回值。 3573 3574**需要权限：** ohos.permission.MICROPHONE 3575 3576不涉及音频录制时，可以不需要获取ohos.permission.MICROPHONE权限。 3577 3578使用相机视频录制还需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/arkts-apis-camera.md)。 3579 3580**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3581 3582**参数：** 3583 3584| 参数名 | 类型 | 必填 | 说明 | 3585| -------- | -------------------------------------- | ---- | ------------------------------------- | 3586| config | [AVRecorderConfig](#avrecorderconfig9) | 是 | 配置音视频录制的相关参数。 | 3587| callback | AsyncCallback\<void> | 是 | 回调函数。当prepare方法成功，err为undefined，否则为错误对象。 | 3588 3589**错误码：** 3590 3591以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3592 3593| 错误码ID | 错误信息 | 3594| -------- | --------------------------------------- | 3595| 201 | Permission denied. Return by callback. | 3596| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3597| 5400102 | Operate not permit. Return by callback. | 3598| 5400105 | Service died. Return by callback. | 3599 3600**示例：** 3601 3602```ts 3603import { BusinessError } from '@kit.BasicServicesKit'; 3604 3605// 配置参数以实际硬件设备支持的范围为准。 3606let avRecorderProfile: media.AVRecorderProfile = { 3607 audioBitrate : 48000, 3608 audioChannels : 2, 3609 audioCodec : media.CodecMimeType.AUDIO_AAC, 3610 audioSampleRate : 48000, 3611 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 3612 videoBitrate : 2000000, 3613 videoCodec : media.CodecMimeType.VIDEO_AVC, 3614 videoFrameWidth : 640, 3615 videoFrameHeight : 480, 3616 videoFrameRate : 30 3617}; 3618let avRecorderConfig: media.AVRecorderConfig = { 3619 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 3620 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 3621 profile : avRecorderProfile, 3622 url : 'fd://', // 文件需先由调用者创建，赋予读写权限，将文件fd传给此参数，eg.fd://45 3623 rotation : 0, // 合理值0、90、180、270，非合理值prepare接口将报错。 3624 location : { latitude : 30, longitude : 130 } 3625}; 3626 3627avRecorder.prepare(avRecorderConfig, (err: BusinessError) => { 3628 if (err) { 3629 console.error('Failed to prepare and error is ' + err.message); 3630 } else { 3631 console.info('Succeeded in preparing'); 3632 } 3633}); 3634``` 3635 3636### prepare<sup>9+</sup> 3637 3638prepare(config: AVRecorderConfig): Promise\<void> 3639 3640异步方式进行音视频录制的参数设置。通过Promise获取返回值。 3641 3642**需要权限：** ohos.permission.MICROPHONE 3643 3644不涉及音频录制时，可以不需要获ohos.permission.MICROPHONE权限。 3645 3646使用相机视频录制还需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/arkts-apis-camera.md)。 3647 3648**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3649 3650**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3651 3652**参数：** 3653 3654| 参数名 | 类型 | 必填 | 说明 | 3655| ------ | -------------------------------------- | ---- | -------------------------- | 3656| config | [AVRecorderConfig](#avrecorderconfig9) | 是 | 配置音视频录制的相关参数。 | 3657 3658**返回值：** 3659 3660| 类型 | 说明 | 3661| -------------- | ------------------------------------------ | 3662| Promise\<void> | 异步音视频录制prepare方法的Promise返回值。 | 3663 3664**错误码：** 3665 3666以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3667 3668| 错误码ID | 错误信息 | 3669| -------- | -------------------------------------- | 3670| 201 | Permission denied. Return by promise. | 3671| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3672| 5400102 | Operate not permit. Return by promise. | 3673| 5400105 | Service died. Return by promise. | 3674 3675**示例：** 3676 3677```ts 3678import { BusinessError } from '@kit.BasicServicesKit'; 3679 3680// 配置参数以实际硬件设备支持的范围为准。 3681let avRecorderProfile: media.AVRecorderProfile = { 3682 audioBitrate : 48000, 3683 audioChannels : 2, 3684 audioCodec : media.CodecMimeType.AUDIO_AAC, 3685 audioSampleRate : 48000, 3686 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 3687 videoBitrate : 2000000, 3688 videoCodec : media.CodecMimeType.VIDEO_AVC, 3689 videoFrameWidth : 640, 3690 videoFrameHeight : 480, 3691 videoFrameRate : 30 3692}; 3693let avRecorderConfig: media.AVRecorderConfig = { 3694 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 3695 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 3696 profile : avRecorderProfile, 3697 url : 'fd://', // 文件需先由调用者创建，赋予读写权限，将文件fd传给此参数，eg.fd://45 3698 rotation : 0, // 合理值0、90、180、270，非合理值prepare接口报错。 3699 location : { latitude : 30, longitude : 130 } 3700}; 3701 3702avRecorder.prepare(avRecorderConfig).then(() => { 3703 console.info('Succeeded in preparing'); 3704}).catch((err: BusinessError) => { 3705 console.error('Failed to prepare and catch error is ' + err.message); 3706}); 3707``` 3708 3709### getInputSurface<sup>9+</sup> 3710 3711getInputSurface(callback: AsyncCallback\<string>): void 3712 3713异步方式获得录制需要的surface。通过注册回调函数获取返回值。此surface提供给调用者，调用者从此surface中获取surfaceBuffer，填入相应的视频数据。 3714 3715应当注意，填入的视频数据需要携带时间戳（单位ns）和buffersize。时间戳的起始时间请以系统启动时间为基准。 3716 3717需在[prepare()](#prepare9-2)事件成功触发后，才能调用getInputSurface()方法。 3718 3719**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3720 3721**参数：** 3722 3723| 参数名 | 类型 | 必填 | 说明 | 3724| -------- | ---------------------- | ---- | --------------------------- | 3725| callback | AsyncCallback\<string> | 是 | 回调函数。当获取surface成功，err为undefined，data为获取到的surfaceId，否则为错误对象。 | 3726 3727**错误码：** 3728 3729以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3730 3731| 错误码ID | 错误信息 | 3732| -------- | --------------------------------------- | 3733| 5400102 | Operate not permit. Return by callback. | 3734| 5400103 | IO error. Return by callback. | 3735| 5400105 | Service died. Return by callback. | 3736 3737**示例：** 3738 3739```ts 3740import { BusinessError } from '@kit.BasicServicesKit'; 3741let surfaceID: string; // 该surfaceID用于传递给相机接口创造videoOutput。 3742 3743avRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 3744 if (err) { 3745 console.error('Failed to do getInputSurface and error is ' + err.message); 3746 } else { 3747 console.info('Succeeded in doing getInputSurface'); 3748 surfaceID = surfaceId; 3749 } 3750}); 3751 3752``` 3753 3754### getInputSurface<sup>9+</sup> 3755 3756getInputSurface(): Promise\<string> 3757 3758异步方式获得录制需要的surface。通过Promise获取返回值。此surface提供给调用者，调用者从此surface中获取surfaceBuffer，填入相应的视频数据。 3759 3760应当注意，填入的视频数据需要携带时间戳（单位ns）和buffersize。时间戳的起始时间请以系统启动时间为基准。 3761 3762需在[prepare()](#prepare9-3)事件成功触发后，才能调用getInputSurface方法。 3763 3764**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3765 3766**返回值：** 3767 3768| 类型 | 说明 | 3769| ---------------- | -------------------------------- | 3770| Promise\<string> | 异步获得surface的Promise返回值。 | 3771 3772**错误码：** 3773 3774以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3775 3776| 错误码ID | 错误信息 | 3777| -------- | -------------------------------------- | 3778| 5400102 | Operate not permit. Return by promise. | 3779| 5400103 | IO error. Return by promise. | 3780| 5400105 | Service died. Return by promise. | 3781 3782**示例：** 3783 3784```ts 3785import { BusinessError } from '@kit.BasicServicesKit'; 3786let surfaceID: string; // 该surfaceID用于传递给相机接口创造videoOutput。 3787 3788avRecorder.getInputSurface().then((surfaceId: string) => { 3789 console.info('Succeeded in getting InputSurface'); 3790 surfaceID = surfaceId; 3791}).catch((err: BusinessError) => { 3792 console.error('Failed to get InputSurface and catch error is ' + err.message); 3793}); 3794``` 3795 3796### updateRotation<sup>12+</sup> 3797 3798updateRotation(rotation: number): Promise\<void> 3799 3800更新视频旋转角度。通过Promise获取返回值。 3801 3802当且仅当[prepare()](#prepare9-3)事件成功触发后，且在[start()](#start9)之前，才能调用updateRotation方法。 3803 3804**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3805 3806**参数：** 3807 3808| 参数名 | 类型 | 必填 | 说明 | 3809| -------- | -------------------- | ---- | --------------------------- | 3810| rotation | number | 是 | 旋转角度，取值仅支持0、90、180、270度。 | 3811 3812**返回值：** 3813 3814| 类型 | 说明 | 3815| ---------------- | -------------------------------- | 3816| Promise\<void> | 异步返回函数执行结果。 | 3817 3818**错误码：** 3819 3820以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3821 3822| 错误码ID | 错误信息 | 3823| -------- | -------------------------------------- | 3824| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3825| 5400102 | Operation not allowed. Return by promise. | 3826| 5400103 | IO error. Return by promise. | 3827| 5400105 | Service died. Return by promise. | 3828 3829**示例：** 3830 3831```ts 3832import { BusinessError } from '@kit.BasicServicesKit'; 3833 3834let rotation = 90; 3835 3836avRecorder.updateRotation(rotation).then(() => { 3837 console.info('Succeeded in updateRotation'); 3838}).catch((err: BusinessError) => { 3839 console.error('Failed to updateRotation and catch error is ' + err.message); 3840}); 3841``` 3842 3843### setWillMuteWhenInterrupted<sup>20+</sup> 3844 3845setWillMuteWhenInterrupted(muteWhenInterrupted: boolean): Promise<void> 3846 3847设置当前录制音频流是否启用静音打断模式。使用Promise异步回调。 3848 3849**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3850 3851**参数：** 3852 3853| 参数名 | 类型 | 必填 | 说明 | 3854| ---------- |---------------- | ------ |---------------------------------------------------------| 3855| muteWhenInterrupted | boolean | 是 | 设置当前录制音频流是否启用静音打断模式, true表示启用，false表示不启用，保持为默认打断模式。 | 3856 3857**返回值：** 3858 3859| 类型 | 说明 | 3860| ------------------- | ----------------------------- | 3861| Promise<void>| Promise对象。无返回结果的Promise对象。| 3862 3863**错误码：** 3864 3865以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3866 3867| 错误码ID | 错误信息 | 3868| -------- | -------------------------------------- | 3869| 5400102 | Operation not allowed. Return by promise. | 3870| 5400105 | Service died. Return by promise. | 3871 3872**示例：** 3873 3874```ts 3875import { BusinessError } from '@kit.BasicServicesKit'; 3876 3877avRecorder.setWillMuteWhenInterrupted(true).then(() => { 3878 console.info('setWillMuteWhenInterrupted Success!'); 3879}).catch((err: BusinessError) => { 3880 console.error(`setWillMuteWhenInterrupted Fail: ${err}`); 3881}); 3882``` 3883 3884### start<sup>9+</sup> 3885 3886start(callback: AsyncCallback\<void>): void 3887 3888异步方式开始视频录制。通过注册回调函数获取返回值。 3889 3890纯音频录制需在[prepare()](#prepare9-2)事件成功触发后，才能调用start方法。纯视频录制，音视频录制需在[getInputSurface()](#getinputsurface9)事件成功触发后，才能调用start方法。 3891 3892**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3893 3894**参数：** 3895 3896| 参数名 | 类型 | 必填 | 说明 | 3897| -------- | -------------------- | ---- | ---------------------------- | 3898| callback | AsyncCallback\<void> | 是 |回调函数。当开始录制视频成功，err为undefined，否则为错误对象。 | 3899 3900**错误码：** 3901 3902以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3903 3904| 错误码ID | 错误信息 | 3905| -------- | --------------------------------------- | 3906| 5400102 | Operate not permit. Return by callback. | 3907| 5400103 | IO error. Return by callback. | 3908| 5400105 | Service died. Return by callback. | 3909 3910**示例：** 3911 3912```ts 3913import { BusinessError } from '@kit.BasicServicesKit'; 3914 3915avRecorder.start((err: BusinessError) => { 3916 if (err) { 3917 console.error('Failed to start AVRecorder and error is ' + err.message); 3918 } else { 3919 console.info('Succeeded in starting AVRecorder'); 3920 } 3921}); 3922``` 3923 3924### start<sup>9+</sup> 3925 3926start(): Promise\<void> 3927 3928异步方式开始视频录制。通过Promise获取返回值。 3929 3930纯音频录制需在[prepare()](#prepare9-3)事件成功触发后，才能调用start方法。纯视频录制，音视频录制需在[getInputSurface()](#getinputsurface9-1)事件成功触发后，才能调用start方法。 3931 3932**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3933 3934**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3935 3936**返回值：** 3937 3938| 类型 | 说明 | 3939| -------------- | ------------------------------------- | 3940| Promise\<void> | 异步开始视频录制方法的Promise返回值。 | 3941 3942**错误码：** 3943 3944以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3945 3946| 错误码ID | 错误信息 | 3947| -------- | -------------------------------------- | 3948| 5400102 | Operate not permit. Return by promise. | 3949| 5400103 | IO error. Return by promise. | 3950| 5400105 | Service died. Return by promise. | 3951 3952**示例：** 3953 3954```ts 3955import { BusinessError } from '@kit.BasicServicesKit'; 3956 3957avRecorder.start().then(() => { 3958 console.info('Succeeded in starting AVRecorder'); 3959}).catch((err: BusinessError) => { 3960 console.error('Failed to start AVRecorder and catch error is ' + err.message); 3961}); 3962``` 3963 3964### pause<sup>9+</sup> 3965 3966pause(callback: AsyncCallback\<void>): void 3967 3968异步方式暂停视频录制。通过注册回调函数获取返回值。 3969 3970需要[start()](#start9)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume9)接口来恢复录制。 3971 3972**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3973 3974**参数：** 3975 3976| 参数名 | 类型 | 必填 | 说明 | 3977| -------- | -------------------- | ---- | --------------------------- | 3978| callback | AsyncCallback\<void> | 是 | 回调函数。当暂停视频录制成功，err为undefined，否则为错误对象。 | 3979 3980**错误码：** 3981 3982以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3983 3984| 错误码ID | 错误信息 | 3985| -------- | --------------------------------------- | 3986| 5400102 | Operate not permit. Return by callback. | 3987| 5400103 | IO error. Return by callback. | 3988| 5400105 | Service died. Return by callback. | 3989 3990**示例：** 3991 3992```ts 3993import { BusinessError } from '@kit.BasicServicesKit'; 3994 3995avRecorder.pause((err: BusinessError) => { 3996 if (err) { 3997 console.error('Failed to pause AVRecorder and error is ' + err.message); 3998 } else { 3999 console.info('Succeeded in pausing'); 4000 } 4001}); 4002``` 4003 4004### pause<sup>9+</sup> 4005 4006pause(): Promise\<void> 4007 4008异步方式暂停视频录制。通过Promise获取返回值。 4009 4010需要[start()](#start9-1)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume9-1)接口来恢复录制。 4011 4012**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 4013 4014**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4015 4016**返回值：** 4017 4018| 类型 | 说明 | 4019| -------------- | ------------------------------------- | 4020| Promise\<void> | 异步暂停视频录制方法的Promise返回值。 | 4021 4022**错误码：** 4023 4024以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4025 4026| 错误码ID | 错误信息 | 4027| -------- | -------------------------------------- | 4028| 5400102 | Operate not permit. Return by promise. | 4029| 5400103 | IO error. Return by promise. | 4030| 5400105 | Service died. Return by promise. | 4031 4032**示例：** 4033 4034```ts 4035import { BusinessError } from '@kit.BasicServicesKit'; 4036 4037avRecorder.pause().then(() => { 4038 console.info('Succeeded in pausing'); 4039}).catch((err: BusinessError) => { 4040 console.error('Failed to pause AVRecorder and catch error is ' + err.message); 4041}); 4042``` 4043 4044### resume<sup>9+</sup> 4045 4046resume(callback: AsyncCallback\<void>): void 4047 4048异步方式恢复视频录制。通过注册回调函数获取返回值。 4049 4050需要在[pause()](#pause9-2)事件成功触发后，才能调用resume方法。 4051 4052**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4053 4054**参数：** 4055 4056| 参数名 | 类型 | 必填 | 说明 | 4057| -------- | -------------------- | ---- | ---------------------------- | 4058| callback | AsyncCallback\<void> | 是 | 回调函数。当恢复视频录制成功，err为undefined，否则为错误对象。 | 4059 4060**错误码：** 4061 4062以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4063 4064| 错误码ID | 错误信息 | 4065| -------- | --------------------------------------- | 4066| 5400102 | Operate not permit. Return by callback. | 4067| 5400103 | IO error. Return by callback. | 4068| 5400105 | Service died. Return by callback. | 4069 4070**示例：** 4071 4072```ts 4073import { BusinessError } from '@kit.BasicServicesKit'; 4074 4075avRecorder.resume((err: BusinessError) => { 4076 if (err) { 4077 console.error('Failed to resume AVRecorder and error is ' + err.message); 4078 } else { 4079 console.info('Succeeded in resuming AVRecorder'); 4080 } 4081}); 4082``` 4083 4084### resume<sup>9+</sup> 4085 4086resume(): Promise\<void> 4087 4088异步方式恢复视频录制。通过Promise获取返回值。 4089 4090需要在[pause()](#pause9-3)事件成功触发后，才能调用resume方法。 4091 4092**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 4093 4094**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4095 4096**返回值：** 4097 4098| 类型 | 说明 | 4099| -------------- | ------------------------------------- | 4100| Promise\<void> | 异步恢复视频录制方法的Promise返回值。 | 4101 4102**错误码：** 4103 4104以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4105 4106| 错误码ID | 错误信息 | 4107| -------- | -------------------------------------- | 4108| 5400102 | Operate not permit. Return by promise. | 4109| 5400103 | IO error. Return by promise. | 4110| 5400105 | Service died. Return by promise. | 4111 4112**示例：** 4113 4114```ts 4115import { BusinessError } from '@kit.BasicServicesKit'; 4116 4117avRecorder.resume().then(() => { 4118 console.info('Succeeded in resuming AVRecorder'); 4119}).catch((err: BusinessError) => { 4120 console.error('Failed to resume AVRecorder failed and catch error is ' + err.message); 4121}); 4122``` 4123 4124### stop<sup>9+</sup> 4125 4126stop(callback: AsyncCallback\<void>): void 4127 4128异步方式停止视频录制。通过注册回调函数获取返回值。 4129 4130需要在[start()](#start9)或[pause()](#pause9-2)事件成功触发后，才能调用stop方法。 4131 4132纯音频录制时，需要重新调用[prepare()](#prepare9-2)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-2)和[getInputSurface()](#getinputsurface9)接口才能重新录制。 4133 4134**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4135 4136**参数：** 4137 4138| 参数名 | 类型 | 必填 | 说明 | 4139| -------- | -------------------- | ---- | ---------------------------- | 4140| callback | AsyncCallback\<void> | 是 | 回调函数。当停止视频录制成功，err为undefined，否则为错误对象。 | 4141 4142**错误码：** 4143 4144以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4145 4146| 错误码ID | 错误信息 | 4147| -------- | --------------------------------------- | 4148| 5400102 | Operate not permit. Return by callback. | 4149| 5400103 | IO error. Return by callback. | 4150| 5400105 | Service died. Return by callback. | 4151 4152**示例：** 4153 4154```ts 4155import { BusinessError } from '@kit.BasicServicesKit'; 4156 4157avRecorder.stop((err: BusinessError) => { 4158 if (err) { 4159 console.error('Failed to stop AVRecorder and error is ' + err.message); 4160 } else { 4161 console.info('Succeeded in stopping AVRecorder'); 4162 } 4163}); 4164``` 4165 4166### stop<sup>9+</sup> 4167 4168stop(): Promise\<void> 4169 4170异步方式停止视频录制。通过Promise获取返回值。 4171 4172需要在[start()](#start9-1)或[pause()](#pause9-3)事件成功触发后，才能调用stop方法。 4173 4174纯音频录制时，需要重新调用[prepare()](#prepare9-3)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-3)和[getInputSurface()](#getinputsurface9-1)接口才能重新录制。 4175 4176**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 4177 4178**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4179 4180**返回值：** 4181 4182| 类型 | 说明 | 4183| -------------- | ------------------------------------- | 4184| Promise\<void> | 异步停止视频录制方法的Promise返回值。 | 4185 4186**错误码：** 4187 4188以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4189 4190| 错误码ID | 错误信息 | 4191| -------- | -------------------------------------- | 4192| 5400102 | Operate not permit. Return by promise. | 4193| 5400103 | IO error. Return by promise. | 4194| 5400105 | Service died. Return by promise. | 4195 4196**示例：** 4197 4198```ts 4199import { BusinessError } from '@kit.BasicServicesKit'; 4200 4201avRecorder.stop().then(() => { 4202 console.info('Succeeded in stopping AVRecorder'); 4203}).catch((err: BusinessError) => { 4204 console.error('Failed to stop AVRecorder and catch error is ' + err.message); 4205}); 4206``` 4207 4208### reset<sup>9+</sup> 4209 4210reset(callback: AsyncCallback\<void>): void 4211 4212异步方式重置音视频录制。通过注册回调函数获取返回值。 4213 4214纯音频录制时，需要重新调用[prepare()](#prepare9-2)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-2)和[getInputSurface()](#getinputsurface9)接口才能重新录制。 4215 4216**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4217 4218**参数：** 4219 4220| 参数名 | 类型 | 必填 | 说明 | 4221| -------- | -------------------- | ---- | ------------------------------ | 4222| callback | AsyncCallback\<void> | 是 | 回调函数。当重置音视频录制成功，err为undefined，否则为错误对象。 | 4223 4224**错误码：** 4225 4226以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4227 4228| 错误码ID | 错误信息 | 4229| -------- | --------------------------------- | 4230| 5400103 | IO error. Return by callback. | 4231| 5400105 | Service died. Return by callback. | 4232 4233**示例：** 4234 4235```ts 4236import { BusinessError } from '@kit.BasicServicesKit'; 4237 4238avRecorder.reset((err: BusinessError) => { 4239 if (err) { 4240 console.error('Failed to reset AVRecorder and error is ' + err.message); 4241 } else { 4242 console.info('Succeeded in resetting AVRecorder'); 4243 } 4244}); 4245``` 4246 4247### reset<sup>9+</sup> 4248 4249reset(): Promise\<void> 4250 4251异步方式重置音视频录制。通过Promise获取返回值。 4252 4253纯音频录制时，需要重新调用[prepare()](#prepare9-3)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-3)和[getInputSurface()](#getinputsurface9-1)接口才能重新录制。 4254 4255**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4256 4257**返回值：** 4258 4259| 类型 | 说明 | 4260| -------------- | --------------------------------------- | 4261| Promise\<void> | 异步重置音视频录制方法的Promise返回值。 | 4262 4263**错误码：** 4264 4265以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4266 4267| 错误码ID | 错误信息 | 4268| -------- | -------------------------------- | 4269| 5400103 | IO error. Return by promise. | 4270| 5400105 | Service died. Return by promise. | 4271 4272**示例：** 4273 4274```ts 4275import { BusinessError } from '@kit.BasicServicesKit'; 4276 4277avRecorder.reset().then(() => { 4278 console.info('Succeeded in resetting AVRecorder'); 4279}).catch((err: BusinessError) => { 4280 console.error('Failed to reset and catch error is ' + err.message); 4281}); 4282``` 4283 4284### release<sup>9+</sup> 4285 4286release(callback: AsyncCallback\<void>): void 4287 4288异步方式释放音视频录制资源。通过注册回调函数获取返回值。 4289 4290释放音视频录制资源之后，该AVRecorder实例不能再进行任何操作。 4291 4292**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4293 4294**参数：** 4295 4296| 参数名 | 类型 | 必填 | 说明 | 4297| -------- | -------------------- | ---- | ---------------------------------- | 4298| callback | AsyncCallback\<void> | 是 | 回调函数。当释放音视频录制资源成功，err为undefined，否则为错误对象。 | 4299 4300**错误码：** 4301 4302以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4303 4304| 错误码ID | 错误信息 | 4305| -------- | --------------------------------- | 4306| 5400105 | Service died. Return by callback. | 4307 4308**示例：** 4309 4310```ts 4311import { BusinessError } from '@kit.BasicServicesKit'; 4312 4313avRecorder.release((err: BusinessError) => { 4314 if (err) { 4315 console.error('Failed to release AVRecorder and error is ' + err.message); 4316 } else { 4317 console.info('Succeeded in releasing AVRecorder'); 4318 } 4319}); 4320``` 4321 4322### release<sup>9+</sup> 4323 4324release(): Promise\<void> 4325 4326异步方式释放音视频录制资源。通过Promise获取返回值。 4327 4328释放音视频录制资源之后，该AVRecorder实例不能再进行任何操作。 4329 4330**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 4331 4332**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4333 4334**返回值：** 4335 4336| 类型 | 说明 | 4337| -------------- | ------------------------------------------- | 4338| Promise\<void> | 异步释放音视频录制资源方法的Promise返回值。 | 4339 4340**错误码：** 4341 4342以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4343 4344| 错误码ID | 错误信息 | 4345| -------- | --------------------------------- | 4346| 5400105 | Service died. Return by callback. | 4347 4348**示例：** 4349 4350```ts 4351import { BusinessError } from '@kit.BasicServicesKit'; 4352 4353avRecorder.release().then(() => { 4354 console.info('Succeeded in releasing AVRecorder'); 4355}).catch((err: BusinessError) => { 4356 console.error('Failed to release AVRecorder and catch error is ' + err.message); 4357}); 4358``` 4359 4360### getCurrentAudioCapturerInfo<sup>11+</sup> 4361 4362getCurrentAudioCapturerInfo(callback: AsyncCallback\<audio.AudioCapturerChangeInfo>): void 4363 4364异步方式获取当前音频采集参数。通过注册回调函数获取返回值。 4365 4366在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 4367 4368**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4369 4370**参数**： 4371 4372| 参数名 | 类型 | 必填 | 说明 | 4373| -------- | ------------------------------------------------------------ | ---- | ------------------------------------ | 4374| callback | AsyncCallback\<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 是 | 回调函数。当获取音频采集参数成功时，err为undefined，data为获取到的audio.AudioCapturerChangeInfo，否则为错误对象。 | 4375 4376**错误码**： 4377 4378以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4379 4380| 错误码ID | 错误信息 | 4381| -------- | ------------------------------------------ | 4382| 5400102 | Operation not allowed. | 4383| 5400103 | I/O error. | 4384| 5400105 | Service died. Return by callback. | 4385 4386**示例**： 4387 4388```ts 4389import { audio } from '@kit.AudioKit'; 4390 4391let currentCapturerInfo: audio.AudioCapturerChangeInfo; 4392 4393avRecorder.getCurrentAudioCapturerInfo((err: BusinessError, capturerInfo: audio.AudioCapturerChangeInfo) => { 4394 if (err) { 4395 console.error('Failed to get CurrentAudioCapturerInfo and error is ' + err.message); 4396 } else { 4397 console.info('Succeeded in getting CurrentAudioCapturerInfo'); 4398 currentCapturerInfo = capturerInfo; 4399 } 4400}); 4401``` 4402 4403### getCurrentAudioCapturerInfo<sup>11+</sup> 4404 4405getCurrentAudioCapturerInfo(): Promise\<audio.AudioCapturerChangeInfo> 4406 4407异步方式获取当前音频采集参数。通过Promise获取返回值。 4408 4409在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 4410 4411**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4412 4413**返回值**： 4414 4415| 类型 | 说明 | 4416| ------------------------------------------------------------ | ------------------------------------------------- | 4417| Promise\<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | Promise对象，返回获取的当前音频采集参数。 | 4418 4419**错误码**： 4420 4421以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4422 4423| 错误码ID | 错误信息 | 4424| -------- | -------------------------------- | 4425| 5400102 | Operation not allowed. | 4426| 5400103 | I/O error. | 4427| 5400105 | Service died. Return by promise. | 4428 4429**示例**： 4430 4431```ts 4432import { audio } from '@kit.AudioKit'; 4433 4434let currentCapturerInfo: audio.AudioCapturerChangeInfo; 4435 4436avRecorder.getCurrentAudioCapturerInfo().then((capturerInfo: audio.AudioCapturerChangeInfo) => { 4437 console.info('Succeeded in getting CurrentAudioCapturerInfo'); 4438 currentCapturerInfo = capturerInfo; 4439}).catch((err: BusinessError) => { 4440 console.error('Failed to get CurrentAudioCapturerInfo and catch error is ' + err.message); 4441}); 4442``` 4443 4444### getAudioCapturerMaxAmplitude<sup>11+</sup> 4445 4446getAudioCapturerMaxAmplitude(callback: AsyncCallback\<number>): void 4447 4448异步方式获取当前音频最大振幅。通过注册回调函数获取返回值。 4449 4450在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 4451 4452调用接口时，获取到的返回值是上一次获取最大振幅的时刻到当前这段区间内的音频最大振幅。即，如果在1s的时刻获取了一次最大振幅，在2s时再获取到的最大振幅时1-2s这个区间里面的最大值。 4453 4454**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4455 4456**参数**： 4457 4458| 参数名 | 类型 | 必填 | 说明 | 4459| -------- | ---------------------- | ---- | ------------------------------------ | 4460| callback | AsyncCallback\<number> | 是 | 回调函数。获取当前音频最大振幅成功时，err为undefined，data为获取到的最大振幅，否则为错误对象。 | 4461 4462**错误码**： 4463 4464以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4465 4466| 错误码ID | 错误信息 | 4467| -------- | ------------------------------------------ | 4468| 5400102 | Operation not allowed. | 4469| 5400105 | Service died. Return by callback. | 4470 4471**示例**： 4472 4473```ts 4474let maxAmplitude: number; 4475 4476avRecorder.getAudioCapturerMaxAmplitude((err: BusinessError, amplitude: number) => { 4477 if (err) { 4478 console.error('Failed to get AudioCapturerMaxAmplitude and error is ' + err.message); 4479 } else { 4480 console.info('Succeeded in getting AudioCapturerMaxAmplitude'); 4481 maxAmplitude = amplitude; 4482 } 4483}); 4484``` 4485 4486### getAudioCapturerMaxAmplitude<sup>11+</sup> 4487 4488getAudioCapturerMaxAmplitude(): Promise\<number> 4489 4490异步方式获取当前音频最大振幅参数。通过Promise获取返回值。 4491 4492在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 4493 4494调用接口时，获取到的返回值是上一次获取最大振幅的时刻到当前这段区间内的音频最大振幅。即，如果在1s的时刻获取了一次最大振幅，在2s时再获取到的最大振幅时1-2s这个区间里面的最大值。 4495 4496**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4497 4498**返回值**： 4499 4500| 类型 | 说明 | 4501| ---------------- | ------------------------------------------------- | 4502| Promise\<number> | Promise对象，返回获取的当前音频最大振幅。 | 4503 4504**错误码**： 4505 4506以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4507 4508| 错误码ID | 错误信息 | 4509| -------- | -------------------------------- | 4510| 5400102 | Operation not allowed. | 4511| 5400105 | Service died. Return by promise. | 4512 4513**示例**： 4514 4515```ts 4516let maxAmplitude: number; 4517 4518avRecorder.getAudioCapturerMaxAmplitude().then((amplitude: number) => { 4519 console.info('Succeeded in getting AudioCapturerMaxAmplitude'); 4520 maxAmplitude = amplitude; 4521}).catch((err: BusinessError) => { 4522 console.error('Failed to get AudioCapturerMaxAmplitude and catch error is ' + err.message); 4523}); 4524``` 4525 4526### getAvailableEncoder<sup>11+</sup> 4527 4528getAvailableEncoder(callback: AsyncCallback\<Array\<EncoderInfo>>): void 4529 4530异步方式获取可用的编码器参数。通过注册回调函数获取返回值。 4531 4532**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4533 4534**参数**： 4535 4536| 参数名 | 类型 | 必填 | 说明 | 4537| -------- | ----------------------------------------------------- | ---- | ------------------------------------ | 4538| callback | AsyncCallback\<Array\<[EncoderInfo](#encoderinfo11)>> | 是 | 回调函数。获取可用的编码器参数成功时，err为undefined，data为获取到的编码器参数，否则为错误对象。 | 4539 4540**错误码**： 4541 4542以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4543 4544| 错误码ID | 错误信息 | 4545| -------- | ------------------------------------------ | 4546| 5400102 | Operation not allowed. | 4547| 5400105 | Service died. Return by callback. | 4548 4549**示例**： 4550 4551```ts 4552let encoderInfo: media.EncoderInfo; 4553 4554avRecorder.getAvailableEncoder((err: BusinessError, info: media.EncoderInfo[]) => { 4555 if (err) { 4556 console.error('Failed to get AvailableEncoder and error is ' + err.message); 4557 } else { 4558 console.info('Succeeded in getting AvailableEncoder'); 4559 encoderInfo = info[0]; 4560 } 4561}); 4562``` 4563 4564### getAvailableEncoder<sup>11+</sup> 4565 4566getAvailableEncoder(): Promise\<Array\<EncoderInfo>> 4567 4568异步方式获取可用的编码器参数。通过注册回调函数获取返回值。 4569 4570**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4571 4572**返回值**： 4573 4574| 类型 | 说明 | 4575| ----------------------------------------------- | ----------------------------------------------- | 4576| Promise\<Array\<[EncoderInfo](#encoderinfo11)>> | Promise对象，返回获取的可用的编码器参数。 | 4577 4578**错误码**： 4579 4580以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4581 4582| 错误码ID | 错误信息 | 4583| -------- | -------------------------------- | 4584| 5400102 | Operation not allowed. | 4585| 5400105 | Service died. Return by promise. | 4586 4587**示例**： 4588 4589```ts 4590let encoderInfo: media.EncoderInfo; 4591 4592avRecorder.getAvailableEncoder().then((info: media.EncoderInfo[]) => { 4593 console.info('Succeeded in getting AvailableEncoder'); 4594 encoderInfo = info[0]; 4595}).catch((err: BusinessError) => { 4596 console.error('Failed to get AvailableEncoder and catch error is ' + err.message); 4597}); 4598``` 4599 4600### getAVRecorderConfig<sup>11+</sup> 4601 4602getAVRecorderConfig(callback: AsyncCallback\<AVRecorderConfig>): void 4603 4604异步方式获取实时的配置参数。通过注册回调函数获取返回值。 4605 4606只能在[prepare()](#prepare9-2)接口调用后调用。 4607 4608**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4609 4610**参数：** 4611 4612| 参数名 | 类型 | 必填 | 说明 | 4613| -------- | ---------------------- | ---- | --------------------------- | 4614| callback | AsyncCallback\<[AVRecorderConfig](#avrecorderconfig9)> | 是 | 回调函数。获取实时配置的参数成功时，err为undefined，data为获取到的配置参数，否则为错误对象。 | 4615 4616**错误码：** 4617 4618以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 4619 4620| 错误码ID | 错误信息 | 4621| -------- | ------------------------------------------ | 4622| 5400102 | Operate not permit. Return by callback. | 4623| 5400103 | IO error. Return by callback. | 4624| 5400105 | Service died. Return by callback. | 4625 4626**示例：** 4627 4628```ts 4629import { BusinessError } from '@kit.BasicServicesKit'; 4630 4631let avConfig: media.AVRecorderConfig; 4632 4633avRecorder.getAVRecorderConfig((err: BusinessError, config: media.AVRecorderConfig) => { 4634 if (err) { 4635 console.error('Failed to get avConfig and error is ' + err.message); 4636 } else { 4637 console.info('Succeeded in getting AVRecorderConfig'); 4638 avConfig = config; 4639 } 4640}); 4641``` 4642 4643### getAVRecorderConfig<sup>11+</sup> 4644 4645getAVRecorderConfig(): Promise\<AVRecorderConfig>; 4646 4647异步方式获取实时的配置参数。通过Promise获取返回值。 4648 4649只能在[prepare()](#prepare9-3)接口调用后调用。 4650 4651**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4652 4653**返回值：** 4654 4655| 类型 | 说明 | 4656| ---------------- | -------------------------------- | 4657| Promise\<[AVRecorderConfig](#avrecorderconfig9)> | 异步获得实时配置参数的回调方法。 | 4658 4659**错误码：** 4660 4661以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 4662 4663| 错误码ID | 错误信息 | 4664| -------- | ----------------------------------------- | 4665| 5400102 | Operate not permit. Return by promise. | 4666| 5400103 | IO error. Return by promise. | 4667| 5400105 | Service died. Return by promise. | 4668 4669**示例：** 4670 4671```ts 4672import { BusinessError } from '@kit.BasicServicesKit'; 4673 4674let avConfig: media.AVRecorderConfig; 4675 4676avRecorder.getAVRecorderConfig().then((config: media.AVRecorderConfig) => { 4677 console.info('Succeeded in getting AVRecorderConfig'); 4678 avConfig = config; 4679}).catch((err: BusinessError) => { 4680 console.error('Failed to get AVRecorderConfig and catch error is ' + err.message); 4681}); 4682``` 4683 4684### on('stateChange')<sup>9+</sup> 4685 4686on(type: 'stateChange', callback: OnAVRecorderStateChangeHandler): void 4687 4688订阅录制状态机AVRecorderState切换的事件，当 AVRecorderState状态机发生变化时，会通过订阅的回调方法通知用户。用户只能订阅一个状态机切换事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 4689 4690**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4691 4692**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4693 4694**参数：** 4695 4696| 参数名 | 类型 | 必填 | 说明 | 4697| -------- | -------- | ---- | ------------------------------------------------------------ | 4698| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 4699| callback | [OnAVRecorderStateChangeHandler](#onavrecorderstatechangehandler12) | 是 | 状态机切换事件回调方法。 | 4700 4701**错误码：** 4702 4703以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4704 4705| 错误码ID | 错误信息 | 4706| -------- | --------------------------------- | 4707| 5400103 | IO error. Return by callback. | 4708| 5400105 | Service died. Return by callback. | 4709 4710**示例：** 4711 4712```ts 4713avRecorder.on('stateChange', async (state: media.AVRecorderState, reason: media.StateChangeReason) => { 4714 console.info('case state has changed, new state is :' + state + ',and new reason is : ' + reason); 4715}); 4716``` 4717 4718### off('stateChange')<sup>9+</sup> 4719 4720off(type: 'stateChange', callback?: OnAVRecorderStateChangeHandler): void 4721 4722取消订阅播放状态机[AVRecorderState](#avrecorderstate9)切换的事件。 4723 4724**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4725 4726**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4727 4728**参数：** 4729 4730| 参数名 | 类型 | 必填 | 说明 | 4731| ------ | ------ | ---- | ------------------------------------------------------------ | 4732| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 4733| callback | [OnAVRecorderStateChangeHandler](#onavrecorderstatechangehandler12) | 否 | 状态机切换事件回调方法。<br/>从API version 12开始支持此参数。 | 4734 4735**示例：** 4736 4737```ts 4738avRecorder.off('stateChange'); 4739``` 4740 4741### on('error')<sup>9+</sup> 4742 4743on(type: 'error', callback: ErrorCallback): void 4744 4745订阅AVRecorder的错误事件，该事件仅用于错误提示，不需要用户停止播控动作。如果此时[AVRecorderState](#avrecorderstate9)也切至error状态，用户需要通过[reset()](#reset9-2)或者[release()](#release9-2)退出录制操作。 4746 4747用户只能订阅一个错误事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 4748 4749**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4750 4751**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4752 4753**参数：** 4754 4755| 参数名 | 类型 | 必填 | 说明 | 4756| -------- | ------------- | ---- | ------------------------------------------------------------ | 4757| type | string | 是 | 录制错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 4758| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录制错误事件回调方法。 | 4759 4760**错误码：** 4761 4762以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4763 4764| 错误码ID | 错误信息 | 4765| -------- | ------------------------------------------ | 4766| 201 | Permission denied. | 4767| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 4768| 801 | Capability not supported. | 4769| 5400101 | No memory. | 4770| 5400102 | Operation not allowed. | 4771| 5400103 | I/O error. | 4772| 5400104 | Time out. | 4773| 5400105 | Service died. | 4774| 5400106 | Unsupported format. | 4775| 5400107 | Audio interrupted. | 4776 4777**示例：** 4778 4779```ts 4780import { BusinessError } from '@kit.BasicServicesKit'; 4781 4782avRecorder.on('error', (err: BusinessError) => { 4783 console.info('case avRecorder.on(error) called, errMessage is ' + err.message); 4784}); 4785``` 4786 4787### off('error')<sup>9+</sup> 4788 4789off(type: 'error', callback?: ErrorCallback): void 4790 4791取消订阅录制错误事件，取消后不再接收到AVRecorder的错误事件。 4792 4793**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4794 4795**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4796 4797**参数：** 4798 4799| 参数名 | 类型 | 必填 | 说明 | 4800| ------ | ------ | ---- | ------------------------------------------------------------ | 4801| type | string | 是 | 录制错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 4802| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 录制错误事件回调方法。<br/>从API version 12开始支持此参数。 | 4803 4804**示例：** 4805 4806```ts 4807avRecorder.off('error'); 4808``` 4809 4810### on('audioCapturerChange')<sup>11+</sup> 4811 4812on(type: 'audioCapturerChange', callback: Callback<audio.AudioCapturerChangeInfo>): void 4813 4814订阅录音配置变化的回调，任意录音配置的变化会触发变化后的录音配置全量信息回调。 4815 4816当用户重复订阅时，以最后一次订阅的回调接口为准。 4817 4818**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4819 4820**参数：** 4821 4822| 参数名 | 类型 | 必填 | 说明 | 4823| -------- | -------- | ---- | ------------------------------------------------------------ | 4824| type | string | 是 |录音配置变化的回调类型，支持的事件：'audioCapturerChange'。 | 4825| callback | Callback<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 是 | 变化后的录音配置全量信息。| 4826 4827**错误码：** 4828 4829| 错误码ID | 错误信息 | 4830| -------- | ------------------------------------------ | 4831| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 4832 4833**示例：** 4834 4835```ts 4836import { audio } from '@kit.AudioKit' 4837 4838let capturerChangeInfo: audio.AudioCapturerChangeInfo; 4839 4840avRecorder.on('audioCapturerChange', (audioCapturerChangeInfo: audio.AudioCapturerChangeInfo) => { 4841 console.info('audioCapturerChange called'); 4842 capturerChangeInfo = audioCapturerChangeInfo; 4843}); 4844``` 4845 4846### off('audioCapturerChange')<sup>11+</sup> 4847 4848off(type: 'audioCapturerChange', callback?: Callback<audio.AudioCapturerChangeInfo>): void 4849 4850取消订阅录音变化的回调事件。 4851 4852**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4853 4854**参数：** 4855 4856| 参数名 | 类型 | 必填 | 说明 | 4857| ------ | ------ | ---- | ------------------------------------------------------------ | 4858| type | string | 是 | 录音配置变化的回调类型，支持的事件：'audioCapturerChange'。 | 4859| callback | Callback<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 否 | 变化后的录音配置全量信息。<br/>从API version 12开始支持此参数。| 4860 4861**示例：** 4862 4863```ts 4864avRecorder.off('audioCapturerChange'); 4865``` 4866 4867### on('photoAssetAvailable')<sup>12+</sup> 4868 4869on(type: 'photoAssetAvailable', callback: Callback\<photoAccessHelper.PhotoAsset>): void 4870 4871订阅媒体资源回调事件，当[FileGenerationMode](#filegenerationmode12)枚举设置为系统创建媒体文件时，会在[stop](#stop9-2)操作结束后把[PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)对象回调给应用。 4872 4873当用户重复订阅时，以最后一次订阅的回调接口为准。 4874 4875**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4876 4877**参数：** 4878 4879| 参数名 | 类型 | 必填 | 说明 | 4880| -------- | -------- | ---- | ------------------------------------------------------------ | 4881| type | string | 是 |录像资源的回调类型，支持的事件：'photoAssetAvailable'。 | 4882| callback | Callback<[photoAccessHelper.PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)> | 是 | 系统创建的资源文件对应的PhotoAsset对象。| 4883 4884**错误码：** 4885 4886| 错误码ID | 错误信息 | 4887| -------- | ------------------------------------------ | 4888| 5400103 | IO error. Return by callback. | 4889| 5400105 | Service died. Return by callback. | 4890 4891**示例：** 4892 4893<!--code_no_check--> 4894```ts 4895import { photoAccessHelper } from '@kit.MediaLibraryKit'; 4896import { common } from '@kit.AbilityKit' 4897let photoAsset: photoAccessHelper.PhotoAsset; 4898private context: Context | undefined; 4899constructor(context: Context) { 4900 this.context = context; // this.getUIContext().getHostContext(); 4901} 4902 4903// 例:处理photoAsset回调，保存video。 4904async function saveVideo(asset: photoAccessHelper.PhotoAsset) { 4905 console.info("saveVideo called"); 4906 try { 4907 let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(this.context); 4908 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset); 4909 assetChangeRequest.saveCameraPhoto(); 4910 await phAccessHelper.applyChanges(assetChangeRequest); 4911 console.info('apply saveVideo successfully'); 4912 } catch (err) { 4913 console.error(`apply saveVideo failed with error: ${err.code}, ${err.message}`); 4914 } 4915} 4916// 注册photoAsset监听。 4917avRecorder.on('photoAssetAvailable', (asset: photoAccessHelper.PhotoAsset) => { 4918 console.info('photoAssetAvailable called'); 4919 if (asset != undefined) { 4920 photoAsset = asset; 4921 // 处理photoAsset回调。 4922 // 例: this.saveVideo(asset); 4923 } else { 4924 console.error('photoAsset is undefined'); 4925 } 4926}); 4927``` 4928 4929### off('photoAssetAvailable')<sup>12+</sup> 4930 4931off(type: 'photoAssetAvailable', callback?: Callback<photoAccessHelper.PhotoAsset>): void 4932 4933取消订阅媒体资源的回调类型。 4934 4935**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4936 4937**参数：** 4938 4939| 参数名 | 类型 | 必填 | 说明 | 4940| ------ | ------ | ---- | ------------------------------------------------------------ | 4941| type | string | 是 | 录音配置变化的回调类型，支持的事件：'photoAssetAvailable'。 | 4942| callback | Callback<[photoAccessHelper.PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)> | 否 | 系统创建的资源文件对应的PhotoAsset对象。| 4943 4944**示例：** 4945 4946```ts 4947avRecorder.off('photoAssetAvailable'); 4948``` 4949 4950## AVRecorderState<sup>9+</sup> 4951 4952type AVRecorderState = 'idle' | 'prepared' | 'started' | 'paused' | 'stopped' | 'released' | 'error' 4953 4954音视频录制的状态机。可通过state属性获取当前状态。 4955 4956**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 4957 4958**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4959 4960| 类型 | 说明 | 4961| -------- | ------------------------------------------------------------ | 4962| 'idle' | 闲置状态。此时可以调用[AVRecorder.prepare()](#prepare9-2)方法设置录制参数，进入prepared状态。AVRecorder刚被创建，或者在任何非released状态下调用[AVRecorder.reset()](#reset9-2)方法，均进入idle状态。 | 4963| 'prepared' | 参数设置完成。此时可以调用[AVRecorder.start()](#start9)方法开始录制，进入started状态。 | 4964| 'started' | 正在录制。此时可以调用[AVRecorder.pause()](#pause9-2)方法暂停录制，进入paused状态。也可以调用[AVRecorder.stop()](#stop9-2)方法结束录制，进入stopped状态。 | 4965| 'paused' | 录制暂停。此时可以调用[AVRecorder.resume()](#resume9)方法继续录制，进入started状态。也可以调用[AVRecorder.stop()](#stop9-2)方法结束录制，进入stopped状态。 | 4966| 'stopped' | 录制停止。此时可以调用[AVRecorder.prepare()](#prepare9-2)方法设置录制参数，重新进入prepared状态。 | 4967| 'released' | 录制资源释放。此时不能再进行任何操作。在任何其他状态下，均可以通过调用[AVRecorder.release()](#release9-2)方法进入released状态。 | 4968| 'error' | 错误状态。当AVRecorder实例发生不可逆错误，会转换至当前状态。切换至error状态时会伴随[AVRecorder.on('error')事件](#onerror9-1)，该事件会上报详细错误原因。在error状态时，用户需要调用[AVRecorder.reset()](#reset9-2)方法重置AVRecorder实例，或者调用[AVRecorder.release()](#release9-2)方法释放资源。 | 4969 4970## OnAVRecorderStateChangeHandler<sup>12+</sup> 4971 4972type OnAVRecorderStateChangeHandler = (state: AVRecorderState, reason: StateChangeReason) => void 4973 4974状态机切换事件回调方法。 4975 4976**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4977 4978**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4979 4980| 参数名 | 类型 | 必填 | 说明 | 4981| ------ | ------ | ------ | ------------------------------------------------------------ | 4982| state | [AVRecorderState](#avrecorderstate9) | 是 | 当前录制状态。 | 4983| reason | [StateChangeReason](#statechangereason9) | 是 | 当前录制状态的切换原因。 | 4984 4985## AVRecorderConfig<sup>9+</sup> 4986 4987表示音视频录制的参数设置。 4988 4989通过audioSourceType和videoSourceType区分纯音频录制、纯视频录制或音视频录制。纯音频录制时，仅需要设置audioSourceType；纯视频录制时，仅需要设置videoSourceType；音视频录制时，audioSourceType和videoSourceType均需要设置。 4990 4991**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4992 4993| 名称 | 类型 | 必填 | 说明 | 4994| --------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 4995| audioSourceType | [AudioSourceType](#audiosourcetype9) | 否 | 选择录制的音频源类型。选择音频录制时必填。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4996| videoSourceType | [VideoSourceType](#videosourcetype9) | 否 | 选择录制的视频源类型。选择视频录制时必填。 | 4997| profile | [AVRecorderProfile](#avrecorderprofile9) | 是 | 录制的profile，必要参数。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4998| url | string | 是 | 录制输出URL：fd://xx (fd number) ，必要参数。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4999|fileGenerationMode<sup>12+</sup> | [FileGenerationMode](#filegenerationmode12) | 否 | 创建媒体文件的模式，配合[on('photoAssetAvailable')](#onphotoassetavailable12)监听使用。| 5000| rotation<sup>(deprecated)</sup> | number | 否 | 录制的视频旋转角度，mp4格式支持0，90，180，270，默认值为0。<br>从API version 6开始支持，从API version 12开始废弃。建议使用[AVMetadata](#avmetadata11).videoOrientation替代。如果同时设置两个值，将会采用[AVMetadata](#avmetadata11).videoOrientation。 | 5001| location<sup>(deprecated)</sup> | [Location](#location) | 否 | 录制的地理位置，默认不记录地理位置信息。<br>从API version 6开始支持，从API version 12开始废弃。建议使用 [AVMetadata](#avmetadata11).location。如果同时设置两个值，将会采用[AVMetadata](#avmetadata11).location。 | 5002| metadata<sup>12+</sup> | [AVMetadata](#avmetadata11) | 否 | 设置元数据信息。详情见 [AVMetadata](#avmetadata11)。 | 5003| maxDuration<sup>18+</sup> | number | 否 | 设置录制的最大时长，单位为秒，有效值取值范围[1 , 2^31-1]，无效输入会重置为最大值。录制到达设定时长后，录制会自动停止，并通过stateChange回调录制状态，[AVRecorderState](#avrecorderstate9) = 'stopped'，[StateChangeReason](#statechangereason9) = BACKGROUND。| 5004 5005## AVRecorderProfile<sup>9+</sup> 5006 5007音视频录制的配置文件。 5008 5009> **说明：** 5010> 此处提供音频参数配置的对照表，每项的具体释义，可查看下述字段解释。 5011> 5012> |编码格式|封装格式|采样率|比特率|声道数| 5013> |----|----|----|----|----| 5014> |AUDIO_AAC|MP4,M4A|[8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000]|[32000-500000]|[1-8]| 5015> |AUDIO_MP3|MP3|[8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000]|<br>- 采样率使用16000以下时，对应比特率范围为[8000 - 64000]。<br>- 采样率使用16000~32000时对应的比特率范围为[8000 - 160000]。<br>- 采样率使用32000以上时对应的比特率范围为[32000 - 320000]。|[1-2]| 5016> |AUDIO_G711MU|WAV|[8000]|[64000]|[1]| 5017> |AUDIO_AMR_NB<sup>18+</sup> |AMR|[8000]|[4750, 5150, 5900, 6700, 7400, 7950, 10200, 12200]|[1]| 5018> |AUDIO_AMR_WB<sup>18+</sup> |AMR|[16000]|[6600, 8850, 12650, 14250, 15850, 18250, 19850, 23050, 23850]|[1]| 5019 5020**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 5021 5022| 名称 | 类型 | 必填 | 说明 | 5023| ---------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 5024| audioBitrate | number | 否 | 音频编码比特率，选择音频录制时必填。<br>支持范围：<br>- AAC编码格式支持比特率范围[32000 - 500000]。<br>- G711-mulaw编码格式支持比特率范围[64000]。<br>- MP3编码格式支持范围[8000, 16000, 32000, 40000, 48000, 56000, 64000, 80000, 96000, 112000, 128000, 160000, 192000, 224000, 256000, 320000]。<br>当使用MP3编码格式时，采样率和比特率的映射关系： <br>- 采样率使用16K以下时，对应比特率范围为[8000 - 64000]。<br>- 采样率使用16K~32K时对应的比特率范围为[8000 - 160000]。<br>- 采样率使用32K以上时对应的比特率范围为[32000 - 320000]。<br>- AMR_NB编码格式支持比特率范围[4750, 5150, 5900, 6700, 7400, 7950, 10200, 12200]。<br>- AMR_WB编码格式支持比特率范围[6600, 8850, 12650, 14250, 15850, 18250, 19850, 23050, 23850]。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 5025| audioChannels | number | 否 | 音频采集声道数，选择音频录制时必填。<br>- AAC编码格式支持范围[1 - 8]。<br>- G711-mulaw编码格式支持范围[1]。<br>- MP3编码格式支持范围[1 - 2]。<br>- AMR-NB、AMR-WB编码格式支持范围[1]。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 5026| audioCodec | [CodecMimeType](#codecmimetype8) | 否 | 音频编码格式，选择音频录制时必填。当前支持AUDIO_AAC，AUDIO_MP3，AUDIO_G711MU, AUDIO_AMR_NB, AUDIO_AMR_WB。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 5027| audioSampleRate | number | 否 | 音频采样率，选择音频录制时必填。<br>支持范围：<br>- AAC编码支持采样率范围[8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000]。<br>- G711-mulaw编码支持采样率范围[8000]。<br>- MP3编码支持采样率范围[8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000]。<br>- AMR_NB编码支持采样率范围[8000]。<br>- AMR_WB编码支持采样率范围[16000]。<br>可变比特率模式，码率仅作参考。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 5028| fileFormat | [ContainerFormatType](#containerformattype8) | 是 | 文件的容器格式，必要参数。当前支持MP4、M4A、MP3、WAV、AMR、AAC封装格式，当前AAC音频封装默认为ADTS帧头格式。不支持在MP4封装格式下使用AUDIO_MP3编码格式。<br>**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 5029| videoBitrate | number | 否 | 视频编码比特率，选择视频录制时必填，支持范围[10000 - 100000000]。 | 5030| videoCodec | [CodecMimeType](#codecmimetype8) | 否 | 视频编码格式，选择视频录制时必填。当前支持VIDEO_AVC。| 5031| videoFrameWidth | number | 否 | 视频帧的宽，选择视频录制时必填，支持范围[176 - 4096]。 | 5032| videoFrameHeight | number | 否 | 视频帧的高，选择视频录制时必填，支持范围[144 - 4096]。 | 5033| videoFrameRate | number | 否 | 视频帧率，选择视频录制时必填，推荐范围[1 - 60]。 | 5034| isHdr<sup>11+</sup> | boolean | 否 | HDR编码，选择视频录制时选填，isHdr默认为false，对应编码格式没有要求，isHdr为true时，对应的编码格式必须为video/hevc。| 5035| enableTemporalScale<sup>12+</sup> | boolean | 否 | 视频录制是否支持时域分层编码功能，选择视频录制时选填，enableTemporalScale默认为false。设置为true时，编码输出的码流中部分帧可以支持跳过不编码。| 5036 5037## AudioSourceType<sup>9+</sup> 5038 5039表示视频录制中音频源类型的枚举。 5040 5041**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 5042 5043| 名称 | 值 | 说明 | 5044| ------------------------- | ---- | ---------------------- | 5045| AUDIO_SOURCE_TYPE_DEFAULT | 0 | 默认的音频输入源类型。 | 5046| AUDIO_SOURCE_TYPE_MIC | 1 | 表示MIC的音频输入源。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 5047| AUDIO_SOURCE_TYPE_VOICE_RECOGNITION<sup>12+</sup> | 2 | 表示语音识别场景的音频源。 | 5048| AUDIO_SOURCE_TYPE_VOICE_COMMUNICATION<sup>12+</sup> | 7 | 表示语音通话场景的音频源。 | 5049| AUDIO_SOURCE_TYPE_VOICE_MESSAGE<sup>12+</sup> | 10 | 表示短语音消息的音频源。 | 5050| AUDIO_SOURCE_TYPE_CAMCORDER<sup>12+</sup> | 13 | 表示相机录像的音频源。 | 5051 5052## VideoSourceType<sup>9+</sup> 5053 5054表示视频录制中视频源类型的枚举。 5055 5056**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 5057 5058| 名称 | 值 | 说明 | 5059| ----------------------------- | ---- | ------------------------------- | 5060| VIDEO_SOURCE_TYPE_SURFACE_YUV | 0 | 输入surface中携带的是raw data。 | 5061| VIDEO_SOURCE_TYPE_SURFACE_ES | 1 | 输入surface中携带的是ES data。 | 5062 5063## ContainerFormatType<sup>8+</sup> 5064 5065表示容器格式类型的枚举，缩写为CFT。 5066 5067**系统能力：** SystemCapability.Multimedia.Media.Core 5068 5069| 名称 | 值 | 说明 | 5070| ----------- | ----- | --------------------- | 5071| CFT_MPEG_4 | 'mp4' | 视频的容器格式，MP4。 | 5072| CFT_MPEG_4A | 'm4a' | 音频的容器格式，M4A。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 5073| CFT_MP3<sup>12+</sup> | 'mp3' | 音频的容器格式，MP3。 | 5074| CFT_WAV<sup>12+</sup> | 'wav' | 音频的容器格式，WAV。 | 5075| CFT_AMR<sup>18+</sup> | 'amr' | 音频的容器格式，AMR。 | 5076| CFT_AAC<sup>20+</sup> | 'aac' | 音频的容器格式，AAC。默认为ADTS帧头格式。 | 5077 5078## Location 5079 5080视频录制的地理位置。 5081 5082**系统能力：** SystemCapability.Multimedia.Media.Core 5083 5084| 名称 | 类型 | 必填 | 说明 | 5085| --------- | ------ | ---- | ---------------- | 5086| latitude | number | 是 | 地理位置的纬度，取值范围为[-90, 90]。 | 5087| longitude | number | 是 | 地理位置的经度，取值范围为[-180, 180]。 | 5088 5089## EncoderInfo<sup>11+</sup> 5090 5091编码器和规格参数 5092 5093系统能力：SystemCapability.Multimedia.Media.AVRecorder 5094 5095| 名称 | 类型 | 可读 | 可写 | 说明 | 5096| ---------- | -------------------------------- | ---- | ---- | ------------------------------------------------------------ | 5097| mimeType | [CodecMimeType](#codecmimetype8) | 是 | 否 | 编码器MIME类型名称。 | 5098| type | string | 是 | 否 | 编码器类型，audio表示音频编码器，video表示视频编码器。 | 5099| bitRate | [Range](#range11) | 是 | 否 | 比特率，包含该编码器的最大和最小值。 | 5100| frameRate | [Range](#range11) | 是 | 否 | 视频帧率，包含帧率的最大和最小值，仅视频编码器拥有。 | 5101| width | [Range](#range11) | 是 | 否 | 视频帧的宽度，包含宽度的最大和最小值，仅视频编码器拥有。 | 5102| height | [Range](#range11) | 是 | 否 | 视频帧的高度，包含高度的最大和最小值，仅视频编码器拥有。 | 5103| channels | [Range](#range11) | 是 | 否 | 音频采集声道数，包含声道数的最大和最小值，仅音频编码器拥有。 | 5104| sampleRate | Array\<number> | 是 | 否 | 音频采样率，包含所有可以使用的音频采样率值数组，具体数值依赖编码器类型，仅音频编码器拥有。 | 5105 5106## Range<sup>11+</sup> 5107 5108表示一个类型的范围 5109 5110系统能力：SystemCapability.Multimedia.Media.AVRecorder 5111 5112| 名称 | 类型 | 可读 | 可写 | 说明 | 5113| ---- | ------ | ---- | ---- | ------------ | 5114| min | number | 是 | 否 | 范围的最小值。 | 5115| max | number | 是 | 否 | 范围的最大值。 | 5116 5117## FileGenerationMode<sup>12+</sup> 5118 5119表示创建媒体文件模式的枚举。 5120 5121**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 5122 5123| 名称 | 值 | 说明 | 5124| ----------------------------- | ---- | ------------------------------- | 5125| APP_CREATE | 0 | 由应用自行在沙箱创建媒体文件。 | 5126| AUTO_CREATE_CAMERA_SCENE | 1 | 由系统创建媒体文件，当前仅在相机录制场景下生效，会忽略应用设置的url。 | 5127 5128## AVTranscoder<sup>12+</sup> 5129 5130视频转码管理类，用于视频转码。在调用AVTranscoder的方法前，需要先通过[createAVTranscoder()](#mediacreateavtranscoder12)构建一个AVTranscoder实例。 5131 5132视频转码demo可参考：[视频转码开发指导](../../media/media/using-avtranscoder-for-transcodering.md) 5133 5134### 属性 5135 5136**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5137 5138| 名称 | 类型 | 只读 | 可选 | 说明 | 5139| ------- | ------------------------------------ | ---- | ---- | ------------------ | 5140| fdSrc<sup>12+</sup> | [AVFileDescriptor](#avfiledescriptor9) | 否 | 否 | 源媒体文件描述，通过该属性设置数据源。<br/> **使用示例**：<br/>假设一个连续存储的媒体文件，地址偏移:0，字节长度:100。其文件描述为 AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVTranscoder 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。 | 5141| fdDst<sup>12+</sup> | number | 否 | 否 | 目标媒体文件描述，通过该属性设置数据输出。在创建AVTranscoder实例后，必须设置fdSrc和fdDst属性。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVTranscoder 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。 | 5142 5143### prepare<sup>12+</sup> 5144 5145prepare(config: AVTranscoderConfig): Promise\<void> 5146 5147异步方式进行视频转码的参数设置。通过Promise获取返回值。 5148 5149**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5150 5151**参数：** 5152 5153| 参数名 | 类型 | 必填 | 说明 | 5154| ------ | -------------------------------------- | ---- | -------------------------- | 5155| config | [AVTranscoderConfig](#avtranscoderconfig12) | 是 | 配置视频转码的相关参数。 <!--RP1--><!--RP1End-->| 5156 5157**返回值：** 5158 5159| 类型 | 说明 | 5160| -------------- | ------------------------------------------ | 5161| Promise\<void> | 异步视频转码prepare方法的Promise返回值。 | 5162 5163**错误码：** 5164 5165以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5166 5167| 错误码ID | 错误信息 | 5168| -------- | -------------------------------------- | 5169| 401 | The parameter check failed. Return by promise. | 5170| 5400102 | Operation not allowed. Return by promise. | 5171| 5400103 | IO error. Return by promise. | 5172| 5400105 | Service died. Return by promise. | 5173| 5400106 | Unsupported format. Returned by promise. | 5174 5175**示例：** 5176 5177```ts 5178import { BusinessError } from '@kit.BasicServicesKit'; 5179 5180// 配置参数以实际硬件设备支持的范围为准。 5181let avTranscoderConfig: media.AVTranscoderConfig = { 5182 audioBitrate : 200000, 5183 audioCodec : media.CodecMimeType.AUDIO_AAC, 5184 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 5185 videoBitrate : 3000000, 5186 videoCodec : media.CodecMimeType.VIDEO_AVC, 5187}; 5188 5189avTranscoder.prepare(avTranscoderConfig).then(() => { 5190 console.info('prepare success'); 5191}).catch((err: BusinessError) => { 5192 console.error('prepare failed and catch error is ' + err.message); 5193}); 5194``` 5195 5196### start<sup>12+</sup> 5197 5198start(): Promise\<void> 5199 5200异步方式开始视频转码。通过Promise获取返回值。 5201 5202需要[prepare()](#prepare12)事件成功触发后，才能调用start方法。 5203 5204**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5205 5206**返回值：** 5207 5208| 类型 | 说明 | 5209| -------------- | ------------------------------------- | 5210| Promise\<void> | 异步开始视频转码方法的Promise返回值。 | 5211 5212**错误码：** 5213 5214以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5215 5216| 错误码ID | 错误信息 | 5217| -------- | -------------------------------------- | 5218| 5400102 | Operation not allowed. Return by promise. | 5219| 5400103 | IO error. Return by promise. | 5220| 5400105 | Service died. Return by promise. | 5221 5222**示例：** 5223 5224```ts 5225import { BusinessError } from '@kit.BasicServicesKit'; 5226 5227avTranscoder.start().then(() => { 5228 console.info('start AVTranscoder success'); 5229}).catch((err: BusinessError) => { 5230 console.error('start AVTranscoder failed and catch error is ' + err.message); 5231}); 5232``` 5233 5234### pause<sup>12+</sup> 5235 5236pause(): Promise\<void> 5237 5238异步方式暂停视频转码。通过Promise获取返回值。 5239 5240需要[start()](#start12)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume12)接口来恢复转码。 5241 5242**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5243 5244**返回值：** 5245 5246| 类型 | 说明 | 5247| -------------- | ------------------------------------- | 5248| Promise\<void> | 异步暂停视频转码方法的Promise返回值。 | 5249 5250**错误码：** 5251 5252以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5253 5254| 错误码ID | 错误信息 | 5255| -------- | -------------------------------------- | 5256| 5400102 | Operation not allowed. Return by promise. | 5257| 5400103 | IO error. Return by promise. | 5258| 5400105 | Service died. Return by promise. | 5259 5260**示例：** 5261 5262```ts 5263import { BusinessError } from '@kit.BasicServicesKit'; 5264 5265avTranscoder.pause().then(() => { 5266 console.info('pause AVTranscoder success'); 5267}).catch((err: BusinessError) => { 5268 console.error('pause AVTranscoder failed and catch error is ' + err.message); 5269}); 5270``` 5271 5272### resume<sup>12+</sup> 5273 5274resume(): Promise\<void> 5275 5276异步方式恢复视频转码。通过Promise获取返回值。 5277 5278需要在[pause()](#pause12)事件成功触发后，才能调用resume方法。 5279 5280**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5281 5282**返回值：** 5283 5284| 类型 | 说明 | 5285| -------------- | ------------------------------------- | 5286| Promise\<void> | 异步恢复视频转码方法的Promise返回值。 | 5287 5288**错误码：** 5289 5290以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5291 5292| 错误码ID | 错误信息 | 5293| -------- | -------------------------------------- | 5294| 5400102 | Operation not allowed. Return by promise. | 5295| 5400103 | IO error. Return by promise. | 5296| 5400105 | Service died. Return by promise. | 5297 5298**示例：** 5299 5300```ts 5301import { BusinessError } from '@kit.BasicServicesKit'; 5302 5303avTranscoder.resume().then(() => { 5304 console.info('resume AVTranscoder success'); 5305}).catch((err: BusinessError) => { 5306 console.error('resume AVTranscoder failed and catch error is ' + err.message); 5307}); 5308``` 5309 5310### cancel<sup>12+</sup> 5311 5312cancel(): Promise\<void> 5313 5314异步方式取消视频转码。通过Promise获取返回值。 5315 5316需要在[prepare()](#prepare12)、[start()](#start12)、[pause()](#pause12)或[resume()](#resume12)事件成功触发后，才能调用cancel方法。 5317 5318**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5319 5320**返回值：** 5321 5322| 类型 | 说明 | 5323| -------------- | ------------------------------------- | 5324| Promise\<void> | 异步取消视频转码方法的Promise返回值。 | 5325 5326**错误码：** 5327 5328以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5329 5330| 错误码ID | 错误信息 | 5331| -------- | -------------------------------------- | 5332| 5400102 | Operation not allowed. Return by promise. | 5333| 5400103 | IO error. Return by promise. | 5334| 5400105 | Service died. Return by promise. | 5335 5336**示例：** 5337 5338```ts 5339import { BusinessError } from '@kit.BasicServicesKit'; 5340 5341avTranscoder.cancel().then(() => { 5342 console.info('cancel AVTranscoder success'); 5343}).catch((err: BusinessError) => { 5344 console.error('cancel AVTranscoder failed and catch error is ' + err.message); 5345}); 5346``` 5347 5348### release<sup>12+</sup> 5349 5350release(): Promise\<void> 5351 5352异步方式释放视频转码资源。通过Promise获取返回值。 5353 5354释放视频转码资源之后，该AVTranscoder实例不能再进行任何操作。 5355 5356**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5357 5358**返回值：** 5359 5360| 类型 | 说明 | 5361| -------------- | ------------------------------------------- | 5362| Promise\<void> | 异步释放视频转码资源方法的Promise返回值。 | 5363 5364**错误码：** 5365 5366以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5367 5368| 错误码ID | 错误信息 | 5369| -------- | --------------------------------- | 5370| 5400102 | Operation not allowed. Return by promise. | 5371| 5400105 | Service died. Return by promise. | 5372 5373**示例：** 5374 5375```ts 5376import { BusinessError } from '@kit.BasicServicesKit'; 5377 5378avTranscoder.release().then(() => { 5379 console.info('release AVTranscoder success'); 5380}).catch((err: BusinessError) => { 5381 console.error('release AVTranscoder failed and catch error is ' + err.message); 5382}); 5383``` 5384 5385### on('progressUpdate')<sup>12+</sup> 5386 5387on(type: 'progressUpdate', callback: Callback\<number>): void 5388 5389注册转码进度更新事件，并通过注册的回调方法通知开发者。开发者只能注册一个进度更新事件的回调方法，当开发者重复注册时，以最后一次注册的回调接口为准。 5390 5391**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5392 5393**参数：** 5394 5395| 参数名 | 类型 | 必填 | 说明 | 5396| -------- | -------- | ---- | ------------------------------------------------------------ | 5397| type | string | 是 | 进度更新事件回调类型，支持的事件：'progressUpdate'，在转码过程中系统会自动触发此事件。 | 5398| callback | [Callback\<number>](../apis-basic-services-kit/js-apis-base.md#callback) | 是 | 进度更新事件回调方法，progress: number，表示当前转码进度。 | 5399 5400**示例：** 5401 5402```ts 5403avTranscoder.on('progressUpdate', (progress: number) => { 5404 console.info('avTranscoder progressUpdate = ' + progress); 5405}); 5406``` 5407 5408### off('progressUpdate')<sup>12+</sup> 5409 5410off(type:'progressUpdate', callback?: Callback\<number>): void 5411 5412取消注册转码进度更新事件。 5413 5414**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5415 5416**参数：** 5417 5418| 参数名 | 类型 | 必填 | 说明 | 5419| ------ | ------ | ---- | ------------------------------------------------------------ | 5420| type | string | 是 | 进度更新事件回调类型，支持的事件：'progressUpdate'。 | 5421| callback | [Callback\<number>](../apis-basic-services-kit/js-apis-base.md#callback) | 否 | 已注册的进度更新事件回调。由于当前回调注册时，仅会保留最后一次注册的回调，建议此参数缺省。 | 5422 5423**示例：** 5424 5425```ts 5426avTranscoder.off('progressUpdate'); 5427``` 5428 5429### on('error')<sup>12+</sup> 5430 5431on(type: 'error', callback: ErrorCallback): void 5432 5433注册AVtranscoder的错误事件，该事件仅用于错误提示。如果AVTranscoder上报error事件，开发者需要通过[release()](#release12)退出转码操作。 5434 5435开发者只能订阅一个错误事件的回调方法，当开发者重复订阅时，以最后一次订阅的回调接口为准。 5436 5437**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5438 5439**参数：** 5440 5441| 参数名 | 类型 | 必填 | 说明 | 5442| -------- | ------------- | ---- | ------------------------------------------------------------ | 5443| type | string | 是 | 转码错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 5444| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 转码错误事件回调方法。 | 5445 5446**错误码：** 5447 5448以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5449 5450| 错误码ID | 错误信息 | 5451| -------- | ------------------------------------------ | 5452| 401 | The parameter check failed. | 5453| 801 | Capability not supported. | 5454| 5400101 | No memory. | 5455| 5400102 | Operation not allowed. | 5456| 5400103 | I/O error. | 5457| 5400104 | Time out. | 5458| 5400105 | Service died. | 5459| 5400106 | Unsupported format. | 5460 5461**示例：** 5462 5463```ts 5464import { BusinessError } from '@kit.BasicServicesKit'; 5465 5466avTranscoder.on('error', (err: BusinessError) => { 5467 console.info('case avTranscoder.on(error) called, errMessage is ' + err.message); 5468}); 5469``` 5470 5471### off('error')<sup>12+</sup> 5472 5473off(type:'error', callback?: ErrorCallback): void 5474 5475取消注册转码错误事件，取消后不再接收到AVTranscoder的错误事件。 5476 5477**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5478 5479**参数：** 5480 5481| 参数名 | 类型 | 必填 | 说明 | 5482| ------ | ------ | ---- | ------------------------------------------------------------ | 5483| type | string | 是 | 转码错误事件回调类型'error'。 <br>- 'error'：转码过程中发生错误，触发该事件。 | 5484| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 错误事件回调方法。 | 5485 5486**示例：** 5487 5488```ts 5489avTranscoder.off('error'); 5490``` 5491 5492### on('complete')<sup>12+</sup> 5493 5494on(type: 'complete', callback: Callback\<void>): void 5495 5496注册转码完成事件，并通过注册的回调方法通知开发者。开发者只能注册一个进度更新事件的回调方法，当开发者重复注册时，以最后一次注册的回调接口为准。 5497 5498当AVTranscoder上报complete事件时，当前转码操作已完成，开发者需要通过[release()](#release12)退出转码操作。 5499 5500**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5501 5502**参数：** 5503 5504| 参数名 | 类型 | 必填 | 说明 | 5505| -------- | -------- | ---- | ------------------------------------------------------------ | 5506| type | string | 是 | 完成事件回调类型，支持的事件：'complete'，在转码过程中系统会自动触发此事件。 | 5507| callback | [Callback\<void>](../apis-basic-services-kit/js-apis-base.md#callback) | 是 | 完成事件回调方法。 | 5508 5509**示例：** 5510 5511```ts 5512avTranscoder.on('complete', async () => { 5513 console.info('avTranscoder complete'); 5514 // 开发者须在此监听转码完成事件 5515 // 须等待avTranscoder.release()之后，再对转码后的文件进行转发、上传、转存等处理 5516 await avTranscoder.release(); 5517 avTranscoder = undefined; 5518}); 5519``` 5520 5521### off('complete')<sup>12+</sup> 5522 5523off(type:'complete', callback?: Callback\<void>): void 5524 5525取消注册转码完成事件。 5526 5527**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5528 5529**参数：** 5530 5531| 参数名 | 类型 | 必填 | 说明 | 5532| ------ | ------ | ---- | ------------------------------------------------------------ | 5533| type | string | 是 | 转码完成事件回调类型，支持的事件：'complete'。 | 5534| callback | [Callback\<void>](../apis-basic-services-kit/js-apis-base.md#callback) | 否 | 完成事件回调方法。 | 5535 5536**示例：** 5537 5538```ts 5539avTranscoder.off('complete'); 5540``` 5541 5542## AVTranscoderConfig<sup>12+</sup> 5543 5544表示视频转码的参数设置。 5545 5546**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5547 5548| 名称 | 类型 | 只读 | 可选 | 说明 | 5549| --------------- | ---------------------------------------- |---- | ---- | ------------------------------------------------------------ | 5550| audioBitrate | number | 否 | 是 | 输出音频的码率，单位为比特率（bps），支持范围[1-500000]。默认设置为48Kbps。| 5551| audioCodec | [CodecMimeType](#codecmimetype8) | 否 | 是 | 输出音频的编码格式，当前仅支持AAC。默认设置为AAC。 | 5552| fileFormat | [ContainerFormatType](#containerformattype8) | 否 | 否 | 输出视频文件的封装格式，当前视频文件仅支持MP4。| 5553| videoBitrate | number | 否 | 是 | 输出视频的码率，单位为比特率（bps）。默认码率按输出视频的分辨率设置，[240p，480P]默认码率值为1Mbps，(480P,720P]默认码率值为2Mbps，(720P,1080P]默认码率值为4Mbps，1080P及以上默认值为8Mbps。| 5554| videoCodec | [CodecMimeType](#codecmimetype8) | 否 | 是 | 输出视频的编码格式，当前仅支持AVC和HEVC。若源视频编码格式为HEVC，则默认设置为HEVC，否则默认设置为AVC。| 5555| videoFrameWidth | number | 否 | 是 | 输出视频帧的宽，单位为像素（px），支持范围[240-3840]。默认设置为源视频帧的宽。| 5556| videoFrameHeight | number | 否 | 是 | 输出视频帧的高，单位为像素（px），支持范围[240-2160]。默认设置为源视频帧的高。| 5557 5558 5559 5560## AVMetadataExtractor<sup>11+</sup> 5561 5562元数据获取类，用于从媒体资源中获取元数据。在调用AVMetadataExtractor的方法前，需要先通过[createAVMetadataExtractor()](#mediacreateavmetadataextractor11)构建一个AVMetadataExtractor实例。 5563 5564获取音频或视频元数据的demo可参考：[获取音视频元数据开发指导](../../media/media/avmetadataextractor.md)。 5565 5566### 属性 5567 5568**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5569 5570| 名称 | 类型 | 可读 | 可写 | 说明 | 5571| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 5572| fdSrc<sup>11+</sup> | [AVFileDescriptor](#avfiledescriptor9) | 是 | 是 | 媒体文件描述，通过该属性设置数据源。在获取元数据之前，必须设置数据源属性，只能设置fdSrc和dataSrc的其中一个。<br/> **使用示例**：<br/>假设一个连续存储的媒体文件，地址偏移:0，字节长度:100。其文件描述为 AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVMetadataExtractor 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致音视频元数据获取异常。 | 5573| dataSrc<sup>11+</sup> | [AVDataSrcDescriptor](#avdatasrcdescriptor10) | 是 | 是 | 流式媒体资源描述，通过该属性设置数据源。在获取元数据之前，必须设置数据源属性，只能设置fdSrc和dataSrc的其中一个。<br/> 当应用从远端获取音视频媒体文件，在应用未下载完整音视频资源时，可以设置dataSrc提前获取该资源的元数据。| 5574 5575### fetchMetadata<sup>11+</sup> 5576 5577fetchMetadata(callback: AsyncCallback\<AVMetadata>): void 5578 5579异步方式获取媒体元数据。通过注册回调函数获取返回值。 5580 5581**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5582 5583**参数：** 5584 5585| 参数名 | 类型 | 必填 | 说明 | 5586| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5587| callback | AsyncCallback\<[AVMetadata](#avmetadata11)> | 是 | 回调函数。异步返回音视频元数据对象（AVMetadata）。| 5588 5589**错误码：** 5590 5591以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5592 5593| 错误码ID | 错误信息 | 5594| -------- | ------------------------------------------ | 5595| 5400102 | Operation not allowed. Returned by callback. | 5596| 5400106 | Unsupported format. Returned by callback. | 5597 5598**示例：** 5599 5600```ts 5601import { BusinessError } from '@kit.BasicServicesKit'; 5602 5603avMetadataExtractor.fetchMetadata((error: BusinessError, metadata: media.AVMetadata) => { 5604 if (error) { 5605 console.error(`Failed to fetch Metadata, err = ${JSON.stringify(error)}`); 5606 return; 5607 } 5608 console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`); 5609}); 5610``` 5611 5612### fetchMetadata<sup>11+</sup> 5613 5614fetchMetadata(): Promise\<AVMetadata> 5615 5616异步方式获取媒体元数据。通过Promise获取返回值。 5617 5618**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5619 5620**返回值：** 5621 5622| 类型 | 说明 | 5623| -------------- | ---------------------------------------- | 5624| Promise\<[AVMetadata](#avmetadata11)> | Promise对象。异步返回音视频元数据对象（AVMetadata）。 | 5625 5626**错误码：** 5627 5628以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5629 5630| 错误码ID | 错误信息 | 5631| -------- | ----------------------------------------- | 5632| 5400102 | Operation not allowed. Returned by promise. | 5633| 5400106 | Unsupported format. Returned by promise. | 5634 5635**示例：** 5636 5637```ts 5638import { BusinessError } from '@kit.BasicServicesKit'; 5639 5640avMetadataExtractor.fetchMetadata().then((metadata: media.AVMetadata) => { 5641 console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`); 5642}).catch((error: BusinessError) => { 5643 console.error(`Failed to fetch Metadata, error message:${error.message}`); 5644}); 5645``` 5646 5647### fetchAlbumCover<sup>11+</sup> 5648 5649fetchAlbumCover(callback: AsyncCallback\<image.PixelMap>): void 5650 5651异步方式获取音频专辑封面。通过注册回调函数获取返回值。 5652 5653**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5654 5655**参数：** 5656 5657| 参数名 | 类型 | 必填 | 说明 | 5658| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5659| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | 是 | 回调函数。异步返回专辑封面。 | 5660 5661**错误码：** 5662 5663以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5664 5665| 错误码ID | 错误信息 | 5666| -------- | ------------------------------------------ | 5667| 5400102 | Operation not allowed. Return by callback. | 5668| 5400106 | Unsupported format. Returned by callback. | 5669 5670**示例：** 5671 5672```ts 5673import { BusinessError } from '@kit.BasicServicesKit'; 5674import { image } from '@kit.ImageKit'; 5675 5676let pixel_map : image.PixelMap | undefined = undefined; 5677 5678avMetadataExtractor.fetchAlbumCover((error: BusinessError, pixelMap: image.PixelMap) => { 5679 if (error) { 5680 console.error(`Failed to fetch AlbumCover, error = ${JSON.stringify(error)}`); 5681 return; 5682 } 5683 pixel_map = pixelMap; 5684}); 5685``` 5686 5687### fetchAlbumCover<sup>11+</sup> 5688 5689fetchAlbumCover(): Promise\<image.PixelMap> 5690 5691异步方式获取专辑封面。通过Promise获取返回值。 5692 5693**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5694 5695**返回值：** 5696 5697| 类型 | 说明 | 5698| -------------- | ---------------------------------------- | 5699| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象。异步返回专辑封面。 | 5700 5701**错误码：** 5702 5703以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5704 5705| 错误码ID | 错误信息 | 5706| -------- | ----------------------------------------- | 5707| 5400102 | Operation not allowed. Returned by promise. | 5708| 5400106 | Unsupported format. Returned by promise. | 5709 5710**示例：** 5711 5712```ts 5713import { BusinessError } from '@kit.BasicServicesKit'; 5714import { image } from '@kit.ImageKit'; 5715 5716let pixel_map : image.PixelMap | undefined = undefined; 5717 5718avMetadataExtractor.fetchAlbumCover().then((pixelMap: image.PixelMap) => { 5719 pixel_map = pixelMap; 5720}).catch((error: BusinessError) => { 5721 console.error(`Failed to fetch AlbumCover, error message:${error.message}`); 5722}); 5723``` 5724 5725### release<sup>11+</sup> 5726 5727release(callback: AsyncCallback\<void>): void 5728 5729异步方式释放资源。通过注册回调函数获取返回值。 5730 5731**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5732 5733**参数：** 5734 5735| 参数名 | 类型 | 必填 | 说明 | 5736| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5737| callback | AsyncCallback\<void> | 是 |回调函数。当释放资源成功，err为undefined，否则为错误对象。 | 5738 5739**错误码：** 5740 5741以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5742 5743| 错误码ID | 错误信息 | 5744| -------- | ------------------------------------------ | 5745| 5400102 | Operation not allowed. Returned by callback. | 5746 5747**示例：** 5748 5749```ts 5750import { BusinessError } from '@kit.BasicServicesKit'; 5751 5752avMetadataExtractor.release((error: BusinessError) => { 5753 if (error) { 5754 console.error(`Failed to release, err = ${JSON.stringify(error)}`); 5755 return; 5756 } 5757 console.info(`Succeeded in releasing.`); 5758}); 5759``` 5760 5761### release<sup>11+</sup> 5762 5763release(): Promise\<void> 5764 5765异步方式释放资源。通过Promise获取返回值。 5766 5767**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5768 5769**返回值：** 5770 5771| 类型 | 说明 | 5772| -------------- | ---------------------------------------- | 5773| Promise\<void> | 异步方式释放资源release方法的Promise返回值。 | 5774 5775**错误码：** 5776 5777以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5778 5779| 错误码ID | 错误信息 | 5780| -------- | ----------------------------------------- | 5781| 5400102 | Operation not allowed. Returned by promise. | 5782 5783**示例：** 5784 5785```ts 5786import { BusinessError } from '@kit.BasicServicesKit'; 5787 5788avMetadataExtractor.release().then(() => { 5789 console.info(`Succeeded in releasing.`); 5790}).catch((error: BusinessError) => { 5791 console.error(`Failed to release, error message:${error.message}`); 5792}); 5793``` 5794 5795## AVMetadata<sup>11+</sup> 5796 5797音视频元数据，包含各个元数据字段。在[AVRecorderConfig](#avrecorderconfig9)中使用时未声明为当前版本只读的参数可以作为使用[AVRecorder](#avrecorder9)录制时的入参。 5798 5799**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5800 5801| 名称 | 类型 | 必填 | 说明 | 5802| ------ | ------ | ---- | ------------------------------------------------------------ | 5803| album | string | 否 | 专辑的标题。当前版本为只读参数。 | 5804| albumArtist | string | 否 | 专辑的艺术家。当前版本为只读参数。 | 5805| artist | string | 否 | 媒体资源的艺术家。当前版本为只读参数。 | 5806| author | string | 否 | 媒体资源的作者。当前版本为只读参数。 | 5807| dateTime | string | 否 | 媒体资源的创建时间。当前版本为只读参数。 | 5808| dateTimeFormat | string | 否 | 媒体资源的创建时间，按YYYY-MM-DD HH:mm:ss格式输出。当前版本为只读参数。 | 5809| composer | string | 否 | 媒体资源的作曲家。当前版本为只读参数。 | 5810| duration | string | 否 | 媒体资源的时长。当前版本为只读参数。 | 5811| genre | string | 否 | 媒体资源的类型或体裁。| 5812| hasAudio | string | 否 | 媒体资源是否包含音频。当前版本为只读参数。 | 5813| hasVideo | string | 否 | 媒体资源是否包含视频。当前版本为只读参数。 | 5814| mimeType | string | 否 | 媒体资源的mime类型。当前版本为只读参数。 | 5815| trackCount | string | 否 | 媒体资源的轨道数量。当前版本为只读参数。 | 5816| sampleRate | string | 否 | 音频的采样率，单位为赫兹（Hz）。当前版本为只读参数。 | 5817| title | string | 否 | 媒体资源的标题。当前版本为只读参数。当前版本为只读参数。 | 5818| videoHeight | string | 否 | 视频的高度，单位为像素。当前版本为只读参数。 | 5819| videoWidth | string | 否 | 视频的宽度，单位为像素。当前版本为只读参数。 | 5820| videoOrientation | string | 否 | 视频的旋转方向，单位为度（°）。| 5821| hdrType<sup>12+</sup> | [HdrType](#hdrtype12) | 否 | 媒体资源的HDR类型。当前版本为只读参数。 | 5822| location<sup>12+</sup> | [Location](#location) | 否 | 视频的地理位置信息。 | 5823| customInfo<sup>12+</sup> | Record<string, string> | 否 | 从moov.meta.list 获取的自定义参数键值映射。| 5824 5825## HdrType<sup>12+</sup> 5826 5827表示视频HDR类型的枚举。 5828 5829**系统能力：** SystemCapability.Multimedia.Media.Core 5830 5831| 名称 | 值 | 说明 | 5832| ------------------------- | ---- | ---------------------- | 5833| AV_HDR_TYPE_NONE | 0 | 表示无HDR类型。 | 5834| AV_HDR_TYPE_VIVID | 1 | 表示为HDR VIVID类型。 | 5835 5836## media.createAudioPlayer<sup>(deprecated)</sup> 5837 5838createAudioPlayer(): AudioPlayer 5839 5840同步方式创建音频播放实例。 5841 5842> **说明：** 5843> 从API version 6开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9)替代。 5844 5845**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5846 5847**返回值：** 5848 5849| 类型 | 说明 | 5850| --------------------------- | ------------------------------------------------------------ | 5851| [AudioPlayer](#audioplayerdeprecated) | 返回AudioPlayer类实例，失败时返回null。可用于音频播放、暂停、停止等操作。 | 5852 5853**示例：** 5854 5855```ts 5856let audioPlayer: media.AudioPlayer = media.createAudioPlayer(); 5857``` 5858 5859## media.createVideoPlayer<sup>(deprecated)</sup> 5860 5861createVideoPlayer(callback: AsyncCallback\<VideoPlayer>): void 5862 5863异步方式创建视频播放实例，通过注册回调函数获取返回值。 5864 5865> **说明：** 5866> 从API version 8开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9)替代。 5867 5868**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5869 5870**参数：** 5871 5872| 参数名 | 类型 | 必填 | 说明 | 5873| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 5874| callback | AsyncCallback<[VideoPlayer](#videoplayerdeprecated)> | 是 | 回调函数。创建VideoPlayer实例成功时，err为undefined，data为获取到的VideoPlayer实例，否则为错误对象。 | 5875 5876**示例：** 5877 5878```ts 5879import { BusinessError } from '@kit.BasicServicesKit'; 5880 5881let videoPlayer: media.VideoPlayer; 5882media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 5883 if (video != null) { 5884 videoPlayer = video; 5885 console.info('Succeeded in creating VideoPlayer'); 5886 } else { 5887 console.error(`Failed to create VideoPlayer, error:${error}`); 5888 } 5889}); 5890``` 5891 5892## media.createVideoPlayer<sup>(deprecated)</sup> 5893 5894createVideoPlayer(): Promise\<VideoPlayer> 5895 5896异步方式创建视频播放实例，通过Promise获取返回值。 5897 5898> **说明：** 5899> 从API version 8开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9-1)替代。 5900 5901**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5902 5903**返回值：** 5904 5905| 类型 | 说明 | 5906| ------------------------------------ | ------------------------------------------------------------ | 5907| Promise<[VideoPlayer](#videoplayerdeprecated)> | Promise对象。异步返回VideoPlayer实例，失败时返回null。可用于管理和播放视频媒体。 | 5908 5909**示例：** 5910 5911```ts 5912import { BusinessError } from '@kit.BasicServicesKit'; 5913 5914let videoPlayer: media.VideoPlayer; 5915media.createVideoPlayer().then((video: media.VideoPlayer) => { 5916 if (video != null) { 5917 videoPlayer = video; 5918 console.info('Succeeded in creating VideoPlayer'); 5919 } else { 5920 console.error('Failed to create VideoPlayer'); 5921 } 5922}).catch((error: BusinessError) => { 5923 console.error(`Failed to create VideoPlayer, error:${error}`); 5924}); 5925``` 5926 5927## media.createAudioRecorder<sup>(deprecated)</sup> 5928 5929createAudioRecorder(): AudioRecorder 5930 5931创建音频录制的实例来控制音频的录制。 5932一台设备只允许创建一个录制实例。 5933 5934> **说明：** 5935> 从API version 6开始支持，从API version 9开始废弃，建议使用[createAVRecorder](#mediacreateavrecorder9)替代。 5936 5937**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 5938 5939**返回值:** 5940 5941| 类型 | 说明 | 5942| ------------------------------- | ------------------------------------------------------------ | 5943| [AudioRecorder](#audiorecorderdeprecated) | 返回AudioRecorder类实例，失败时返回null。可用于录制音频媒体。 | 5944 5945**示例：** 5946 5947```ts 5948let audioRecorder: media.AudioRecorder = media.createAudioRecorder(); 5949``` 5950 5951## MediaErrorCode<sup>(deprecated)</sup> 5952 5953媒体服务错误类型枚举。 5954 5955> **说明：** 5956> 从API version 8开始支持，从API version 11开始废弃，建议使用[媒体错误码](#averrorcode9)替代。 5957 5958**系统能力：** SystemCapability.Multimedia.Media.Core 5959 5960| 名称 | 值 | 说明 | 5961| -------------------------- | ---- | -------------------------------------- | 5962| MSERR_OK | 0 | 表示操作成功。 | 5963| MSERR_NO_MEMORY | 1 | 表示申请内存失败，系统可能无可用内存。 | 5964| MSERR_OPERATION_NOT_PERMIT | 2 | 表示无权限执行此操作。 | 5965| MSERR_INVALID_VAL | 3 | 表示传入入参无效。 | 5966| MSERR_IO | 4 | 表示发生IO错误。 | 5967| MSERR_TIMEOUT | 5 | 表示操作超时。 | 5968| MSERR_UNKNOWN | 6 | 表示未知错误。 | 5969| MSERR_SERVICE_DIED | 7 | 表示服务端失效。 | 5970| MSERR_INVALID_STATE | 8 | 表示在当前状态下，不允许执行此操作。 | 5971| MSERR_UNSUPPORTED | 9 | 表示在当前版本下，不支持此操作。 | 5972 5973## AudioPlayer<sup>(deprecated)</sup> 5974 5975> **说明：** 5976> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer](#avplayer9)替代。 5977 5978音频播放管理类，用于管理和播放音频媒体。在调用AudioPlayer的方法前，需要先通过[createAudioPlayer()](#mediacreateaudioplayerdeprecated)构建一个AudioPlayer实例。 5979 5980### 属性<sup>(deprecated)</sup> 5981 5982**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5983 5984| 名称 | 类型 | 只读 | 可选 | 说明 | 5985| ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 5986| src | string | 否 | 否 | 音频媒体URI，支持当前主流的音频格式(m4a、aac、mp3、ogg、wav、amr)。<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/>**需要权限：** ohos.permission.READ_MEDIA 或 ohos.permission.INTERNET。 | 5987| fdSrc<sup>9+</sup> | [AVFileDescriptor](#avfiledescriptor9) | 否 | 否 | 音频媒体文件描述，使用场景：应用中的音频资源被连续存储在同一个文件中。<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/> | 5988| loop | boolean | 否 | 否 | 音频循环播放属性，设置为'true'表示循环播放。 | 5989| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9) | 是 | 是 | 音频焦点模型。 | 5990| currentTime | number | 是 | 否 | 音频的当前播放位置，单位为毫秒（ms）。 | 5991| duration | number | 是 | 否 | 音频时长，单位为毫秒（ms）。 | 5992| state | [AudioState](#audiostatedeprecated) | 是 | 否 | 可以查询音频播放的状态，该状态不可作为调用play/pause/stop等状态切换的触发条件。 | 5993 5994### play<sup>(deprecated)</sup> 5995 5996play(): void 5997 5998开始播放音频资源，需在'dataLoad'事件成功触发后，才能调用。 5999 6000> **说明：** 6001> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9)替代。 6002 6003**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6004 6005**示例：** 6006 6007```ts 6008audioPlayer.on('play', () => { //设置'play'事件回调。 6009 console.info('audio play called'); 6010}); 6011audioPlayer.play(); 6012``` 6013 6014### pause<sup>(deprecated)</sup> 6015 6016pause(): void 6017 6018暂停播放音频资源。 6019 6020> **说明：** 6021> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9)替代。 6022 6023**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6024 6025**示例：** 6026 6027```ts 6028audioPlayer.on('pause', () => { //设置'pause'事件回调。 6029 console.info('audio pause called'); 6030}); 6031audioPlayer.pause(); 6032``` 6033 6034### stop<sup>(deprecated)</sup> 6035 6036stop(): void 6037 6038停止播放音频资源。 6039 6040> **说明：** 6041> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9)替代。 6042 6043**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6044 6045**示例：** 6046 6047```ts 6048audioPlayer.on('stop', () => { //设置'stop'事件回调。 6049 console.info('audio stop called'); 6050}); 6051audioPlayer.stop(); 6052``` 6053 6054### reset<sup>(deprecated)</sup> 6055 6056reset(): void 6057 6058重置播放音频资源。 6059 6060> **说明：** 6061> 从API version 7开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9)替代。 6062 6063**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6064 6065**示例：** 6066 6067```ts 6068audioPlayer.on('reset', () => { //设置'reset'事件回调。 6069 console.info('audio reset called'); 6070}); 6071audioPlayer.reset(); 6072``` 6073 6074### seek<sup>(deprecated)</sup> 6075 6076seek(timeMs: number): void 6077 6078跳转到指定播放位置。 6079 6080> **说明：** 6081> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6082 6083**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6084 6085**参数：** 6086 6087| 参数名 | 类型 | 必填 | 说明 | 6088| ------ | ------ | ---- | ----------------------------------------------------------- | 6089| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围[0, duration]。 | 6090 6091**示例：** 6092 6093```ts 6094audioPlayer.on('timeUpdate', (seekDoneTime: number) => { //设置'timeUpdate'事件回调。 6095 if (seekDoneTime == null) { 6096 console.error('Failed to seek'); 6097 return; 6098 } 6099 console.info('Succeeded in seek. seekDoneTime: ' + seekDoneTime); 6100}); 6101audioPlayer.seek(30000); //seek到30000ms的位置。 6102``` 6103 6104### setVolume<sup>(deprecated)</sup> 6105 6106setVolume(vol: number): void 6107 6108设置音量。 6109 6110> **说明：** 6111> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 6112 6113**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6114 6115**参数：** 6116 6117| 参数名 | 类型 | 必填 | 说明 | 6118| ------ | ------ | ---- | ------------------------------------------------------------ | 6119| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 6120 6121**示例：** 6122 6123```ts 6124audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调。 6125 console.info('audio volumeChange called'); 6126}); 6127audioPlayer.setVolume(1); //设置音量到100%。 6128``` 6129 6130### release<sup>(deprecated)</sup> 6131 6132release(): void 6133 6134释放音频资源。 6135 6136> **说明：** 6137> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9)替代。 6138 6139**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6140 6141**示例：** 6142 6143```ts 6144audioPlayer.release(); 6145audioPlayer = undefined; 6146``` 6147 6148### getTrackDescription<sup>(deprecated)</sup> 6149 6150getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 6151 6152获取音频轨道信息。需在'dataLoad'事件成功触发后，才能调用。通过回调函数获取返回值。 6153 6154> **说明：** 6155> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9)替代。 6156 6157**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6158 6159**参数：** 6160 6161| 参数名 | 类型 | 必填 | 说明 | 6162| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 6163| callback | AsyncCallback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 回调函数。获取音频轨道信息成功时，err为undefined，data为获取到的MediaDescription数组，否则为错误对象。 | 6164 6165**示例：** 6166 6167```ts 6168import { BusinessError } from '@kit.BasicServicesKit'; 6169 6170audioPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 6171 if (arrList != null) { 6172 console.info('Succeeded in getting TrackDescription'); 6173 } else { 6174 console.error(`Failed to get TrackDescription, error:${error}`); 6175 } 6176}); 6177``` 6178 6179### getTrackDescription<sup>(deprecated)</sup> 6180 6181getTrackDescription(): Promise\<Array\<MediaDescription>> 6182 6183获取音频轨道信息。需在'dataLoad'事件成功触发后，才能调用。通过Promise获取返回值。 6184 6185> **说明：** 6186> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9-1)替代。 6187 6188**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6189 6190**返回值：** 6191 6192| 类型 | 说明 | 6193| ------------------------------------------------------ | ----------------------------------------------- | 6194| Promise<Array<[MediaDescription](#mediadescription8)>> | 音频轨道信息MediaDescription数组Promise返回值。 | 6195 6196**示例：** 6197 6198```ts 6199import { BusinessError } from '@kit.BasicServicesKit'; 6200 6201audioPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 6202 console.info('Succeeded in getting TrackDescription'); 6203}).catch((error: BusinessError) => { 6204 console.error(`Failed to get TrackDescription, error:${error}`); 6205}); 6206``` 6207 6208### on('bufferingUpdate')<sup>(deprecated)</sup> 6209 6210on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void 6211 6212开始订阅音频缓存更新事件。仅网络播放支持该订阅事件。 6213 6214> **说明：** 6215> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('bufferingUpdate')](#onbufferingupdate9)替代。 6216 6217**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6218 6219**参数：** 6220 6221| 参数名 | 类型 | 必填 | 说明 | 6222| -------- | -------- | ---- | ------------------------------------------------------------ | 6223| type | string | 是 | 音频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 6224| callback | function | 是 | 音频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)value值固定为0。 | 6225 6226**示例：** 6227 6228```ts 6229audioPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 6230 console.info('audio bufferingInfo type: ' + infoType); 6231 console.info('audio bufferingInfo value: ' + value); 6232}); 6233``` 6234 6235### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')<sup>(deprecated)</sup> 6236 6237on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void): void 6238 6239开始订阅音频播放事件。 6240 6241> **说明：** 6242> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('stateChange')](#onstatechange9)替代。 6243 6244**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6245 6246**参数：** 6247 6248| 参数名 | 类型 | 必填 | 说明 | 6249| -------- | ---------- | ---- | ------------------------------------------------------------ | 6250| type | string | 是 | 播放事件回调类型，支持的事件包括：'play' \| 'pause' \| 'stop' \| 'reset' \| 'dataLoad' \| 'finish' \| 'volumeChange'。<br>- 'play'：完成[play()](#playdeprecated)调用，音频开始播放，触发该事件。<br>- 'pause'：完成[pause()](#pausedeprecated)调用，音频暂停播放，触发该事件。<br>- 'stop'：完成[stop()](#stopdeprecated)调用，音频停止播放，触发该事件。<br>- 'reset'：完成[reset()](#resetdeprecated)调用，播放器重置，触发该事件。<br>- 'dataLoad'：完成音频数据加载后触发该事件，即src属性设置完成后触发该事件。<br>- 'finish'：完成音频播放后触发该事件。<br>- 'volumeChange'：完成[setVolume()](#setvolumedeprecated)调用，播放音量改变后触发该事件。 | 6251| callback | () => void | 是 | 播放事件回调方法。 | 6252 6253**示例：** 6254 6255```ts 6256import { fileIo as fs } from '@kit.CoreFileKit'; 6257import { BusinessError } from '@kit.BasicServicesKit'; 6258 6259let audioPlayer: media.AudioPlayer = media.createAudioPlayer(); //创建一个音频播放实例。 6260audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调，src属性设置成功后，触发此回调。 6261 console.info('audio set source called'); 6262 audioPlayer.play(); //开始播放，并触发'play'事件回调。 6263}); 6264audioPlayer.on('play', () => { //设置'play'事件回调。 6265 console.info('audio play called'); 6266 audioPlayer.seek(30000); //调用seek方法，并触发'timeUpdate'事件回调。 6267}); 6268audioPlayer.on('pause', () => { //设置'pause'事件回调。 6269 console.info('audio pause called'); 6270 audioPlayer.stop(); //停止播放，并触发'stop'事件回调。 6271}); 6272audioPlayer.on('reset', () => { //设置'reset'事件回调。 6273 console.info('audio reset called'); 6274 audioPlayer.release(); //释放播放实例资源。 6275 audioPlayer = undefined; 6276}); 6277audioPlayer.on('timeUpdate', (seekDoneTime: number) => { //设置'timeUpdate'事件回调。 6278 if (seekDoneTime == null) { 6279 console.error('Failed to seek'); 6280 return; 6281 } 6282 console.info('Succeeded in seek, and seek time is ' + seekDoneTime); 6283 audioPlayer.setVolume(0.5); //设置音量为50%，并触发'volumeChange'事件回调。 6284}); 6285audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调。 6286 console.info('audio volumeChange called'); 6287 audioPlayer.pause(); //暂停播放，并触发'pause'事件回调。 6288}); 6289audioPlayer.on('finish', () => { //设置'finish'事件回调。 6290 console.info('audio play finish'); 6291 audioPlayer.stop(); //停止播放，并触发'stop'事件回调。 6292}); 6293audioPlayer.on('error', (error: BusinessError) => { //设置'error'事件回调。 6294 console.error(`audio error called, error: ${error}`); 6295}); 6296 6297// 用户选择音频设置fd(本地播放)。 6298let fdPath = 'fd://'; 6299// path路径的码流可通过"hdc file send D:\xxx\01.mp3 /data/accounts/account_0/appdata" 命令，将其推送到设备上。 6300let path = '/data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3'; 6301fs.open(path).then((file) => { 6302 fdPath = fdPath + '' + file.fd; 6303 console.info('Succeeded in opening fd, fd is' + fdPath); 6304 audioPlayer.src = fdPath; //设置src属性，并触发'dataLoad'事件回调。 6305}, (err: BusinessError) => { 6306 console.error('Failed to open fd, err is' + err); 6307}).catch((err: BusinessError) => { 6308 console.error('Failed to open fd, err is' + err); 6309}); 6310``` 6311 6312### on('timeUpdate')<sup>(deprecated)</sup> 6313 6314on(type: 'timeUpdate', callback: Callback\<number>): void 6315 6316开始订阅音频播放时间更新事件。处于播放状态时，每隔1s上报一次该事件。 6317 6318> **说明：** 6319> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('timeUpdate')](#ontimeupdate9)替代。 6320 6321**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6322 6323**参数：** 6324 6325| 参数名 | 类型 | 必填 | 说明 | 6326| -------- | ----------------- | ---- | ------------------------------------------------------------ | 6327| type | string | 是 | 播放事件回调类型，支持的事件包括：'timeUpdate'。<br>- 'timeUpdate'：音频播放时间戳更新，开始播放后自动触发该事件。 | 6328| callback | Callback\<number> | 是 | 播放事件回调方法。回调方法入参为更新后的时间戳。 | 6329 6330**示例：** 6331 6332```ts 6333audioPlayer.on('timeUpdate', (newTime: number) => { //设置'timeUpdate'事件回调。 6334 if (newTime == null) { 6335 console.error('Failed to do timeUpadate'); 6336 return; 6337 } 6338 console.info('Succeeded in doing timeUpadate. seekDoneTime: ' + newTime); 6339}); 6340audioPlayer.play(); //开始播放后，自动触发时间戳更新事件。 6341``` 6342 6343### on('audioInterrupt')<sup>(deprecated)</sup> 6344 6345on(type: 'audioInterrupt', callback: (info: audio.InterruptEvent) => void): void 6346 6347监听音频焦点变化事件，参考[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)。 6348 6349> **说明：** 6350> 从API version 9开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('audioInterrupt')](#onaudiointerrupt9)替代。 6351 6352**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6353 6354**参数：** 6355 6356| 参数名 | 类型 | 必填 | 说明 | 6357| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 6358| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 6359| callback | function | 是 | 音频焦点变化事件回调方法。 | 6360 6361**示例：** 6362 6363```ts 6364import { audio } from '@kit.AudioKit'; 6365 6366audioPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 6367 console.info('audioInterrupt called,and InterruptEvent info is:' + info); 6368}); 6369``` 6370 6371### on('error')<sup>(deprecated)</sup> 6372 6373on(type: 'error', callback: ErrorCallback): void 6374 6375开始订阅音频播放错误事件，当上报error错误事件后，用户需处理error事件，退出播放操作。 6376 6377> **说明：** 6378> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('error')](#onerror9)替代。 6379 6380**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6381 6382**参数：** 6383 6384| 参数名 | 类型 | 必填 | 说明 | 6385| -------- | ------------- | ---- | ------------------------------------------------------------ | 6386| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：音频播放中发生错误，触发该事件。 | 6387| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 播放错误事件回调方法。 | 6388 6389**示例：** 6390 6391```ts 6392import { BusinessError } from '@kit.BasicServicesKit'; 6393 6394audioPlayer.on('error', (error: BusinessError) => { //设置'error'事件回调。 6395 console.error(`audio error called, error: ${error}`); 6396}); 6397audioPlayer.setVolume(3); //设置volume为无效值，触发'error'事件。 6398``` 6399 6400## AudioState<sup>(deprecated)</sup> 6401 6402type AudioState = 'idle' | 'playing' | 'paused' | 'stopped' | 'error' 6403 6404音频播放的状态机。可通过state属性获取当前状态。 6405 6406> **说明：** 6407> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayerState](#avplayerstate9)替代。 6408 6409**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6410 6411| 类型 | 说明 | 6412| ------- | ---------------------------------------------- | 6413| 'idle' | 音频播放空闲，dataload/reset成功后处于此状态。 | 6414| 'playing' | 音频正在播放，play成功后处于此状态。 | 6415| 'paused' | 音频暂停播放，pause成功后处于此状态。 | 6416| 'stopped' | 音频播放停止，stop/播放结束后处于此状态。 | 6417| 'error' | 错误状态。 | 6418 6419## VideoPlayer<sup>(deprecated)</sup> 6420 6421> **说明：** 6422> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer](#avplayer9)替代。 6423 6424视频播放管理类，用于管理和播放视频媒体。在调用VideoPlayer的方法前，需要先通过[createVideoPlayer()](#mediacreatevideoplayerdeprecated)构建一个VideoPlayer实例。 6425 6426### 属性 6427 6428**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6429 6430| 名称 | 类型 | 只读 | 可选 | 说明 | 6431| ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 6432| url<sup>8+</sup> | string | 否 | 否 | 视频媒体URL，支持当前主流的视频格式(mp4、mpeg-ts、mkv)。<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>5. file类型: file\://xx<br/>**说明：**<br>从API version 11开始不支持webm。 | 6433| fdSrc<sup>9+</sup> | [AVFileDescriptor](#avfiledescriptor9) | 否 | 否 | 视频媒体文件描述，使用场景：应用中的视频资源被连续存储在同一个文件中。<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/> | 6434| loop<sup>8+</sup> | boolean | 否 | 否 | 视频循环播放属性，设置为'true'表示循环播放。 | 6435| videoScaleType<sup>9+</sup> | [VideoScaleType](#videoscaletype9) | 否 | 是 | 视频缩放模式。默认值为VIDEO_SCALE_TYPE_FIT。 | 6436| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9) | 否 | 是 | 音频焦点模型。 | 6437| currentTime<sup>8+</sup> | number | 是 | 否 | 视频的当前播放位置，单位为毫秒（ms）。 | 6438| duration<sup>8+</sup> | number | 是 | 否 | 视频时长，单位为毫秒（ms），返回-1表示直播模式。 | 6439| state<sup>8+</sup> | [VideoPlayState](#videoplaystatedeprecated) | 是 | 否 | 视频播放的状态。 | 6440| width<sup>8+</sup> | number | 是 | 否 | 视频宽，单位为像素（px）。 | 6441| height<sup>8+</sup> | number | 是 | 否 | 视频高，单位为像素（px）。 | 6442 6443### setDisplaySurface<sup>(deprecated)</sup> 6444 6445setDisplaySurface(surfaceId: string, callback: AsyncCallback\<void>): void 6446 6447设置SurfaceId。通过回调函数获取返回值。 6448 6449*注意：SetDisplaySurface需要在设置url和Prepare之间，无音频的视频流必须设置Surface否则Prepare失败。 6450 6451> **说明：** 6452> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.surfaceId](#属性)替代。 6453 6454**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6455 6456**参数：** 6457 6458| 参数名 | 类型 | 必填 | 说明 | 6459| --------- | -------------------- | ---- | ------------------------- | 6460| surfaceId | string | 是 | SurfaceId. | 6461| callback | AsyncCallback\<void> | 是 | 回调函数。当设置SurfaceId成功，err为undefined，否则为错误对象。 | 6462 6463**示例：** 6464 6465```ts 6466import { BusinessError } from '@kit.BasicServicesKit'; 6467 6468let surfaceId: string = ''; 6469videoPlayer.setDisplaySurface(surfaceId, (err: BusinessError) => { 6470 if (err) { 6471 console.error('Failed to set DisplaySurface!'); 6472 } else { 6473 console.info('Succeeded in setting DisplaySurface!'); 6474 } 6475}); 6476``` 6477 6478### setDisplaySurface<sup>(deprecated)</sup> 6479 6480setDisplaySurface(surfaceId: string): Promise\<void> 6481 6482设置SurfaceId。通过Promise获取返回值。 6483 6484*注意：SetDisplaySurface需要在设置url和Prepare之间，无音频的视频流必须设置Surface否则Prepare失败。 6485 6486> **说明：** 6487> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.surfaceId](#属性)替代。 6488 6489**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6490 6491**参数：** 6492 6493| 参数名 | 类型 | 必填 | 说明 | 6494| --------- | ------ | ---- | --------- | 6495| surfaceId | string | 是 | SurfaceId. | 6496 6497**返回值：** 6498 6499| 类型 | 说明 | 6500| -------------- | ------------------------------ | 6501| Promise\<void> | 设置SurfaceId的Promise返回值。 | 6502 6503**示例：** 6504 6505```ts 6506import { BusinessError } from '@kit.BasicServicesKit'; 6507 6508let surfaceId: string = ''; 6509videoPlayer.setDisplaySurface(surfaceId).then(() => { 6510 console.info('Succeeded in setting DisplaySurface'); 6511}).catch((error: BusinessError) => { 6512 console.error(`video catchCallback, error:${error}`); 6513}); 6514``` 6515 6516### prepare<sup>(deprecated)</sup> 6517 6518prepare(callback: AsyncCallback\<void>): void 6519 6520准备播放视频。通过回调函数获取返回值。 6521 6522> **说明：** 6523> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.prepare](#prepare9)替代。 6524 6525**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6526 6527**参数：** 6528 6529| 参数名 | 类型 | 必填 | 说明 | 6530| -------- | -------------------- | ---- | ------------------------ | 6531| callback | AsyncCallback\<void> | 是 | 回调函数。当准备播放视频成功，err为undefined，否则为错误对象。| 6532 6533**示例：** 6534 6535```ts 6536import { BusinessError } from '@kit.BasicServicesKit'; 6537 6538videoPlayer.prepare((err: BusinessError) => { 6539 if (err) { 6540 console.error('Failed to prepare!'); 6541 } else { 6542 console.info('Succeeded in preparing!'); 6543 } 6544}); 6545``` 6546 6547### prepare<sup>(deprecated)</sup> 6548 6549prepare(): Promise\<void> 6550 6551准备播放视频。通过Promise获取返回值。 6552 6553> **说明：** 6554> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.prepare](#prepare9-1)替代。 6555 6556**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6557 6558**返回值：** 6559 6560| 类型 | 说明 | 6561| -------------- | ----------------------------- | 6562| Promise\<void> | 准备播放视频的Promise返回值。 | 6563 6564**示例：** 6565 6566```ts 6567import { BusinessError } from '@kit.BasicServicesKit'; 6568 6569videoPlayer.prepare().then(() => { 6570 console.info('Succeeded in preparing'); 6571}).catch((error: BusinessError) => { 6572 console.error(`video catchCallback, error:${error}`); 6573}); 6574``` 6575 6576### play<sup>(deprecated)</sup> 6577 6578play(callback: AsyncCallback\<void>): void 6579 6580开始播放视频。通过回调函数获取返回值。 6581 6582> **说明：** 6583> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9)替代。 6584 6585**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6586 6587**参数：** 6588 6589| 参数名 | 类型 | 必填 | 说明 | 6590| -------- | -------------------- | ---- | ------------------------ | 6591| callback | AsyncCallback\<void> | 是 | 回调函数。当开始播放视频成功，err为undefined，否则为错误对象。 | 6592 6593**示例：** 6594 6595```ts 6596import { BusinessError } from '@kit.BasicServicesKit'; 6597 6598videoPlayer.play((err: BusinessError) => { 6599 if (err) { 6600 console.error('Failed to play!'); 6601 } else { 6602 console.info('Succeeded in playing!'); 6603 } 6604}); 6605``` 6606 6607### play<sup>(deprecated)</sup> 6608 6609play(): Promise\<void> 6610 6611开始播放视频。通过Promise获取返回值。 6612 6613> **说明：** 6614> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9-1)替代。 6615 6616**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6617 6618**返回值：** 6619 6620| 类型 | 说明 | 6621| -------------- | ----------------------------- | 6622| Promise\<void> | 开始播放视频的Promise返回值。 | 6623 6624**示例：** 6625 6626```ts 6627import { BusinessError } from '@kit.BasicServicesKit'; 6628 6629videoPlayer.play().then(() => { 6630 console.info('Succeeded in playing'); 6631}).catch((error: BusinessError) => { 6632 console.error(`video catchCallback, error:${error}`); 6633}); 6634``` 6635 6636### pause<sup>(deprecated)</sup> 6637 6638pause(callback: AsyncCallback\<void>): void 6639 6640通过回调方式暂停播放视频。通过回调函数获取返回值。 6641 6642> **说明：** 6643> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9)替代。 6644 6645**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6646 6647**参数：** 6648 6649| 参数名 | 类型 | 必填 | 说明 | 6650| -------- | -------------------- | ---- | ------------------------ | 6651| callback | AsyncCallback\<void> | 是 | 回调函数。当暂停播放视频成功，err为undefined，否则为错误对象。 | 6652 6653**示例：** 6654 6655```ts 6656import { BusinessError } from '@kit.BasicServicesKit'; 6657 6658videoPlayer.pause((err: BusinessError) => { 6659 if (err) { 6660 console.error('Failed to pause!'); 6661 } else { 6662 console.info('Succeeded in pausing!'); 6663 } 6664}); 6665``` 6666 6667### pause<sup>(deprecated)</sup> 6668 6669pause(): Promise\<void> 6670 6671暂停播放视频。通过Promise获取返回值。 6672 6673> **说明：** 6674> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9-1)替代。 6675 6676**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6677 6678**返回值：** 6679 6680| 类型 | 说明 | 6681| -------------- | ----------------------------- | 6682| Promise\<void> | 暂停播放视频的Promise返回值。 | 6683 6684**示例：** 6685 6686```ts 6687import { BusinessError } from '@kit.BasicServicesKit'; 6688 6689videoPlayer.pause().then(() => { 6690 console.info('Succeeded in pausing'); 6691}).catch((error: BusinessError) => { 6692 console.error(`video catchCallback, error:${error}`); 6693}); 6694``` 6695 6696### stop<sup>(deprecated)</sup> 6697 6698stop(callback: AsyncCallback\<void>): void 6699 6700通过回调方式停止播放视频。通过回调函数获取返回值。 6701 6702> **说明：** 6703> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9)替代。 6704 6705**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6706 6707**参数：** 6708 6709| 参数名 | 类型 | 必填 | 说明 | 6710| -------- | -------------------- | ---- | ------------------------ | 6711| callback | AsyncCallback\<void> | 是 | 回调函数。当停止播放视频成功，err为undefined，否则为错误对象。 | 6712 6713**示例：** 6714 6715```ts 6716import { BusinessError } from '@kit.BasicServicesKit'; 6717 6718videoPlayer.stop((err: BusinessError) => { 6719 if (err) { 6720 console.error('Failed to stop!'); 6721 } else { 6722 console.info('Succeeded in stopping!'); 6723 } 6724}); 6725``` 6726 6727### stop<sup>(deprecated)</sup> 6728 6729stop(): Promise\<void> 6730 6731停止播放视频。通过Promise获取返回值。 6732 6733> **说明：** 6734> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9-1)替代。 6735 6736**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6737 6738**返回值：** 6739 6740| 类型 | 说明 | 6741| -------------- | ----------------------------- | 6742| Promise\<void> | 停止播放视频的Promise返回值。 | 6743 6744**示例：** 6745 6746```ts 6747import { BusinessError } from '@kit.BasicServicesKit'; 6748 6749videoPlayer.stop().then(() => { 6750 console.info('Succeeded in stopping'); 6751}).catch((error: BusinessError) => { 6752 console.error(`video catchCallback, error:${error}`); 6753}); 6754``` 6755 6756### reset<sup>(deprecated)</sup> 6757 6758reset(callback: AsyncCallback\<void>): void 6759 6760重置播放视频。通过回调函数获取返回值。 6761 6762> **说明：** 6763> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9)替代。 6764 6765**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6766 6767**参数：** 6768 6769| 参数名 | 类型 | 必填 | 说明 | 6770| -------- | -------------------- | ---- | ------------------------ | 6771| callback | AsyncCallback\<void> | 是 | 回调函数。当重置播放视频成功，err为undefined，否则为错误对象。 | 6772 6773**示例：** 6774 6775```ts 6776import { BusinessError } from '@kit.BasicServicesKit'; 6777 6778videoPlayer.reset((err: BusinessError) => { 6779 if (err) { 6780 console.error('Failed to reset!'); 6781 } else { 6782 console.info('Succeeded in resetting!'); 6783 } 6784}); 6785``` 6786 6787### reset<sup>(deprecated)</sup> 6788 6789reset(): Promise\<void> 6790 6791重置播放视频。通过Promise获取返回值。 6792 6793> **说明：** 6794> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9-1)替代。 6795 6796**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6797 6798**返回值：** 6799 6800| 类型 | 说明 | 6801| -------------- | ----------------------------- | 6802| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6803 6804**示例：** 6805 6806```ts 6807import { BusinessError } from '@kit.BasicServicesKit'; 6808 6809videoPlayer.reset().then(() => { 6810 console.info('Succeeded in resetting'); 6811}).catch((error: BusinessError) => { 6812 console.error(`video catchCallback, error:${error}`); 6813}); 6814``` 6815 6816### seek<sup>(deprecated)</sup> 6817 6818seek(timeMs: number, callback: AsyncCallback\<number>): void 6819 6820跳转到指定播放位置，默认跳转到指定时间点的上一个关键帧。通过回调函数获取返回值。 6821 6822> **说明：** 6823> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6824 6825**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6826 6827**参数：** 6828 6829| 参数名 | 类型 | 必填 | 说明 | 6830| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 6831| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6832| callback | AsyncCallback\<number> | 是 | 回调函数。跳转到指定播放位置成功时，err为undefined，data为获取到的跳转到的播放位置，否则为错误对象。 | 6833 6834**示例：** 6835 6836```ts 6837import { BusinessError } from '@kit.BasicServicesKit'; 6838 6839let videoPlayer: media.VideoPlayer; 6840media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6841 if (video != null) { 6842 videoPlayer = video; 6843 console.info('Succeeded in creating VideoPlayer'); 6844 } else { 6845 console.error(`Failed to create VideoPlayer, error:${error}`); 6846 } 6847}); 6848 6849let seekTime: number = 5000; 6850videoPlayer.seek(seekTime, (err: BusinessError, result: number) => { 6851 if (err) { 6852 console.error('Failed to do seek!'); 6853 } else { 6854 console.info('Succeeded in doing seek!'); 6855 } 6856}); 6857``` 6858 6859### seek<sup>(deprecated)</sup> 6860 6861seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\<number>): void 6862 6863跳转到指定播放位置。通过回调函数获取返回值。 6864 6865> **说明：** 6866> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6867 6868**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6869 6870**参数：** 6871 6872| 参数名 | 类型 | 必填 | 说明 | 6873| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 6874| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6875| mode | [SeekMode](#seekmode8) | 是 | 跳转模式。 | 6876| callback | AsyncCallback\<number> | 是 | 回调函数。跳转到指定播放位置成功时，err为undefined，data为获取到的跳转到的播放位置，否则为错误对象。 | 6877 6878**示例：** 6879 6880```ts 6881import { BusinessError } from '@kit.BasicServicesKit'; 6882 6883let videoPlayer: media.VideoPlayer | null = null; 6884media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6885 if (video != null) { 6886 videoPlayer = video; 6887 console.info('Succeeded in creating VideoPlayer'); 6888 } else { 6889 console.error(`Failed to create VideoPlayer, error:${error}`); 6890 } 6891}); 6892let seekTime: number = 5000; 6893if (videoPlayer) { 6894 (videoPlayer as media.VideoPlayer).seek(seekTime, media.SeekMode.SEEK_NEXT_SYNC, (err: BusinessError, result: number) => { 6895 if (err) { 6896 console.error('Failed to do seek!'); 6897 } else { 6898 console.info('Succeeded in doing seek!'); 6899 } 6900 }); 6901} 6902``` 6903 6904### seek<sup>(deprecated)</sup> 6905 6906seek(timeMs: number, mode?:SeekMode): Promise\<number> 6907 6908跳转到指定播放位置，如果没有设置mode则跳转到指定时间点的上一个关键帧。通过Promise获取返回值。 6909 6910> **说明：** 6911> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6912 6913**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6914 6915**参数：** 6916 6917| 参数名 | 类型 | 必填 | 说明 | 6918| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 6919| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6920| mode | [SeekMode](#seekmode8) | 否 | 基于视频I帧的跳转模式，默认为SEEK_PREV_SYNC模式。 | 6921 6922**返回值：** 6923 6924| 类型 | 说明 | 6925| ---------------- | ------------------------------------------- | 6926| Promise\<number> | 跳转到指定播放位置的Promise返回值，单位ms。 | 6927 6928**示例：** 6929 6930```ts 6931import { BusinessError } from '@kit.BasicServicesKit'; 6932 6933let videoPlayer: media.VideoPlayer | null = null; 6934media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6935 if (video != null) { 6936 videoPlayer = video; 6937 console.info('Succeeded in creating VideoPlayer'); 6938 } else { 6939 console.error(`Failed to create VideoPlayer, error:${error}`); 6940 } 6941}); 6942let seekTime: number = 5000; 6943if (videoPlayer) { 6944 (videoPlayer as media.VideoPlayer).seek(seekTime).then((seekDoneTime: number) => { // seekDoneTime表示seek完成后的时间点。 6945 console.info('Succeeded in doing seek'); 6946 }).catch((error: BusinessError) => { 6947 console.error(`video catchCallback, error:${error}`); 6948 }); 6949 6950 (videoPlayer as media.VideoPlayer).seek(seekTime, media.SeekMode.SEEK_NEXT_SYNC).then((seekDoneTime: number) => { 6951 console.info('Succeeded in doing seek'); 6952 }).catch((error: BusinessError) => { 6953 console.error(`video catchCallback, error:${error}`); 6954 }); 6955} 6956``` 6957 6958### setVolume<sup>(deprecated)</sup> 6959 6960setVolume(vol: number, callback: AsyncCallback\<void>): void 6961 6962设置音量。通过回调函数获取返回值。 6963 6964> **说明：** 6965> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 6966 6967**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6968 6969**参数：** 6970 6971| 参数名 | 类型 | 必填 | 说明 | 6972| -------- | -------------------- | ---- | ------------------------------------------------------------ | 6973| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 6974| callback | AsyncCallback\<void> | 是 | 回调函数。当设置音量成功，err为undefined，否则为错误对象。 | 6975 6976**示例：** 6977 6978```ts 6979import { BusinessError } from '@kit.BasicServicesKit'; 6980 6981let vol: number = 0.5; 6982videoPlayer.setVolume(vol, (err: BusinessError) => { 6983 if (err) { 6984 console.error('Failed to set Volume!'); 6985 } else { 6986 console.info('Succeeded in setting Volume!'); 6987 } 6988}); 6989``` 6990 6991### setVolume<sup>(deprecated)</sup> 6992 6993setVolume(vol: number): Promise\<void> 6994 6995设置音量。通过Promise获取返回值。 6996 6997> **说明：** 6998> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 6999 7000**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7001 7002**参数：** 7003 7004| 参数名 | 类型 | 必填 | 说明 | 7005| ------ | ------ | ---- | ------------------------------------------------------------ | 7006| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 7007 7008**返回值：** 7009 7010| 类型 | 说明 | 7011| -------------- | ------------------------- | 7012| Promise\<void> | 设置音量的Promise返回值。 | 7013 7014**示例：** 7015 7016```ts 7017import { BusinessError } from '@kit.BasicServicesKit'; 7018 7019let vol: number = 0.5; 7020videoPlayer.setVolume(vol).then(() => { 7021 console.info('Succeeded in setting Volume'); 7022}).catch((error: BusinessError) => { 7023 console.error(`video catchCallback, error:${error}`); 7024}); 7025``` 7026 7027### release<sup>(deprecated)</sup> 7028 7029release(callback: AsyncCallback\<void>): void 7030 7031释放视频资源。通过回调函数获取返回值。 7032 7033> **说明：** 7034> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9)替代。 7035 7036**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7037 7038**参数：** 7039 7040| 参数名 | 类型 | 必填 | 说明 | 7041| -------- | -------------------- | ---- | ------------------------ | 7042| callback | AsyncCallback\<void> | 是 | 回调函数。当释放视频资源成功，err为undefined，否则为错误对象。 | 7043 7044**示例：** 7045 7046```ts 7047import { BusinessError } from '@kit.BasicServicesKit'; 7048 7049videoPlayer.release((err: BusinessError) => { 7050 if (err) { 7051 console.error('Failed to release!'); 7052 } else { 7053 console.info('Succeeded in releasing!'); 7054 } 7055}); 7056``` 7057 7058### release<sup>(deprecated)</sup> 7059 7060release(): Promise\<void> 7061 7062释放视频资源。通过Promise获取返回值。 7063 7064> **说明：** 7065> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9-1)替代。 7066 7067**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7068 7069**返回值：** 7070 7071| 类型 | 说明 | 7072| -------------- | ----------------------------- | 7073| Promise\<void> | 释放视频资源的Promise返回值。 | 7074 7075**示例：** 7076 7077```ts 7078import { BusinessError } from '@kit.BasicServicesKit'; 7079 7080videoPlayer.release().then(() => { 7081 console.info('Succeeded in releasing'); 7082}).catch((error: BusinessError) => { 7083 console.error(`video catchCallback, error:${error}`); 7084}); 7085``` 7086 7087### getTrackDescription<sup>(deprecated)</sup> 7088 7089getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 7090 7091获取视频轨道信息。通过回调函数获取返回值。 7092 7093> **说明：** 7094> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9)替代。 7095 7096**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7097 7098**参数：** 7099 7100| 参数名 | 类型 | 必填 | 说明 | 7101| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 7102| callback | AsyncCallback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 回调函数。获取视频轨道信息成功时，err为undefined，data为获取到的视频轨道信息MediaDescription数组，否则为错误对象。 | 7103 7104**示例：** 7105 7106```ts 7107import { BusinessError } from '@kit.BasicServicesKit'; 7108 7109videoPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 7110 if ((arrList) != null) { 7111 console.info('Succeeded in getting TrackDescription'); 7112 } else { 7113 console.error(`Failed to get TrackDescription, error:${error}`); 7114 } 7115}); 7116``` 7117 7118### getTrackDescription<sup>(deprecated)</sup> 7119 7120getTrackDescription(): Promise\<Array\<MediaDescription>> 7121 7122获取视频轨道信息。通过Promise获取返回值。 7123 7124> **说明：** 7125> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9-1)替代。 7126 7127**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7128 7129**返回值：** 7130 7131| 类型 | 说明 | 7132| ------------------------------------------------------ | ----------------------------------------------- | 7133| Promise<Array<[MediaDescription](#mediadescription8)>> | Promise对象，返回获取的视频轨道信息MediaDescription数组。 | 7134 7135**示例：** 7136 7137```ts 7138import { BusinessError } from '@kit.BasicServicesKit'; 7139 7140videoPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 7141 if (arrList != null) { 7142 console.info('Succeeded in getting TrackDescription'); 7143 } else { 7144 console.error('Failed to get TrackDescription'); 7145 } 7146}).catch((error: BusinessError) => { 7147 console.error(`video catchCallback, error:${error}`); 7148}); 7149``` 7150 7151### setSpeed<sup>(deprecated)</sup> 7152 7153setSpeed(speed: number, callback: AsyncCallback\<number>): void 7154 7155设置播放速度。通过回调函数获取返回值。 7156 7157> **说明：** 7158> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setSpeed](#setspeed9)替代。 7159 7160**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7161 7162**参数：** 7163 7164| 参数名 | 类型 | 必填 | 说明 | 7165| -------- | ---------------------- | ---- | ---------------------------------------------------------- | 7166| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 7167| callback | AsyncCallback\<number> | 是 | 回调函数。设置播放速度成功时，err为undefined，data为设置的播放速度，否则为错误对象。 | 7168 7169**示例：** 7170 7171```ts 7172import { BusinessError } from '@kit.BasicServicesKit'; 7173 7174let videoPlayer: media.VideoPlayer | null = null; 7175media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 7176 if (video != null) { 7177 videoPlayer = video; 7178 console.info('Succeeded in creating VideoPlayer'); 7179 } else { 7180 console.error(`Failed to create VideoPlayer, error:${error}`); 7181 } 7182}); 7183let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X; 7184if (videoPlayer) { 7185 (videoPlayer as media.VideoPlayer).setSpeed(speed, (err: BusinessError, result: number) => { 7186 if (err) { 7187 console.error('Failed to set Speed!'); 7188 } else { 7189 console.info('Succeeded in setting Speed!'); 7190 } 7191 }); 7192} 7193``` 7194 7195### setSpeed<sup>(deprecated)</sup> 7196 7197setSpeed(speed: number): Promise\<number> 7198 7199设置播放速度。通过Promise获取返回值。 7200 7201> **说明：** 7202> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setSpeed](#setspeed9)替代。 7203 7204**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7205 7206**参数：** 7207 7208| 参数名 | 类型 | 必填 | 说明 | 7209| ------ | ------ | ---- | ---------------------------------------------------------- | 7210| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 7211 7212**返回值：** 7213 7214| 类型 | 说明 | 7215| ---------------- | ------------------------------------------------------------ | 7216| Promise\<number> | Promise对象，返回设置的播放速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 7217 7218**示例：** 7219 7220```ts 7221import { BusinessError } from '@kit.BasicServicesKit'; 7222 7223let videoPlayer: media.VideoPlayer | null = null; 7224media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 7225 if (video != null) { 7226 videoPlayer = video; 7227 console.info('Succeeded in creating VideoPlayer'); 7228 } else { 7229 console.error(`Failed to create VideoPlayer, error:${error}`); 7230 } 7231}); 7232let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X; 7233if (videoPlayer) { 7234 (videoPlayer as media.VideoPlayer).setSpeed(speed).then((result: number) => { 7235 console.info('Succeeded in setting Speed'); 7236 }).catch((error: BusinessError) => { 7237 console.error(`Failed to set Speed, error:${error}`);//todo:: error. 7238 }); 7239} 7240``` 7241 7242### on('playbackCompleted')<sup>(deprecated)</sup> 7243 7244on(type: 'playbackCompleted', callback: Callback\<void>): void 7245 7246开始监听视频播放完成事件。 7247 7248> **说明：** 7249> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('stateChange')](#onstatechange9)替代。 7250 7251**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7252 7253**参数：** 7254 7255| 参数名 | 类型 | 必填 | 说明 | 7256| -------- | -------- | ---- | ----------------------------------------------------------- | 7257| type | string | 是 | 视频播放完成事件回调类型，支持的事件：'playbackCompleted'。 | 7258| callback | Callback\<void> | 是 | 视频播放完成事件回调方法。 | 7259 7260**示例：** 7261 7262```ts 7263videoPlayer.on('playbackCompleted', () => { 7264 console.info('playbackCompleted called!'); 7265}); 7266``` 7267 7268### on('bufferingUpdate')<sup>(deprecated)</sup> 7269 7270on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void 7271 7272开始监听视频缓存更新事件。仅网络播放支持该订阅事件。 7273 7274> **说明：** 7275> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('bufferingUpdate')](#onbufferingupdate9)替代。 7276 7277**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7278 7279**参数：** 7280 7281| 参数名 | 类型 | 必填 | 说明 | 7282| -------- | -------- | ---- | ------------------------------------------------------------ | 7283| type | string | 是 | 视频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 7284| callback | function | 是 | 视频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)value值固定为0。 | 7285 7286**示例：** 7287 7288```ts 7289videoPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 7290 console.info('video bufferingInfo type: ' + infoType); 7291 console.info('video bufferingInfo value: ' + value); 7292}); 7293``` 7294 7295### on('startRenderFrame')<sup>(deprecated)</sup> 7296 7297on(type: 'startRenderFrame', callback: Callback\<void>): void 7298 7299开始监听视频播放首帧送显上报事件。 7300 7301> **说明：** 7302> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('startRenderFrame')](#onstartrenderframe9)替代。 7303 7304**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7305 7306**参数：** 7307 7308| 参数名 | 类型 | 必填 | 说明 | 7309| -------- | --------------- | ---- | ------------------------------------------------------------ | 7310| type | string | 是 | 视频播放首帧送显上报事件回调类型，支持的事件：'startRenderFrame'。 | 7311| callback | Callback\<void> | 是 | 视频播放首帧送显上报事件回调方法。 | 7312 7313**示例：** 7314 7315```ts 7316videoPlayer.on('startRenderFrame', () => { 7317 console.info('startRenderFrame called!'); 7318}); 7319``` 7320 7321### on('videoSizeChanged')<sup>(deprecated)</sup> 7322 7323on(type: 'videoSizeChanged', callback: (width: number, height: number) => void): void 7324 7325开始监听视频播放宽高变化事件。 7326 7327> **说明：** 7328> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('videoSizeChange')](#onvideosizechange9)替代。 7329 7330**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7331 7332**参数：** 7333 7334| 参数名 | 类型 | 必填 | 说明 | 7335| -------- | -------- | ---- | ------------------------------------------------------------ | 7336| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChanged'。 | 7337| callback | function | 是 | 视频播放宽高变化事件回调方法，width表示宽，height表示高。 | 7338 7339**示例：** 7340 7341```ts 7342videoPlayer.on('videoSizeChanged', (width: number, height: number) => { 7343 console.info('video width is: ' + width); 7344 console.info('video height is: ' + height); 7345}); 7346``` 7347### on('audioInterrupt')<sup>(deprecated)</sup> 7348 7349on(type: 'audioInterrupt', callback: (info: audio.InterruptEvent) => void): void 7350 7351监听音频焦点变化事件，参考[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)。 7352 7353> **说明：** 7354> 从API version 9开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('audioInterrupt')](#onaudiointerrupt9)替代。 7355 7356**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7357 7358**参数：** 7359 7360| 参数名 | 类型 | 必填 | 说明 | 7361| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 7362| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 7363| callback | function | 是 | 音频焦点变化事件回调方法。 | 7364 7365**示例：** 7366 7367```ts 7368import { audio } from '@kit.AudioKit'; 7369 7370videoPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 7371 console.info('audioInterrupt called,and InterruptEvent info is:' + info); 7372}); 7373``` 7374 7375### on('error')<sup>(deprecated)</sup> 7376 7377on(type: 'error', callback: ErrorCallback): void 7378 7379开始监听视频播放错误事件，当上报error错误事件后，用户需处理error事件，退出播放操作。 7380 7381> **说明：** 7382> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('error')](#onerror9)替代。 7383 7384**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7385 7386**参数：** 7387 7388| 参数名 | 类型 | 必填 | 说明 | 7389| -------- | ------------- | ---- | ------------------------------------------------------------ | 7390| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：视频播放中发生错误，触发该事件。 | 7391| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 播放错误事件回调方法。 | 7392 7393**示例：** 7394 7395```ts 7396import { BusinessError } from '@kit.BasicServicesKit'; 7397 7398videoPlayer.on('error', (error: BusinessError) => { // 设置'error'事件回调。 7399 console.error(`video error called, error: ${error}`); 7400}); 7401videoPlayer.url = 'fd://error'; //设置错误的播放地址，触发'error'事件。 7402``` 7403 7404## VideoPlayState<sup>(deprecated)</sup> 7405 7406type VideoPlayState = 'idle' | 'prepared' | 'playing' | 'paused' | 'stopped' | 'error' 7407 7408视频播放的状态机，可通过state属性获取当前状态。 7409 7410> **说明：** 7411> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayerState](#avplayerstate9)替代。 7412 7413**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7414 7415| 类型 | 说明 | 7416| -------- | -------------- | 7417| 'idle' | 视频播放空闲。 | 7418| 'prepared' | 视频播放准备。 | 7419| 'playing' | 视频正在播放。 | 7420| 'paused' | 视频暂停播放。 | 7421| 'stopped' | 视频播放停止。 | 7422| 'error' | 错误状态。 | 7423 7424## AudioRecorder<sup>(deprecated)</sup> 7425 7426> **说明：** 7427> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder](#avrecorder9)替代。 7428 7429音频录制管理类，用于录制音频媒体。在调用AudioRecorder的方法前，需要先通过[createAudioRecorder()](#mediacreateaudiorecorderdeprecated) 构建一个AudioRecorder实例。 7430 7431### prepare<sup>(deprecated)</sup> 7432 7433prepare(config: AudioRecorderConfig): void 7434 7435录音准备。 7436 7437> **说明：** 7438> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.prepare](#prepare9-2)替代。 7439 7440**需要权限：** ohos.permission.MICROPHONE 7441 7442**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7443 7444**参数：** 7445 7446| 参数名 | 类型 | 必填 | 说明 | 7447| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ | 7448| config | [AudioRecorderConfig](#audiorecorderconfigdeprecated) | 是 | 配置录音的相关参数，包括音频输出URI、编码格式、采样率、声道数、输出格式等。 | 7449 7450**错误码：** 7451 7452以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7453 7454| 错误码ID | 错误信息 | 7455| -------- | --------------------- | 7456| 201 | permission denied | 7457 7458**示例：** 7459 7460```ts 7461let audioRecorderConfig: media.AudioRecorderConfig = { 7462 audioEncoder : media.AudioEncoder.AAC_LC, 7463 audioEncodeBitRate : 22050, 7464 audioSampleRate : 22050, 7465 numberOfChannels : 2, 7466 format : media.AudioOutputFormat.AAC_ADTS, 7467 uri : 'fd://1', // 文件需先由调用者创建，并给予适当的权限。 7468 location : { latitude : 30, longitude : 130}, 7469}; 7470audioRecorder.on('prepare', () => { //设置'prepare'事件回调。 7471 console.info('prepare called'); 7472}); 7473audioRecorder.prepare(audioRecorderConfig); 7474``` 7475 7476### start<sup>(deprecated)</sup> 7477 7478start(): void 7479 7480开始录制，需在'prepare'事件成功触发后，才能调用start方法。 7481 7482> **说明：** 7483> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.start](#start9)替代。 7484 7485**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7486 7487**示例：** 7488 7489```ts 7490audioRecorder.on('start', () => { //设置'start'事件回调。 7491 console.info('audio recorder start called'); 7492}); 7493audioRecorder.start(); 7494``` 7495 7496### pause<sup>(deprecated)</sup> 7497 7498pause():void 7499 7500暂停录制，需要在'start'事件成功触发后，才能调用pause方法。 7501 7502> **说明：** 7503> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.pause](#pause9-2)替代。 7504 7505**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7506 7507**示例：** 7508 7509```ts 7510audioRecorder.on('pause', () => { //设置'pause'事件回调。 7511 console.info('audio recorder pause called'); 7512}); 7513audioRecorder.pause(); 7514``` 7515 7516### resume<sup>(deprecated)</sup> 7517 7518resume():void 7519 7520恢复录制，需要在'pause'事件成功触发后，才能调用resume方法。 7521 7522> **说明：** 7523> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.resume](#resume9)替代。 7524 7525**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7526 7527**示例：** 7528 7529```ts 7530audioRecorder.on('resume', () => { //设置'resume'事件回调。 7531 console.info('audio recorder resume called'); 7532}); 7533audioRecorder.resume(); 7534``` 7535 7536### stop<sup>(deprecated)</sup> 7537 7538stop(): void 7539 7540停止录音。 7541 7542> **说明：** 7543> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.stop](#stop9-2)替代。 7544 7545**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7546 7547**示例：** 7548 7549```ts 7550audioRecorder.on('stop', () => { //设置'stop'事件回调。 7551 console.info('audio recorder stop called'); 7552}); 7553audioRecorder.stop(); 7554``` 7555 7556### release<sup>(deprecated)</sup> 7557 7558release(): void 7559 7560释放录音资源。 7561 7562> **说明：** 7563> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.release](#release9-2)替代。 7564 7565**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7566 7567**示例：** 7568 7569```ts 7570audioRecorder.on('release', () => { //设置'release'事件回调。 7571 console.info('audio recorder release called'); 7572}); 7573audioRecorder.release(); 7574audioRecorder = undefined; 7575``` 7576 7577### reset<sup>(deprecated)</sup> 7578 7579reset(): void 7580 7581重置录音。 7582 7583进行重置录音之前，需要先调用stop()停止录音。重置录音之后，需要调用prepare()设置录音参数项，才能再次进行录音。 7584 7585> **说明：** 7586> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.reset](#reset9-2)替代。 7587 7588**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7589 7590**示例：** 7591 7592```ts 7593audioRecorder.on('reset', () => { //设置'reset'事件回调。 7594 console.info('audio recorder reset called'); 7595}); 7596audioRecorder.reset(); 7597``` 7598 7599### on('prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset')<sup>(deprecated)</sup> 7600 7601on(type: 'prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset', callback: () => void): void 7602 7603开始订阅音频录制事件。 7604 7605> **说明：** 7606> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.on('stateChange')](#onstatechange9-1)替代。 7607 7608**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7609 7610**参数：** 7611 7612| 参数名 | 类型 | 必填 | 说明 | 7613| -------- | -------- | ---- | ------------------------------------------------------------ | 7614| type | string | 是 | 录制事件回调类型，支持的事件包括：'prepare' \| 'start' \| 'pause' \| ’resume‘ \| 'stop' \| 'release' \| 'reset'。<br/>- 'prepare' ：完成prepare调用，音频录制参数设置完成，触发该事件。<br/>- 'start' ：完成start调用，音频录制开始，触发该事件。<br/>- 'pause': 完成pause调用，音频暂停录制，触发该事件。<br/>- 'resume': 完成resume调用，音频恢复录制，触发该事件。<br/>- 'stop' ：完成stop调用，音频停止录制，触发该事件。<br/>- 'release' ：完成release调用，音频释放录制资源，触发该事件。<br/>- 'reset'：完成reset调用，音频重置为初始状态，触发该事件。 | 7615| callback | ()=>void | 是 | 录制事件回调方法。 | 7616 7617**示例：** 7618 7619```ts 7620import { BusinessError } from '@kit.BasicServicesKit'; 7621 7622let audioRecorder: media.AudioRecorder = media.createAudioRecorder(); // 创建一个音频录制实例。 7623let audioRecorderConfig: media.AudioRecorderConfig = { 7624 audioEncoder : media.AudioEncoder.AAC_LC, 7625 audioEncodeBitRate : 22050, 7626 audioSampleRate : 22050, 7627 numberOfChannels : 2, 7628 format : media.AudioOutputFormat.AAC_ADTS, 7629 uri : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限。 7630 location : { latitude : 30, longitude : 130} 7631}; 7632audioRecorder.on('error', (error: BusinessError) => { // 设置'error'事件回调。 7633 console.error(`audio error called, error: ${error}`); 7634}); 7635audioRecorder.on('prepare', () => { // 设置'prepare'事件回调。 7636 console.info('prepare called'); 7637 audioRecorder.start(); // 开始录制，并触发'start'事件回调。 7638}); 7639audioRecorder.on('start', () => { // 设置'start'事件回调。 7640 console.info('audio recorder start called'); 7641}); 7642audioRecorder.on('pause', () => { // 设置'pause'事件回调。 7643 console.info('audio recorder pause called'); 7644}); 7645audioRecorder.on('resume', () => { // 设置'resume'事件回调。 7646 console.info('audio recorder resume called'); 7647}); 7648audioRecorder.on('stop', () => { // 设置'stop'事件回调。 7649 console.info('audio recorder stop called'); 7650}); 7651audioRecorder.on('release', () => { // 设置'release'事件回调。 7652 console.info('audio recorder release called'); 7653}); 7654audioRecorder.on('reset', () => { // 设置'reset'事件回调。 7655 console.info('audio recorder reset called'); 7656}); 7657audioRecorder.prepare(audioRecorderConfig) // 设置录制参数 ，并触发'prepare'事件回调。 7658``` 7659 7660### on('error')<sup>(deprecated)</sup> 7661 7662on(type: 'error', callback: ErrorCallback): void 7663 7664开始订阅音频录制错误事件，当上报error错误事件后，用户需处理error事件，退出录制操作。 7665 7666> **说明：** 7667> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.on('error')](#onerror9-1)替代。 7668 7669**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7670 7671**参数：** 7672 7673| 参数名 | 类型 | 必填 | 说明 | 7674| -------- | ------------- | ---- | ------------------------------------------------------------ | 7675| type | string | 是 | 录制错误事件回调类型'error'。<br/>- 'error'：音频录制过程中发生错误，触发该事件。 | 7676| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录制错误事件回调方法。 | 7677 7678**示例：** 7679 7680```ts 7681import { BusinessError } from '@kit.BasicServicesKit'; 7682 7683let audioRecorderConfig: media.AudioRecorderConfig = { 7684 audioEncoder : media.AudioEncoder.AAC_LC, 7685 audioEncodeBitRate : 22050, 7686 audioSampleRate : 22050, 7687 numberOfChannels : 2, 7688 format : media.AudioOutputFormat.AAC_ADTS, 7689 uri : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限。 7690 location : { latitude : 30, longitude : 130} 7691}; 7692audioRecorder.on('error', (error: BusinessError) => { // 设置'error'事件回调。 7693 console.error(`audio error called, error: ${error}`); 7694}); 7695audioRecorder.prepare(audioRecorderConfig); // prepare不设置参数，触发'error'事件。 7696``` 7697 7698## AudioRecorderConfig<sup>(deprecated)</sup> 7699 7700> **说明：** 7701> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorderConfig](#avrecorderconfig9)替代。 7702 7703表示音频的录音配置。 7704 7705**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7706 7707| 名称 | 类型 | 必填 | 说明 | 7708| ----------------------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 7709| audioEncoder | [AudioEncoder](#audioencoderdeprecated) | 否 | 音频编码格式，默认设置为AAC_LC。<br/>**说明：** 从API version 8开始废弃，建议使用audioEncoderMime替代。 | 7710| audioEncodeBitRate | number | 否 | 音频编码比特率，默认值为48000。 | 7711| audioSampleRate | number | 否 | 音频采集采样率，默认值为48000。<br>可变比特率模式，码率仅作参考。 | 7712| numberOfChannels | number | 否 | 音频采集声道数，默认值为2。 | 7713| format | [AudioOutputFormat](#audiooutputformatdeprecated) | 否 | 音频输出封装格式，默认设置为MPEG_4。<br/>**说明：** 从API version 8开始废弃，建议使用fileFormat替代。 | 7714| location | [Location](#location) | 否 | 音频采集的地理位置。 | 7715| uri | string | 是 | 音频输出URI：fd://xx (fd number)<br/> <br/>文件需要由调用者创建，并赋予适当的权限。 | 7716| audioEncoderMime<sup>8+</sup> | [CodecMimeType](#codecmimetype8) | 否 | 容器编码格式。 | 7717| fileFormat<sup>8+</sup> | [ContainerFormatType](#containerformattype8) | 否 | 音频编码格式。 | 7718 7719## AudioEncoder<sup>(deprecated)</sup> 7720 7721> **说明：** 7722> 从API version 6开始支持，从API version 8开始废弃，建议使用[CodecMimeType](#codecmimetype8)替代。 7723 7724表示音频编码格式的枚举。 7725 7726**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7727 7728| 名称 | 值 | 说明 | 7729| ------- | ---- | ------------------------------------------------------------ | 7730| DEFAULT | 0 | 默认编码格式。<br/>仅做接口定义，暂不支持使用。 | 7731| AMR_NB | 1 | AMR-NB(Adaptive Multi Rate-Narrow Band Speech Codec) 编码格式。<br/>仅做接口定义，暂不支持使用。 | 7732| AMR_WB | 2 | AMR-WB(Adaptive Multi Rate-Wide Band Speech Codec) 编码格式。<br/>仅做接口定义，暂不支持使用。 | 7733| AAC_LC | 3 | AAC-LC（Advanced Audio Coding Low Complexity）编码格式。 | 7734| HE_AAC | 4 | HE_AAC（High-Efficiency Advanced Audio Coding）编码格式。<br/>仅做接口定义，暂不支持使用。 | 7735 7736## AudioOutputFormat<sup>(deprecated)</sup> 7737 7738> **说明：** 7739> 从API version 6开始支持，从API version 8 开始废弃，建议使用[ContainerFormatType](#containerformattype8)替代。 7740 7741表示音频封装格式的枚举。 7742 7743**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7744 7745| 名称 | 值 | 说明 | 7746| -------- | ---- | ------------------------------------------------------------ | 7747| DEFAULT | 0 | 默认封装格式。<br/>仅做接口定义，暂不支持使用。 | 7748| MPEG_4 | 2 | 封装为MPEG-4格式。 | 7749| AMR_NB | 3 | 封装为AMR_NB格式。<br/>仅做接口定义，暂不支持使用。 | 7750| AMR_WB | 4 | 封装为AMR_WB格式。<br/>仅做接口定义，暂不支持使用。 | 7751| AAC_ADTS | 6 | 封装为ADTS（Audio Data Transport Stream）格式，是AAC音频的传输流格式。 | 7752 7753 7754## media.createAVImageGenerator<sup>12+</sup> 7755 7756createAVImageGenerator(callback: AsyncCallback\<AVImageGenerator>): void 7757 7758创建AVImageGenerator实例，通过回调函数获取返回值。 7759 7760**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7761 7762**参数：** 7763 7764| 参数名 | 类型 | 必填 | 说明 | 7765| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 7766| callback | AsyncCallback\<[AVImageGenerator](#avimagegenerator12)> | 是 | 回调函数。异步返回AVImageGenerator实例，失败时返回null。可用于获取视频缩略图。 | 7767 7768**错误码：** 7769 7770以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7771 7772| 错误码ID | 错误信息 | 7773| -------- | ------------------------------ | 7774| 5400101 | No memory. Returned by callback. | 7775 7776**示例：** 7777 7778```ts 7779import { BusinessError } from '@kit.BasicServicesKit'; 7780 7781let avImageGenerator: media.AVImageGenerator; 7782media.createAVImageGenerator((error: BusinessError, generator: media.AVImageGenerator) => { 7783 if (generator != null) { 7784 avImageGenerator = generator; 7785 console.info('Succeeded in creating AVImageGenerator'); 7786 } else { 7787 console.error(`Failed to creat AVImageGenerator, error message:${error.message}`); 7788 } 7789}); 7790``` 7791 7792## media.createAVImageGenerator<sup>12+</sup> 7793 7794createAVImageGenerator(): Promise\<AVImageGenerator> 7795 7796创建AVImageGenerator对象，通过Promise获取返回值。 7797 7798**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7799 7800**返回值：** 7801 7802| 类型 | 说明 | 7803| ------------------------------- | ------------------------------------------------------------ | 7804| Promise\<[AVImageGenerator](#avimagegenerator12)> | Promise对象。异步返回AVImageGenerator实例，失败时返回null。可用于获取视频缩略图。 | 7805 7806**错误码：** 7807 7808以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7809 7810| 错误码ID | 错误信息 | 7811| -------- | ----------------------------- | 7812| 5400101 | No memory. Returned by promise. | 7813 7814**示例：** 7815 7816```ts 7817import { BusinessError } from '@kit.BasicServicesKit'; 7818 7819let avImageGenerator: media.AVImageGenerator; 7820media.createAVImageGenerator().then((generator: media.AVImageGenerator) => { 7821 if (generator != null) { 7822 avImageGenerator = generator; 7823 console.info('Succeeded in creating AVImageGenerator'); 7824 } else { 7825 console.error('Failed to creat AVImageGenerator'); 7826 } 7827}).catch((error: BusinessError) => { 7828 console.error(`Failed to creat AVImageGenerator, error message:${error.message}`); 7829}); 7830``` 7831 7832## AVImageGenerator<sup>12+</sup> 7833 7834视频缩略图获取类，用于从视频资源中获取缩略图。在调用AVImageGenerator的方法前，需要先通过[createAVImageGenerator()](#mediacreateavimagegenerator12)构建一个AVImageGenerator实例。 7835 7836获取视频缩略图的demo可参考：[获取视频缩略图开发指导](../../media/media/avimagegenerator.md)。 7837 7838### 属性 7839 7840**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7841 7842| 名称 | 类型 | 可读 | 可写 | 说明 | 7843| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 7844| fdSrc<sup>12+</sup> | [AVFileDescriptor](js-apis-media.md#avfiledescriptor9) | 是 | 是 | 媒体文件描述，通过该属性设置数据源。<br/> **使用示例**：<br/>假设一个连续存储的媒体文件，地址偏移:0，字节长度:100。其文件描述为 AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVImageGenerator 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频缩略图数据获取异常。 | 7845 7846### fetchFrameByTime<sup>12+</sup> 7847 7848fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams, callback: AsyncCallback\<image.PixelMap>): void 7849 7850异步方式获取视频缩略图。通过注册回调函数获取返回值。 7851 7852**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7853 7854**参数：** 7855 7856| 参数名 | 类型 | 必填 | 说明 | 7857| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7858| timeUs | number | 是 | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 | 7859| options | [AVImageQueryOptions](#avimagequeryoptions12) | 是 | 需要获取的缩略图时间点与视频帧的对应关系。 | 7860| param | [PixelMapParams](#pixelmapparams12) | 是 | 需要获取的缩略图的格式参数。 | 7861| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | 是 | 回调函数。获取缩略图成功时，err为undefined，data为PixelMap实例，否则为错误对象。 | 7862 7863**错误码：** 7864 7865以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7866 7867| 错误码ID | 错误信息 | 7868| -------- | ------------------------------------------ | 7869| 5400102 | Operation not allowed. Returned by callback. | 7870| 5400106 | Unsupported format. Returned by callback. | 7871 7872**示例：** 7873 7874```ts 7875import { BusinessError } from '@kit.BasicServicesKit'; 7876import { image } from '@kit.ImageKit'; 7877 7878let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7879let pixel_map : image.PixelMap | undefined = undefined; 7880 7881// 初始化入参。 7882let timeUs: number = 0; 7883 7884let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC; 7885 7886let param: media.PixelMapParams = { 7887 width : 300, 7888 height : 300, 7889}; 7890 7891// 获取缩略图。 7892media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7893 if(generator != null){ 7894 avImageGenerator = generator; 7895 console.info(`Succeeded in creating AVImageGenerator`); 7896 avImageGenerator.fetchFrameByTime(timeUs, queryOption, param, (error: BusinessError, pixelMap) => { 7897 if (error) { 7898 console.error(`Failed to fetch FrameByTime, err = ${JSON.stringify(error)}`); 7899 return; 7900 } 7901 pixel_map = pixelMap; 7902 }); 7903 } else { 7904 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7905 }; 7906}); 7907``` 7908 7909### fetchFrameByTime<sup>12+</sup> 7910 7911fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams): Promise<image.PixelMap> 7912 7913异步方式获取视频缩略图。通过Promise获取返回值。 7914 7915**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7916 7917**参数：** 7918 7919| 参数名 | 类型 | 必填 | 说明 | 7920| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7921| timeUs | number | 是 | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 | 7922| options | [AVImageQueryOptions](#avimagequeryoptions12) | 是 | 需要获取的缩略图时间点与视频帧的对应关系。 | 7923| param | [PixelMapParams](#pixelmapparams12) | 是 | 需要获取的缩略图的格式参数。 | 7924 7925**返回值：** 7926 7927| 类型 | 说明 | 7928| -------------- | ---------------------------------------- | 7929| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象，返回视频缩略图对象。 | 7930 7931**错误码：** 7932 7933以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7934 7935| 错误码ID | 错误信息 | 7936| -------- | ----------------------------------------- | 7937| 5400102 | Operation not allowed. Returned by promise. | 7938| 5400106 | Unsupported format. Returned by promise. | 7939 7940**示例：** 7941 7942```ts 7943import { BusinessError } from '@kit.BasicServicesKit'; 7944import { image } from '@kit.ImageKit'; 7945 7946let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7947let pixel_map : image.PixelMap | undefined = undefined; 7948 7949// 初始化入参。 7950let timeUs: number = 0; 7951 7952let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC; 7953 7954let param: media.PixelMapParams = { 7955 width : 300, 7956 height : 300, 7957}; 7958 7959// 获取缩略图。 7960media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7961 if(generator != null){ 7962 avImageGenerator = generator; 7963 console.info(`Succeeded in creating AVImageGenerator`); 7964 avImageGenerator.fetchFrameByTime(timeUs, queryOption, param).then((pixelMap: image.PixelMap) => { 7965 pixel_map = pixelMap; 7966 }).catch((error: BusinessError) => { 7967 console.error(`Failed to fetch FrameByTime, error message:${error.message}`); 7968 }); 7969 } else { 7970 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7971 }; 7972}); 7973``` 7974 7975### fetchScaledFrameByTime<sup>20+</sup> 7976 7977fetchScaledFrameByTime(timeUs: number, queryMode: AVImageQueryOptions, outputSize?: OutputSize):Promise\<image.PixelMap\> 7978 7979支持按比例缩放提取视频缩略图。使用Promise异步回调。 7980 7981**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7982 7983**参数：** 7984 7985| 参数名 | 类型 | 必填 | 说明 | 7986| ---------- | --------------------------------------------- | ---- | ---------------------------------------------------- | 7987| timeUs | number | 是 | 在视频中需要获取的缩略图的时间点，单位为微秒（μs）。 | 7988| queryMode | [AVImageQueryOptions](#avimagequeryoptions12) | 是 | 需要获取的缩略图时间点与视频帧的对应关系。 | 7989| outputSize | [OutputSize ](#outputsize20) | 否 | 定义帧的输出大小。默认按原图大小显示。 | 7990 7991**返回值：** 7992 7993| 类型 | 说明 | 7994| ------------------------------------------------------------ | --------------------------------- | 7995| Promise\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)> | Promise对象。返回视频缩略图对象。 | 7996 7997**错误码：** 7998 7999以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 8000 8001| 错误码ID | 错误信息 | 8002| -------- | ------------------------------------------- | 8003| 5400102 | Operation not allowed. Returned by promise. | 8004| 5400106 | Unsupported format. Returned by promise. | 8005 8006**示例：** 8007 8008```ts 8009import { BusinessError } from '@kit.BasicServicesKit'; 8010import { image } from '@kit.ImageKit'; 8011import { media } from '@kit.MediaKit'; 8012let avImageGenerator: media.AVImageGenerator | undefined = undefined; 8013let pixel_map : image.PixelMap | undefined = undefined; 8014// 初始化入参。 8015let timeUs: number = 0; 8016let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC; 8017let outputSize: media.OutputSize = { 8018 width : 300, 8019 height : 300, 8020}; 8021// 获取缩略图。 8022media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 8023 if(generator != null){ 8024 avImageGenerator = generator; 8025 console.info(`Succeeded in creating AVImageGenerator`); 8026 avImageGenerator.fetchScaledFrameByTime(timeUs, queryOption, outputSize).then((pixelMap: image.PixelMap) => { 8027 pixel_map = pixelMap; 8028 }).catch((error: BusinessError) => { 8029 console.error(`Failed to fetch ScaledFrameByTime, error message:${error.message}`); 8030 }); 8031 } else { 8032 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 8033 }; 8034}); 8035``` 8036 8037### release<sup>12+</sup> 8038 8039release(callback: AsyncCallback\<void>): void 8040 8041异步方式释放资源。通过注册回调函数获取返回值。 8042 8043**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 8044 8045**参数：** 8046 8047| 参数名 | 类型 | 必填 | 说明 | 8048| -------- | -------------------------------------------- | ---- | ----------------------------------- | 8049| callback | AsyncCallback\<void> | 是 | 回调函数。当释放资源成功，err为undefined，否则为错误对象。 | 8050 8051**错误码：** 8052 8053以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 8054 8055| 错误码ID | 错误信息 | 8056| -------- | ------------------------------------------ | 8057| 5400102 | Operation not allowed. Returned by callback. | 8058 8059**示例：** 8060 8061```ts 8062import { BusinessError } from '@kit.BasicServicesKit'; 8063 8064let avImageGenerator: media.AVImageGenerator | undefined = undefined; 8065 8066//释放资源。 8067media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 8068 if(generator != null){ 8069 avImageGenerator = generator; 8070 console.info(`Succeeded in creating AVImageGenerator`); 8071 avImageGenerator.release((error: BusinessError) => { 8072 if (error) { 8073 console.error(`Failed to release, err = ${JSON.stringify(error)}`); 8074 return; 8075 } 8076 console.info(`Succeeded in releasing`); 8077 }); 8078 } else { 8079 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 8080 }; 8081}); 8082``` 8083 8084### release<sup>12+</sup> 8085 8086release(): Promise\<void> 8087 8088异步方式释放资源。通过Promise获取返回值。 8089 8090**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 8091 8092**返回值：** 8093 8094| 类型 | 说明 | 8095| -------------- | ---------------------------------------- | 8096| Promise\<void> | 异步方式释放资源release方法的Promise返回值。 | 8097 8098**错误码：** 8099 8100以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 8101 8102| 错误码ID | 错误信息 | 8103| -------- | ----------------------------------------- | 8104| 5400102 | Operation not allowed. Returned by promise. | 8105 8106**示例：** 8107 8108```ts 8109import { BusinessError } from '@kit.BasicServicesKit'; 8110 8111let avImageGenerator: media.AVImageGenerator | undefined = undefined; 8112 8113//释放资源 8114media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 8115 if(generator != null){ 8116 avImageGenerator = generator; 8117 console.info(`Succeeded in creating AVImageGenerator`); 8118 avImageGenerator.release().then(() => { 8119 console.info(`Succeeded in releasing.`); 8120 }).catch((error: BusinessError) => { 8121 console.error(`Failed to release, error message:${error.message}`); 8122 }); 8123 } else { 8124 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 8125 }; 8126}); 8127``` 8128 8129## AVImageQueryOptions<sup>12+</sup> 8130 8131需要获取的缩略图时间点与视频帧的对应关系。 8132 8133在获取视频缩略图时，传入的时间点与实际取得的视频帧所在时间点不一定相等，需要指定传入的时间点与实际取得的视频帧的时间关系。 8134 8135**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 8136 8137| 名称 | 值 | 说明 | 8138| ------------------------ | --------------- | ------------------------------------------------------------ | 8139| AV_IMAGE_QUERY_NEXT_SYNC | 0 | 表示选取传入时间点或之后的关键帧。 | 8140| AV_IMAGE_QUERY_PREVIOUS_SYNC | 1 | 表示选取传入时间点或之前的关键帧。 | 8141| AV_IMAGE_QUERY_CLOSEST_SYNC | 2 | 表示选取离传入时间点最近的关键帧。 | 8142| AV_IMAGE_QUERY_CLOSEST | 3 | 表示选取离传入时间点最近的帧，该帧不一定是关键帧。 | 8143 8144## PixelMapParams<sup>12+</sup> 8145 8146获取视频缩略图时，输出缩略图的格式参数。 8147 8148**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 8149 8150| 名称 | 类型 | 可读 | 可写 | 说明 | 8151|--------|--------|------|------|---------------------------------------------------------------------------------| 8152| width | number | 是 | 是 | 输出的缩略图宽度。应保证大于0且不大于原始视频宽度。否则返回的缩略图不会进行缩放。 | 8153| height | number | 是 | 是 | 输出的缩略图高度。应保证大于0且不大于原始视频高度。否则返回的缩略图不会进行缩放。 | 8154 8155## OutputSize<sup>20+</sup> 8156 8157用于获取视频缩略图时，来定义输出图像大小。 8158 8159**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 8160 8161| 名称 | 类型 | 只读 | 可选 | 说明 | 8162| ------ | ------ | ---- | ---- | ------------------------------------------------------------ | 8163| width | number | 否 | 是 | 输出的缩略图宽度。<br/>- 如果该值小于0，宽度是视频的原始宽度。<br/>- 如果值为0或未分配任何值，缩放比例同高度比例。 | 8164| height | number | 否 | 是 | 输出的缩略图高度。<br/>- 如果该值小于0，高度是视频的原始高度。<br/>- 如果值为0或未分配任何值，缩放比例同宽度比例。 | 8165 8166## media.createMediaSourceWithUrl<sup>12+</sup> 8167 8168createMediaSourceWithUrl(url: string, headers?: Record\<string, string>): MediaSource 8169 8170创建流媒体预下载媒体来源实例方法。 8171 8172**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 8173 8174**系统能力：** SystemCapability.Multimedia.Media.Core 8175 8176**参数：** 8177 8178| 参数名 | 类型 | 必填 | 说明 | 8179| -------- | -------- | ---- | -------------------- | 8180| url | string | 是 | - 流媒体预下载媒体来源url，支持的流媒体格式：HLS、HTTP-FLV、Dash、Https。<br> - 本地m3u8的fd路径。 | 8181| headers | Record\<string, string> | 否 | 支持流媒体预下载HttpHeader自定义。 | 8182 8183**返回值：** 8184 8185| 类型 | 说明 | 8186| -------------- | ------------------------------------------ | 8187| [MediaSource](#mediasource12) | MediaSource返回值。 | 8188 8189**错误码：** 8190 8191以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 8192 8193| 错误码ID | 错误信息 | 8194| -------- | ----------------------------------------- | 8195| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 8196| 5400101 | No memory. | 8197 8198**示例1：** 8199 8200```ts 8201let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 8202let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 8203``` 8204 8205**示例2：** 8206 8207<!--code_no_check--> 8208```ts 8209import { common } from '@kit.AbilityKit'; 8210import { resourceManager } from '@kit.LocalizationKit'; 8211 8212private context: Context | undefined; 8213constructor(context: Context) { 8214 this.context = context; // this.getUIContext().getHostContext(); 8215} 8216let mgr = this.context.resourceManager; 8217let fileDescriptor = await mgr.getRawFd("xxx.m3u8"); 8218 8219let fd:string = fileDescriptor.fd.toString(); 8220let offset:string = fileDescriptor.offset.toString(); 8221let length:string = fileDescriptor.length.toString(); 8222let fdUrl:string = "fd://" + fd + "?offset=" + offset + "&size=" + length; 8223 8224let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 8225let mediaSource : media.MediaSource = media.createMediaSourceWithUrl(fdUrl, headers); 8226 8227let mimeType : media.AVMimeTypes = media.AVMimeTypes.APPLICATION_M3U8; 8228mediaSource.setMimeType(mimeType); 8229 8230``` 8231## media.createMediaSourceWithStreamData<sup>19+</sup> 8232 8233createMediaSourceWithStreamData(streams: Array\<MediaStream>): MediaSource 8234 8235创建流媒体多码率媒体来源实例方法，当前仅支持HTTP-FLV协议格式多码率。 8236 8237**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 8238 8239**系统能力：** SystemCapability.Multimedia.Media.Core 8240 8241**参数：** 8242 8243| 参数名 | 类型 | 必填 | 说明 | 8244| ------- | ------------------------------------ | ---- | ----------------------------------------------------- | 8245| streams | Array<[MediaStream](#mediastream19)> | 是 | 可设置MediaStream数组，支持的流媒体格式：HTTP-FLV。 | 8246 8247**返回值：** 8248 8249| 类型 | 说明 | 8250| ----------------------------- | ------------------- | 8251| [MediaSource](#mediasource12) | 返回MediaSource，用于媒体资源设置。 | 8252 8253**示例1：** 8254 8255```ts 8256let streams : Array<media.MediaStream> = []; 8257streams.push({url: "http://xxx/480p.flv", width: 854, height: 480, bitrate: 800000}); 8258streams.push({url: "http://xxx/720p.flv", width: 1280, height: 720, bitrate: 2000000}); 8259streams.push({url: "http://xxx/1080p.flv", width: 1280, height: 720, bitrate: 2000000}); 8260let mediaSource : media.MediaSource = media.createMediaSourceWithStreamData(streams); 8261``` 8262 8263## MediaStream<sup>19+</sup> 8264 8265媒体流数据信息。 8266 8267**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 8268 8269**系统能力：** SystemCapability.Multimedia.Media.Core 8270 8271| 名称 | 类型 | 只读 | 可选 | 说明 | 8272| ------- | ------ | ---- | ---- | ------------------------------------------------------------ | 8273| url | string | 否 | 否 | 媒体资源链接，当前仅支持http或者https。 | 8274| width | number | 否 | 否 | 媒体资源视频宽像素值。未知时可以填0，此时将无法通过[PlaybackStrategy](#playbackstrategy12)优选匹配。 | 8275| height | number | 否 | 否 | 媒体资源视频高像素值。未知时可以填0，此时将无法通过[PlaybackStrategy](#playbackstrategy12)优选匹配。 | 8276| bitrate | number | 否 | 否 | 媒体资源码率值，单位bps。 | 8277 8278## MediaSource<sup>12+</sup> 8279 8280媒体数据信息。来源自[createMediaSourceWithUrl](#mediacreatemediasourcewithurl12)。 8281 8282**系统能力：** SystemCapability.Multimedia.Media.Core 8283 8284### setMimeType<sup>12+</sup> 8285 8286setMimeType(mimeType: AVMimeTypes): void 8287 8288设置媒体MIME类型，以帮助播放器处理扩展的媒体源。 8289 8290**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 8291 8292**系统能力：** SystemCapability.Multimedia.Media.Core 8293 8294**参数：** 8295 8296| 参数名 | 类型 | 必填 | 说明 | 8297| -------- | -------- | ---- | -------------------- | 8298| mimeType | [AVMimeTypes](#mediasource12) | 是 | 媒体MIME类型。 | 8299 8300### setMediaResourceLoaderDelegate<sup>18+</sup> 8301 8302setMediaResourceLoaderDelegate(resourceLoader: MediaSourceLoader): void 8303 8304设置MediaSourceLoader，帮助播放器请求媒体数据。 8305 8306**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8307 8308**系统能力：** SystemCapability.Multimedia.Media.Core 8309 8310**参数：** 8311 8312| 参数名 | 类型 | 必填 | 说明 | 8313| -------- | -------- | ---- | -------------------- | 8314| resourceLoader | [MediaSourceLoader](#mediasourceloader18) | 是 | 应用实现的媒体数据获取接口，方便播放器获取数据。 | 8315 8316**示例：** 8317 8318```ts 8319import HashMap from '@ohos.util.HashMap'; 8320 8321let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 8322let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 8323let uuid: number = 1; 8324let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8325 8326let sourceOpenCallback: media.SourceOpenCallback = (request: media.MediaSourceLoadingRequest) => { 8327 console.log(`Opening resource: ${request.url}`); 8328 // 成功打开资源，返回唯一的句柄, 保证uuid和request对应。 8329 uuid += 1; 8330 requests.set(uuid, request); 8331 return uuid; 8332}; 8333 8334let sourceReadCallback: media.SourceReadCallback = (uuid: number, requestedOffset: number, requestedLength: number) => { 8335 console.log(`Reading resource with handle ${uuid}, offset: ${requestedOffset}, length: ${requestedLength}`); 8336 // 判断uuid是否合法、存储read请求，不要在read请求阻塞去推送数据和头信息。 8337}; 8338 8339let sourceCloseCallback: media.SourceCloseCallback = (uuid: number) => { 8340 console.log(`Closing resource with handle ${uuid}`); 8341 // 清除当前uuid相关资源。 8342 requests.remove(uuid); 8343}; 8344 8345// 应用按需实现。 8346let resourceLoader: media.MediaSourceLoader = { 8347 open: sourceOpenCallback, 8348 read: sourceReadCallback, 8349 close: sourceCloseCallback 8350}; 8351 8352mediaSource.setMediaResourceLoaderDelegate(resourceLoader); 8353``` 8354 8355## SourceOpenCallback<sup>18+</sup> 8356 8357type SourceOpenCallback = (request: MediaSourceLoadingRequest) => number 8358 8359由应用实现此回调函数，应用需处理传入的资源打开请求，并返回所打开资源对应的唯一句柄。 8360> 8361>**注意：** 客户端在处理完请求后应立刻返回。 8362> 8363 8364**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8365 8366**系统能力：** SystemCapability.Multimedia.Media.Core 8367 8368**参数：** 8369 8370| 参数名 | 类型 | 必填 | 说明 | 8371| -------- | -------- | ---- | -------------------- | 8372| request | [MediaSourceLoadingRequest](#mediasourceloadingrequest18) | 是 | 打开请求参数，包含请求资源的具体信息和数据推送方式。 | 8373 8374**返回值：** 8375 8376| 类型 | 说明 | 8377| -------- | -------------------- | 8378| number | 当前资源打开请求的句柄。大于0表示请求成功，小于或等于0表示请求失败。<br/> - request对象对应句柄唯一。| 8379 8380**示例：** 8381 8382```ts 8383import HashMap from '@ohos.util.HashMap'; 8384 8385let uuid: number = 1; 8386let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8387 8388let sourceOpenCallback: media.SourceOpenCallback = (request: media.MediaSourceLoadingRequest) => { 8389 console.log(`Opening resource: ${request.url}`); 8390 // 成功打开资源，返回唯一的句柄, 保证uuid和request对应。 8391 uuid += 1; 8392 requests.set(uuid, request); 8393 return uuid; 8394}; 8395``` 8396 8397## SourceReadCallback<sup>18+</sup> 8398 8399type SourceReadCallback = (uuid: number, requestedOffset: number, requestedLength: number) => void 8400 8401由应用实现此回调函数，应用需记录读取请求，并在数据充足时通过对应的MediaSourceLoadingRequest对象的[respondData](#responddata18)方法推送数据。 8402> 8403>**注意：** 客户端在处理完请求后应立刻返回。 8404> 8405 8406**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8407 8408**系统能力：** SystemCapability.Multimedia.Media.Core 8409 8410**参数：** 8411 8412| 参数名 | 类型 | 必填 | 说明 | 8413| -------- | -------- | ---- | -------------------- | 8414| uuid | number | 是 | 资源句柄的标识。 | 8415| requestedOffset | number | 是 | 当前媒体数据相对于资源起始位置的偏移量。 | 8416| requestedLength | number | 是 | 当前请求的长度。值为-1时，表示到达资源末尾，此时推送完成后需通过[finishLoading](#finishloading18)方法通知播放器推送结束。 | 8417 8418**示例：** 8419 8420```ts 8421let sourceReadCallback: media.SourceReadCallback = (uuid: number, requestedOffset: number, requestedLength: number) => { 8422 console.log(`Reading resource with handle ${uuid}, offset: ${requestedOffset}, length: ${requestedLength}`); 8423 // 判断uuid是否合法、存储read请求，不要在read请求阻塞去推送数据和头信息。 8424}; 8425``` 8426 8427## SourceCloseCallback<sup>18+</sup> 8428 8429type SourceCloseCallback = (uuid: number) => void 8430 8431由应用实现此回调函数，应用应释放相关资源。 8432> 8433>**注意：** 客户端在处理完请求后应立刻返回。 8434> 8435 8436**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8437 8438**系统能力：** SystemCapability.Multimedia.Media.Core 8439 8440**参数：** 8441 8442| 参数名 | 类型 | 必填 | 说明 | 8443| -------- | -------- | ---- | -------------------- | 8444| uuid | number | 是 | 资源句柄的标识。 | 8445 8446**示例：** 8447 8448```ts 8449import HashMap from '@ohos.util.HashMap'; 8450 8451let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8452 8453let sourceCloseCallback: media.SourceCloseCallback = (uuid: number) => { 8454 console.log(`Closing resource with handle ${uuid}`); 8455 // 清除当前uuid相关资源。 8456 requests.remove(uuid); 8457}; 8458``` 8459 8460## MediaSourceLoader<sup>18+</sup> 8461 8462用于定义媒体数据加载器，需要应用程序对其进行实现。 8463 8464**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8465 8466**系统能力：** SystemCapability.Multimedia.Media.Core 8467 8468| 名称 | 类型 | 必填 | 说明 | 8469| -------- | -------- | ---- | -------------------- | 8470| open | [SourceOpenCallback](#sourceopencallback18) | 是 | 由应用程序实现的回调函数，用于处理资源打开请求。 | 8471| read | [SourceReadCallback](#sourcereadcallback18) | 是 | 由应用程序实现的回调函数，用于处理资源读取请求。 | 8472| close | [SourceCloseCallback](#sourceclosecallback18) | 是 | 由应用程序实现的回调函数，用于处理资源关闭请求。 | 8473 8474**示例：** 8475 8476```ts 8477import HashMap from '@ohos.util.HashMap'; 8478 8479let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 8480let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 8481let uuid: number = 1; 8482let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8483let mediaSourceLoader: media.MediaSourceLoader = { 8484 open: (request: media.MediaSourceLoadingRequest) => { 8485 console.log(`Opening resource: ${request.url}`); 8486 // 成功打开资源，返回唯一的句柄, 保证uuid和request对应。 8487 uuid += 1; 8488 requests.set(uuid, request); 8489 return uuid; 8490 }, 8491 read: (uuid: number, requestedOffset: number, requestedLength: number) => { 8492 console.log(`Reading resource with handle ${uuid}, offset: ${requestedOffset}, length: ${requestedLength}`); 8493 // 判断uuid是否合法、存储read请求，不要在read请求阻塞去推送数据和头信息。 8494 }, 8495 close: (uuid: number) => { 8496 console.log(`Closing resource with handle ${uuid}`); 8497 // 清除当前uuid相关资源。 8498 requests.remove(uuid); 8499 } 8500}; 8501 8502mediaSource.setMediaResourceLoaderDelegate(mediaSourceLoader); 8503let playStrategy : media.PlaybackStrategy = { 8504 preferredBufferDuration: 20, 8505}; 8506 8507async function setupPlayer() { 8508 let player = await media.createAVPlayer(); 8509 player.setMediaSource(mediaSource, playStrategy); 8510} 8511``` 8512 8513## MediaSourceLoadingRequest<sup>18+</sup> 8514 8515用于定义加载请求的对象。应用程序通过该对象来获取请求的资源位置，通过该对象和播放器进行数据交互。 8516 8517**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8518 8519### 属性 8520 8521**系统能力：** SystemCapability.Multimedia.Media.Core 8522 8523| 名称 | 类型 | 只读 | 可选 | 说明 | 8524| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 8525| url | string | 否 | 否 | 资源url，需要应用程序打开的资源路径。 | 8526| header | Record<string, string> | 否 | 是 | 网络请求标头，如果存在需要应用在下载数据是将头信息设置到http请求中。 | 8527 8528### respondData<sup>18+</sup> 8529 8530respondData(uuid: number, offset: number, buffer: ArrayBuffer): number 8531 8532用于应用程序向播放器发送数据。 8533 8534**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8535 8536**系统能力：** SystemCapability.Multimedia.Media.Core 8537 8538**参数：** 8539 8540| 参数名 | 类型 | 必填 | 说明 | 8541| -------- | -------- | ---- | -------------------- | 8542| uuid | number | 是 | 资源句柄的标识。 | 8543| offset | number | 是 | 当前媒体数据相对于资源起始位置的偏移量。 | 8544| buffer | ArrayBuffer | 是 | 响应播放器的媒体数据。<br/>**注意：** 不要传输无关数据，会影响正常数据解析和播放。 | 8545 8546**返回值：** 8547 8548| 类型 | 说明 | 8549| -------------- | ----------------------------------- | 8550| number | 当前服务端接受的字节数。<br>- 返回值小于0表示操作失败。<br>- 返回值为-2时，表示播放器不再需要当前数据，客户端应停止当前读取过程。<br>- 返回值为-3时，表示播放器的缓冲区已满，客户端应等待下一次读取。 | 8551 8552**示例：** 8553 8554```ts 8555import HashMap from '@ohos.util.HashMap'; 8556let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8557let uuid = 1; 8558 8559let request = requests.get(uuid); 8560let offset = 0; // 当前媒体数据相对于资源起始位置的偏移量 8561let buf = new ArrayBuffer(0); // 由应用定义，推送给播放器的数据 8562let num = request.respondData(uuid, offset, buf); 8563``` 8564 8565### respondHeader<sup>18+</sup> 8566 8567respondHeader(uuid: number, header?: Record<string, string>, redirectUrl?: string): void 8568 8569用于应用程序向播放器发送响应头信息，应在第一次调用[respondData](#responddata18)方法之前调用。 8570 8571**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8572 8573**系统能力：** SystemCapability.Multimedia.Media.Core 8574 8575**参数：** 8576 8577| 参数名 | 类型 | 必填 | 说明 | 8578| -------- | -------- | ---- | -------------------- | 8579| uuid | number | 是 | 资源句柄的标识。 | 8580| header | Record<string, string> | 否 | HTTP响应中的头部信息。应用可将头部信息字段与底层支持解析字段取交集传递或直接传入对应的所有头部信息。<br> - 底层播放需要解析的字段包括Transfer-Encoding、Location、Content-Type、Content-Range、Content-Encode、Accept-Ranges、content-length。 | 8581| redirectUrl | string | 否 | 如果存在，为HTTP响应中的重定向URL。 | 8582 8583**示例：** 8584 8585```ts 8586import HashMap from '@ohos.util.HashMap'; 8587let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8588let uuid = 1; 8589 8590// 应用根据情况填充。 8591let header:Record<string, string> = { 8592 'Transfer-Encoding':'xxx', 8593 'Location' : 'xxx', 8594 'Content-Type' : 'xxx', 8595 'Content-Range' : 'xxx', 8596 'Content-Encode' : 'xxx', 8597 'Accept-Ranges' : 'xxx', 8598 'content-length' : 'xxx' 8599}; 8600let request = requests.get(uuid); 8601request.respondHeader(uuid, header); 8602``` 8603 8604### finishLoading<sup>18+</sup> 8605 8606finishLoading(uuid: number, state: LoadingRequestError): void 8607 8608应用程序用于通知播放器当前请求状态的接口。针对服务侧请求的单个资源，推送完全部资源后需要发送LOADING_ERROR_SUCCESS状态告知该资源推送结束。 8609 8610**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8611 8612**系统能力：** SystemCapability.Multimedia.Media.Core 8613 8614**参数：** 8615 8616| 参数名 | 类型 | 必填 | 说明 | 8617| -------- | -------- | ---- | -------------------- | 8618| uuid | number | 是 | 资源句柄的标识。 | 8619| state | [LoadingRequestError](#loadingrequesterror18) | 是 | 请求的状态。 | 8620 8621**示例：** 8622 8623```ts 8624import HashMap from '@ohos.util.HashMap'; 8625let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8626let uuid = 1; 8627 8628let request = requests.get(uuid); 8629let loadingError = media.LoadingRequestError.LOADING_ERROR_SUCCESS; 8630request.finishLoading(uuid, loadingError); 8631``` 8632 8633## LoadingRequestError<sup>18+</sup> 8634 8635枚举，数据加载过程中状态变化的原因。 8636 8637**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8638 8639**系统能力：** SystemCapability.Multimedia.Media.Core 8640 8641| 名称 | 值 | 说明 | 8642| -------------------- | ---- | ------------------------------ | 8643| LOADING_ERROR_SUCCESS | 0 | 由客户端返回，表示已经推送到资源末尾。 | 8644| LOADING_ERROR_NOT_READY | 1 | 由客户端返回，表示资源尚未准备好可供访问。| 8645| LOADING_ERROR_NO_RESOURCE | 2 | 由客户端返回，表示请求的资源URL不存在。 | 8646| LOADING_ERROR_INVAID_HANDLE | 3 | 由客户端返回，表示请求的资源句柄uuid无效。 | 8647| LOADING_ERROR_ACCESS_DENIED | 4 | 由客户端返回，表示客户端没有权限请求该资源。 | 8648| LOADING_ERROR_ACCESS_TIMEOUT | 5 | 由客户端返回，表示访问资源过程超时。 | 8649| LOADING_ERROR_AUTHORIZE_FAILED | 6 | 由客户端返回，表示授权失败。 | 8650 8651## AVMimeTypes<sup>12+</sup> 8652 8653媒体MIME类型，通过[setMimeType](#setmimetype12)设置。 8654 8655**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 8656 8657**系统能力：** SystemCapability.Multimedia.Media.Core 8658 8659 8660| 名称 | 值 | 说明 | 8661| ---------- | ---- | ------------------------------------------------------------ | 8662| APPLICATION_M3U8 | application/m3u8 | 表示m3u8本地文件。 | 8663 8664 8665## PlaybackStrategy<sup>12+</sup> 8666 8667播放策略。 8668 8669**系统能力：** SystemCapability.Multimedia.Media.Core 8670 8671| 名称 | 类型 | 必填 | 说明 | 8672| -------- | -------- | ---- | -------------------- | 8673| preferredWidth| number | 否 | 播放策略首选宽度，设置范围为大于0的整数，如1080，单位为像素（px）。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 8674| preferredHeight | number | 否 | 播放策略首选高度，设置范围为大于0的整数，如1920，单位为像素（px）。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 8675| preferredBufferDuration | number | 否 | 播放策略首选缓冲持续时间，单位s，取值范围1-20。<br>具体使用方式可参考[在线视频播放卡顿优化实践](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-online-video-playback-lags-practice)。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 8676| preferredHdr | boolean | 否 | 播放策略true是hdr，false非hdr，默认非hdr。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 8677| enableSuperResolution<sup>18+</sup> | boolean | 否 | 表示是否使能超分功能。true表示使能超分，false表示不使能超分，默认为false。<br>若不使能超分，则后续不能调用超分相关接口。若使能超分，则超分功能默认开启，默认目标分辨率为1920x1080，单位为像素。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 8678| showFirstFrameOnPrepare<sup>17+</sup> | boolean | 否 | 播放策略true是Prepare之后显示视频起播首帧，false是Prepare之后不显示视频起播首帧，默认不显示。<br>**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 | 8679| mutedMediaType | [MediaType](#mediatype8) | 否 | 静音播放的媒体类型，仅支持设置 MediaType.MEDIA_TYPE_AUD。 | 8680| preferredAudioLanguage<sup>13+</sup> | string | 否 | 播放策略首选音轨语言。dash场景下应用可按需设置。非dash场景暂不支持，建议缺省。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 8681| preferredSubtitleLanguage<sup>13+</sup> | string | 否 | 播放策略首选字幕语言。dash场景下应用可按需设置。非dash场景暂不支持，建议缺省。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 8682| preferredBufferDurationForPlaying<sup>18+</sup> | number | 否 | 播放策略首选起播缓冲水线。当起播缓冲时间超过该值，开始播放。单位s，取值范围0-20。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 8683| thresholdForAutoQuickPlay<sup>18+</sup> | number | 否 | 智能追帧水线，单位为s，取值应不小于2s，且需大于起播缓冲水线，默认设置为5s。<br>播放策略可以通过设置智能追帧水线来保证直播的实时性。flv直播场景下应用可按需设置，非flv直播场景暂不支持。网络状态的变化可能会导致播放器在某段时间内积压大量数据。播放器会定期检查当前播放时间与缓存中最新的帧时间戳之间的差值，当这个差值过大时，播放器将以1.2倍速开始智能追帧。[speedDone事件](#onspeeddone9)会回调特定值100，表示智能追帧开启成功。当差值小于起播缓冲水线时，则停止追帧并恢复到正常播放速度。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 8684 8685## AVScreenCaptureRecordPreset<sup>12+</sup> 8686 8687进行屏幕录制时的编码、封装格式参数的枚举。 8688 8689**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8690 8691| 名称 | 值 | 说明 | 8692| --------------------------------- | ---- | -------------------------------------------- | 8693| SCREEN_RECORD_PRESET_H264_AAC_MP4 | 0 | 使用视频H264编码，音频AAC编码，MP4封装格式。 | 8694| SCREEN_RECORD_PRESET_H265_AAC_MP4 | 1 | 使用视频H265编码，音频AAC编码，MP4封装格式。 | 8695 8696## AVScreenCaptureStateCode<sup>12+</sup> 8697 8698屏幕录制的状态回调。 8699 8700**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8701 8702| 名称 | 值 | 说明 | 8703| ---------------------------------------- | ---- | ------------------------ | 8704| SCREENCAPTURE_STATE_STARTED | 0 | 录屏已开始。 | 8705| SCREENCAPTURE_STATE_CANCELED | 1 | 录屏被取消。 | 8706| SCREENCAPTURE_STATE_STOPPED_BY_USER | 2 | 录屏被用户手动停止。 | 8707| SCREENCAPTURE_STATE_INTERRUPTED_BY_OTHER | 3 | 录屏被其他录屏打断。 | 8708| SCREENCAPTURE_STATE_STOPPED_BY_CALL | 4 | 录屏被来电打断。 | 8709| SCREENCAPTURE_STATE_MIC_UNAVAILABLE | 5 | 录屏无法使用麦克风收音。 | 8710| SCREENCAPTURE_STATE_MIC_MUTED_BY_USER | 6 | 麦克风被用户关闭。 | 8711| SCREENCAPTURE_STATE_MIC_UNMUTED_BY_USER | 7 | 麦克风被用户打开。 | 8712| SCREENCAPTURE_STATE_ENTER_PRIVATE_SCENE | 8 | 录屏进入隐私页面。 | 8713| SCREENCAPTURE_STATE_EXIT_PRIVATE_SCENE | 9 | 录屏退出隐私页面。 | 8714| SCREENCAPTURE_STATE_STOPPED_BY_USER_SWITCHES | 10 | 系统用户切换，录屏中断。 | 8715 8716## AVScreenCaptureFillMode<sup>18+</sup> 8717 8718进行屏幕录制时视频填充模式的枚举。 8719 8720**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8721 8722| 名称 | 值 | 说明 | 8723| --------------------------------- | ---- | -------------------------------------------- | 8724| PRESERVE_ASPECT_RATIO | 0 | 保持与原始图像相同的宽高比例，即与物理屏幕宽高比例一致。 | 8725| SCALE_TO_FILL | 1 | 进行图像拉伸填充，适配设置的宽度和高度。 | 8726 8727## AVScreenCaptureStrategy<sup>20+</sup> 8728 8729录屏策略。 8730 8731**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8732 8733| 名称 | 类型 | 必填 | 说明 | 8734| --------------------- | ------- | --- | -------------------- | 8735| keepCaptureDuringCall | boolean | 否 | 蜂窝通话时是否保持录屏。 | 8736 8737## AVScreenCaptureRecordConfig<sup>12+</sup> 8738 8739表示录屏参数配置。 8740 8741**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8742 8743| 名称 | 类型 | 必填 | 说明 | 8744| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 8745| fd | number | 是 | 录制输出的文件fd。 | 8746| frameWidth | number | 否 | 录屏的视频宽度，默认屏幕宽度，根据不同屏幕默认值不同，单位px。 | 8747| frameHeight | number | 否 | 录屏的视频高度，默认屏幕高度，根据不同屏幕默认值不同，单位px。 | 8748| videoBitrate | number | 否 | 录屏的视频比特率，默认10000000。 | 8749| audioSampleRate | number | 否 | 录屏的音频采样率，内录的系统音和外录的麦克风都是用此采样率，默认48000，仅支持设置48000或16000。 | 8750| audioChannelCount | number | 否 | 录屏的音频通道数，内录的系统音和外录的麦克风都是用此通道数，默认2声道，仅支持设置1或2声道。 | 8751| audioBitrate | number | 否 | 录屏的音频比特率，内录的系统音和外录的麦克风都是用此比特率，默认96000。 | 8752| preset | [AVScreenCaptureRecordPreset](#avscreencapturerecordpreset12) | 否 | 录屏使用的编码和封装格式，默认SCREEN_RECORD_PRESET_H264_AAC_MP4格式。 | 8753| displayId<sup>15+</sup> | number | 否 | 指定录屏使用的屏幕，默认主屏幕。 | 8754| fillMode<sup>18+</sup> | [AVScreenCaptureFillMode](#avscreencapturefillmode18)| 否 | 录屏时视频流的填充模式。 | 8755| strategy<sup>20+</sup> | [AVScreenCaptureStrategy](#avscreencapturestrategy20)| 否 | 录屏策略。 | 8756 8757## AVScreenCaptureRecorder<sup>12+</sup> 8758 8759屏幕录制管理类，用于进行屏幕录制。在调用AVScreenCaptureRecorder的方法前，需要先通过[createAVScreenCaptureRecorder()](#mediacreateavscreencapturerecorder12)创建一个AVScreenCaptureRecorder实例。 8760 8761### init<sup>12+</sup> 8762 8763init(config: AVScreenCaptureRecordConfig): Promise\<void> 8764 8765异步方式进行录屏初始化，设置录屏参数。通过Promise获取返回值。 8766 8767**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8768 8769**参数：** 8770 8771| 参数名 | 类型 | 必填 | 说明 | 8772| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 8773| config | [AVScreenCaptureRecordConfig](#avscreencapturerecordconfig12) | 是 | 配置屏幕录制的相关参数。 | 8774 8775**返回值：** 8776 8777| 类型 | 说明 | 8778| -------------- | ----------------------------------- | 8779| Promise\<void> | 异步录屏初始化方法的Promise返回值。 | 8780 8781**错误码：** 8782 8783| 错误码ID | 错误信息 | 8784| -------- | ---------------------------------------------- | 8785| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 8786| 5400103 | IO error. Return by promise. | 8787| 5400105 | Service died. Return by promise. | 8788 8789**示例：** 8790 8791```ts 8792import { BusinessError } from '@kit.BasicServicesKit'; 8793 8794let avCaptureConfig: media.AVScreenCaptureRecordConfig = { 8795 fd: 0, // 文件需要先有调用者创建，赋予写权限，将文件fd传给此参数。 8796 frameWidth: 640, 8797 frameHeight: 480 8798 // 补充其他参数。 8799}; 8800 8801avScreenCaptureRecorder.init(avCaptureConfig).then(() => { 8802 console.info('Succeeded in initing avScreenCaptureRecorder'); 8803}).catch((err: BusinessError) => { 8804 console.info('Failed to init avScreenCaptureRecorder, error: ' + err.message); 8805}); 8806``` 8807 8808### startRecording<sup>12+</sup> 8809 8810startRecording(): Promise\<void> 8811 8812异步方式开始录屏。通过Promise获取返回值。 8813 8814**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8815 8816**返回值：** 8817 8818| 类型 | 说明 | 8819| -------------- | -------------------------------- | 8820| Promise\<void> | 异步开始录屏方法的Promise返回值. | 8821 8822**错误码：** 8823 8824| 错误码ID | 错误信息 | 8825| -------- | -------------------------------- | 8826| 5400103 | IO error. Return by promise. | 8827| 5400105 | Service died. Return by promise. | 8828 8829**示例：** 8830 8831```ts 8832import { BusinessError } from '@kit.BasicServicesKit'; 8833 8834avScreenCaptureRecorder.startRecording().then(() => { 8835 console.info('Succeeded in starting avScreenCaptureRecorder'); 8836}).catch((err: BusinessError) => { 8837 console.info('Failed to start avScreenCaptureRecorder, error: ' + err.message); 8838}); 8839``` 8840 8841### stopRecording<sup>12+</sup> 8842 8843stopRecording(): Promise\<void> 8844 8845异步方式结束录屏。通过Promise获取返回值。 8846 8847**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8848 8849**返回值：** 8850 8851| 类型 | 说明 | 8852| -------------- | --------------------------------- | 8853| Promise\<void> | 异步结束录屏方法的Promise返回值。 | 8854 8855**错误码：** 8856 8857| 错误码ID | 错误信息 | 8858| -------- | -------------------------------- | 8859| 5400103 | IO error. Return by promise. | 8860| 5400105 | Service died. Return by promise. | 8861 8862**示例：** 8863 8864```ts 8865import { BusinessError } from '@kit.BasicServicesKit'; 8866 8867avScreenCaptureRecorder.stopRecording().then(() => { 8868 console.info('Succeeded in stopping avScreenCaptureRecorder'); 8869}).catch((err: BusinessError) => { 8870 console.info('Failed to stop avScreenCaptureRecorder, error: ' + err.message); 8871}); 8872``` 8873 8874### skipPrivacyMode<sup>12+</sup> 8875 8876skipPrivacyMode(windowIDs: Array\<number>): Promise\<void> 8877 8878录屏时，应用可对本应用的隐私窗口做安全豁免。通过Promise获取返回值。 8879如录屏时，用户在本应用进行输入密码等操作，应用不会进行黑屏处理。 8880 8881**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8882 8883**参数：** 8884 8885| 参数名 | 类型 | 必填 | 说明 | 8886| ------ | ------- | ---- | --------------------------------------------------------- | 8887| windowIDs | Array\<number> | 是 | 需要豁免隐私的窗口列表，包括主窗口id和子窗口id，窗口属性获取方法可以参考[窗口API引用](../apis-arkui/arkts-apis-window-Window.md#getwindowproperties9)。 | 8888 8889**返回值：** 8890 8891| 类型 | 说明 | 8892| -------------- | -------------------------------- | 8893| Promise\<void> | 豁免隐私窗口的Promise返回值. | 8894 8895**错误码：** 8896 8897| 错误码ID | 错误信息 | 8898| -------- | -------------------------------- | 8899| 5400103 | IO error. Return by promise. | 8900| 5400105 | Service died. Return by promise. | 8901 8902**示例：** 8903 8904```ts 8905import { BusinessError } from '@kit.BasicServicesKit'; 8906 8907let windowIDs = []; 8908avScreenCaptureRecorder.skipPrivacyMode(windowIDs).then(() => { 8909 console.info('Succeeded in skipping privacy mode'); 8910}).catch((err: BusinessError) => { 8911 console.info('Failed to skip privacy mode, error: ' + err.message); 8912}); 8913``` 8914 8915### setMicEnabled<sup>12+</sup> 8916 8917setMicEnabled(enable: boolean): Promise\<void> 8918 8919异步方式设置麦克风开关。通过Promise获取返回值。 8920 8921**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8922 8923**参数：** 8924 8925| 参数名 | 类型 | 必填 | 说明 | 8926| ------ | ------- | ---- | --------------------------------------------------------- | 8927| enable | boolean | 是 | 麦克风开关控制，true代表麦克风打开，false代表麦克风关闭。 | 8928 8929**返回值：** 8930 8931| 类型 | 说明 | 8932| -------------- | --------------------------------------- | 8933| Promise\<void> | 异步设置麦克风开关方法的Promise返回值。 | 8934 8935**错误码：** 8936 8937| 错误码ID | 错误信息 | 8938| -------- | -------------------------------- | 8939| 5400103 | IO error. Return by promise. | 8940| 5400105 | Service died. Return by promise. | 8941 8942**示例：** 8943 8944```ts 8945import { BusinessError } from '@kit.BasicServicesKit'; 8946 8947avScreenCaptureRecorder.setMicEnabled(true).then(() => { 8948 console.info('Succeeded in setMicEnabled avScreenCaptureRecorder'); 8949}).catch((err: BusinessError) => { 8950 console.info('Failed to setMicEnabled avScreenCaptureRecorder, error: ' + err.message); 8951}); 8952``` 8953 8954### release<sup>12+</sup> 8955 8956release(): Promise\<void> 8957 8958异步方式释放录屏。通过Promise获取返回值。 8959 8960**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8961 8962**返回值：** 8963 8964| 类型 | 说明 | 8965| -------------- | --------------------------------- | 8966| Promise\<void> | 异步释放录屏方法的Promise返回值。 | 8967 8968**错误码：** 8969 8970| 错误码ID | 错误信息 | 8971| -------- | -------------------------------- | 8972| 5400103 | IO error. Return by promise. | 8973| 5400105 | Service died. Return by promise. | 8974 8975**示例：** 8976 8977```ts 8978import { BusinessError } from '@kit.BasicServicesKit'; 8979 8980avScreenCaptureRecorder.release().then(() => { 8981 console.info('Succeeded in releasing avScreenCaptureRecorder'); 8982}).catch((err: BusinessError) => { 8983 console.info('Faile to release avScreenCaptureRecorder, error: ' + err.message); 8984}); 8985``` 8986 8987### on('stateChange')<sup>12+</sup> 8988 8989on(type: 'stateChange', callback: Callback\<AVScreenCaptureStateCode>): void 8990 8991订阅录屏状态切换的事件，当状态发生的时候，会通过订阅的回调通知用户。用户只能订阅一个状态切换的回调方法，重复订阅时，以最后一次订阅的回调接口为准。 8992 8993**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8994 8995**参数：** 8996 8997| 参数名 | 类型 | 必填 | 说明 | 8998| -------- | -------- | ---- | ------------------------------------------------------------ | 8999| type | string | 是 | 状态切换事件回调类型，支持的事件：'stateChange'。 | 9000| callback | function | 是 | 状态切换事件回调方法，[AVScreenCaptureStateCode](#avscreencapturestatecode12)表示切换到的状态。 | 9001 9002**示例：** 9003 9004```ts 9005avScreenCaptureRecorder.on('stateChange', (state: media.AVScreenCaptureStateCode) => { 9006 console.info('avScreenCaptureRecorder stateChange to ' + state); 9007}); 9008``` 9009 9010### on('error')<sup>12+</sup> 9011 9012on(type: 'error', callback: ErrorCallback): void 9013 9014订阅AVScreenCaptureRecorder的错误事件，用户可以根据应用自身逻辑对错误事件进行处理。用户只能订阅一个错误事件的回调方法，重复订阅时，以最后一次订阅的回调接口为准。 9015 9016**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 9017 9018**参数：** 9019 9020| 参数名 | 类型 | 必填 | 说明 | 9021| -------- | ------------- | ---- | --------------------------------------- | 9022| type | string | 是 | 错误事件回调类型，支持的事件：'error'。 | 9023| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录屏错误事件回调方法。 | 9024 9025**错误码：** 9026 9027| 错误码ID | 错误信息 | 9028| -------- | -------------------------------- | 9029| 201 | permission denied. | 9030| 5400103 | IO error. Return by ErrorCallback. | 9031| 5400105 | Service died. Return by ErrorCallback. | 9032 9033**示例：** 9034 9035```ts 9036avScreenCaptureRecorder.on('error', (err: BusinessError) => { 9037 console.error('avScreenCaptureRecorder error:' + err.message); 9038}); 9039``` 9040 9041### off('stateChange')<sup>12+</sup> 9042 9043 off(type: 'stateChange', callback?: Callback\<AVScreenCaptureStateCode>): void 9044 9045取消订阅状态切换回调事件。用户可以指定填入状态切换的回调方法来取消订阅。 9046 9047**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 9048 9049**参数：** 9050 9051| 参数名 | 类型 | 必填 | 说明 | 9052| -------- | -------- | ---- | ------------------------------------------------------------ | 9053| type | string | 是 | 状态切换事件回调类型，支持的事件：'stateChange'。 | 9054| callback | function | 否 | 状态切换事件回调方法，[AVScreenCaptureStateCode](#avscreencapturestatecode12)表示切换到的状态，不填此参数则会取消最后一次订阅事件。 | 9055 9056**示例：** 9057 9058```ts 9059avScreenCaptureRecorder.off('stateChange'); 9060``` 9061 9062### off('error')<sup>12+</sup> 9063 9064off(type: 'error', callback?: ErrorCallback): void 9065 9066取消订阅错误回调事件。用户可以指定填入错误回调方法来取消订阅。 9067 9068**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 9069 9070**参数：** 9071 9072| 参数名 | 类型 | 必填 | 说明 | 9073| -------- | -------- | ---- | ---------------------------------------------------------- | 9074| type | string | 是 | 状态切换事件回调类型，支持的事件：'error'。 | 9075| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 录屏错误事件回调方法，不填此参数则会取消最后一次订阅事件。 | 9076 9077**示例：** 9078 9079```ts 9080avScreenCaptureRecorder.off('error'); 9081```
