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以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 301 302| 错误码ID | 错误信息 | 303| -------- | ------------------------------ | 304| 5400101 | No memory. Returned by promise. | 305 306**示例：** 307 308```ts 309import { BusinessError } from '@kit.BasicServicesKit'; 310 311let avMetadataExtractor: media.AVMetadataExtractor; 312media.createAVMetadataExtractor().then((extractor: media.AVMetadataExtractor) => { 313 if (extractor != null) { 314 avMetadataExtractor = extractor; 315 console.info('Succeeded in creating AVMetadataExtractor'); 316 } else { 317 console.error(`Failed to create AVMetadataExtractor`); 318 } 319}).catch((error: BusinessError) => { 320 console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`); 321}); 322``` 323 324## media.createSoundPool<sup>10+</sup> 325 326createSoundPool(maxStreams: number, audioRenderInfo: audio.AudioRendererInfo, callback: AsyncCallback\<SoundPool>): void 327 328创建音频池实例，使用callback方式异步获取返回值。 329 330> **说明：** 331> 332> - API 18以下版本，创建的SoundPool对象底层为单实例模式，一个应用进程只能够创建1个SoundPool实例。 333> - API 18及API 18以上版本，创建的SoundPool对象底层为多实例模式，一个应用进程最多能够创建128个SoundPool实例。 334 335**系统能力：** SystemCapability.Multimedia.Media.SoundPool 336 337**参数：** 338 339| 参数名 | 类型 | 必填 | 说明 | 340| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 341| maxStreams | number | 是 | soundPool实例的最大播放的流数，设置范围为1-32的正整数。 | 342| 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播放短音时为混音模式，不会打断其他音频播放。 | 343| callback | AsyncCallback<[SoundPool](js-apis-inner-multimedia-soundPool.md)> | 是 | 回调函数。异步返回SoundPool实例，失败时返回null。用于音频池实例的加载播放功能。 | 344 345**错误码：** 346 347以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 348 349| 错误码ID | 错误信息 | 350| -------- | ------------------------------ | 351| 5400101 | No memory. Return by callback. | 352 353**示例：** 354 355```js 356import { audio } from '@kit.AudioKit'; 357 358let soundPool: media.SoundPool; 359let audioRendererInfo: audio.AudioRendererInfo = { 360 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 361 rendererFlags : 0 362} 363 364media.createSoundPool(5, audioRendererInfo, (error, soundPool_: media.SoundPool) => { 365 if (error) { 366 console.error(`Failed to createSoundPool`) 367 return; 368 } else { 369 soundPool = soundPool_; 370 console.info(`Succeeded in createSoundPool`) 371 } 372}); 373``` 374 375## media.createSoundPool<sup>10+</sup> 376 377createSoundPool(maxStreams: number, audioRenderInfo: audio.AudioRendererInfo): Promise\<SoundPool> 378 379创建音频池实例，通过Promise获取返回值。 380 381> **说明：** 382> 383> - API 18以下版本，创建的SoundPool对象底层为单实例模式，一个应用进程只能够创建1个SoundPool实例。 384> - API 18及API 18以上版本，创建的SoundPool对象底层为多实例模式，一个应用进程最多能够创建128个SoundPool实例。 385 386**系统能力：** SystemCapability.Multimedia.Media.SoundPool 387 388**参数：** 389 390| 参数名 | 类型 | 必填 | 说明 | 391| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 392| maxStreams | number | 是 | soundPool实例的最大播放的流数，设置范围为1-32的正整数。 | 393| audioRenderInfo | [audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8) | 是 | 音频播放参数信息 | 394 395**返回值：** 396 397| 类型 | 说明 | 398| ----------------------------------------- | ------------------------------------------------------------ | 399| Promise<[SoundPool](js-apis-inner-multimedia-soundPool.md)> | Promise对象。异步返回SoundPool实例，失败时返回null。用于音频池实例的加载播放功能。 | 400 401**错误码：** 402 403以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 404 405| 错误码ID | 错误信息 | 406| -------- | ----------------------------- | 407| 5400101 | No memory. Return by promise. | 408 409**示例：** 410 411```js 412import { audio } from '@kit.AudioKit'; 413import { BusinessError } from '@kit.BasicServicesKit'; 414 415let soundPool: media.SoundPool; 416let audioRendererInfo: audio.AudioRendererInfo = { 417 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 418 rendererFlags : 0 419} 420 421media.createSoundPool(5, audioRendererInfo).then((soundpool_: media.SoundPool) => { 422 if (soundpool_ != null) { 423 soundPool = soundpool_; 424 console.info('Succceeded in creating SoundPool'); 425 } else { 426 console.error('Failed to create SoundPool'); 427 } 428}, (error: BusinessError) => { 429 console.error(`soundpool catchCallback, error message:${error.message}`); 430}); 431``` 432 433## media.createAVScreenCaptureRecorder<sup>12+</sup> 434 435createAVScreenCaptureRecorder(): Promise\<AVScreenCaptureRecorder> 436 437创建屏幕录制实例，通过Promise获取返回值。 438 439**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 440 441**返回值：** 442 443| 类型 | 说明 | 444| ------------------------------------------------------------ | ------------------------------------------------------------ | 445| Promise\<[AVScreenCaptureRecorder](#avscreencapturerecorder12)> | Promise对象。异步返回AVScreenCaptureRecorder实例，失败时返回null。可用于进行屏幕录制。 | 446 447**错误码：** 448 449| 错误码ID | 错误信息 | 450| -------- | ------------------------------ | 451| 5400101 | No memory. Return by promise. | 452 453**示例：** 454 455```ts 456import { BusinessError } from '@kit.BasicServicesKit'; 457 458let avScreenCaptureRecorder: media.AVScreenCaptureRecorder; 459media.createAVScreenCaptureRecorder().then((captureRecorder: media.AVScreenCaptureRecorder) => { 460 if (captureRecorder != null) { 461 avScreenCaptureRecorder = captureRecorder; 462 console.info('Succeeded in createAVScreenCaptureRecorder'); 463 } else { 464 console.error('Failed to createAVScreenCaptureRecorder'); 465 } 466}).catch((error: BusinessError) => { 467 console.error(`createAVScreenCaptureRecorder catchCallback, error message:${error.message}`); 468}); 469``` 470 471## SoundPool<sup>10+</sup> 472 473type SoundPool = _SoundPool 474 475音频池，提供了系统声音的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能。 476 477**系统能力：** SystemCapability.Multimedia.Media.SoundPool 478 479| 类型 | 说明 | 480| -------- | ------------------------------ | 481| [_SoundPool](js-apis-inner-multimedia-soundPool.md#soundpool) | 音频池，提供了系统声音的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能。 | 482 483## PlayParameters<sup>10+</sup> 484 485type PlayParameters = _PlayParameters 486 487表示音频池播放参数设置。 488 489**系统能力：** SystemCapability.Multimedia.Media.SoundPool 490 491| 类型 | 说明 | 492| -------- | ------------------------------ | 493| [_PlayParameters](js-apis-inner-multimedia-soundPool.md#playparameters) | 表示音频池播放参数设置。 | 494 495## AVErrorCode<sup>9+</sup> 496 497[媒体错误码](errorcode-media.md)类型枚举 498 499**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 500 501**系统能力：** SystemCapability.Multimedia.Media.Core 502 503| 名称 | 值 | 说明 | 504| :------------------------------------ | ------- | ------------------------------------ | 505| AVERR_OK | 0 | 表示操作成功。 | 506| AVERR_NO_PERMISSION | 201 | 表示无权限执行此操作。 | 507| AVERR_INVALID_PARAMETER | 401 | 表示传入入参无效。 | 508| AVERR_UNSUPPORT_CAPABILITY | 801 | 表示当前版本不支持该API能力。 | 509| AVERR_NO_MEMORY | 5400101 | 表示系统内存不足或服务数量达到上限。 | 510| AVERR_OPERATE_NOT_PERMIT | 5400102 | 表示当前状态不允许或无权执行此操作。 | 511| AVERR_IO | 5400103 | 表示数据流异常信息。 | 512| AVERR_TIMEOUT | 5400104 | 表示系统或网络响应超时。 | 513| AVERR_SERVICE_DIED | 5400105 | 表示服务进程死亡。 | 514| AVERR_UNSUPPORT_FORMAT | 5400106 | 表示不支持当前媒体资源的格式。 | 515| AVERR_AUDIO_INTERRUPTED<sup>11+</sup> | 5400107 | 表示音频焦点被抢占 | 516| AVERR_IO_HOST_NOT_FOUND<sup>14+</sup> | 5411001 | 表示解析或链接服务端地址错误。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 517| AVERR_IO_CONNECTION_TIMEOUT<sup>14+</sup> | 5411002 | 表示网络连接超时。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 518| AVERR_IO_NETWORK_ABNORMAL<sup>14+</sup> | 5411003 | 表示网络异常导致的数据或链路异常。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 519| AVERR_IO_NETWORK_UNAVAILABLE<sup>14+</sup> | 5411004 | 表示网络被禁用。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 520| AVERR_IO_NO_PERMISSION<sup>14+</sup> | 5411005 | 表示无访问权限。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 521| AVERR_IO_REQUEST_DENIED<sup>14+</sup> | 5411006 | 表示客户端请求参数错误或超出处理能力。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 522| AVERR_IO_RESOURCE_NOT_FOUND<sup>14+</sup> | 5411007 | 表示无可用网络资源。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 523| AVERR_IO_SSL_CLIENT_CERT_NEEDED<sup>14+</sup> | 5411008 | 表示服务端校验客户端证书失败。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 524| AVERR_IO_SSL_CONNECTION_FAILED<sup>14+</sup> | 5411009 | 表示SSL连接失败。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 525| AVERR_IO_SSL_SERVER_CERT_UNTRUSTED<sup>14+</sup> | 5411010 | 表示客户端校验服务端证书失败。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 526| AVERR_IO_UNSUPPORTED_REQUEST<sup>14+</sup> | 5411011 | 表示网络协议的原因导致请求不受支持。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 527| AVERR_SEEK_CONTINUOUS_UNSUPPORTED<sup>18+</sup> | 5410002 | 表示不支持SEEK_CONTINUOUS模式的seek。 <br> **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 528| AVERR_SUPER_RESOLUTION_UNSUPPORTED<sup>18+</sup> | 5410003 | 表示不支持超分。 <br> **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 529| AVERR_SUPER_RESOLUTION_NOT_ENABLED<sup>18+</sup> | 5410004 | 表示未使能超分。 <br> **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 530 531## MediaType<sup>8+</sup> 532 533媒体类型枚举。 534 535**系统能力：** SystemCapability.Multimedia.Media.Core 536 537| 名称 | 值 | 说明 | 538| -------------- | --------------------- | ------------------- | 539| MEDIA_TYPE_AUD | 0 | 表示音频。 <br> **原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 | 540| MEDIA_TYPE_VID | 1 | 表示视频。 <br> **原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 | 541| MEDIA_TYPE_SUBTITLE<sup>12+</sup> | 2 | 表示字幕。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 542 543## CodecMimeType<sup>8+</sup> 544 545Codec MIME类型枚举。 546 547**系统能力：** SystemCapability.Multimedia.Media.Core 548 549| 名称 | 值 | 说明 | 550| ------------ | --------------------- | ------------------------ | 551| VIDEO_H263 | 'video/h263' | 表示视频/h263类型。 | 552| VIDEO_AVC | 'video/avc' | 表示视频/avc类型。 | 553| VIDEO_MPEG2 | 'video/mpeg2' | 表示视频/mpeg2类型。 | 554| VIDEO_MPEG4 | 'video/mp4v-es' | 表示视频/mpeg4类型。 | 555| VIDEO_VP8 | 'video/x-vnd.on2.vp8' | 表示视频/vp8类型。 | 556| VIDEO_HEVC<sup>11+</sup> | 'video/hevc' | 表示视频/H265类型。| 557| AUDIO_AAC | 'audio/mp4a-latm' | 表示音频/mp4a-latm类型。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 558| AUDIO_VORBIS | 'audio/vorbis' | 表示音频/vorbis类型。 | 559| AUDIO_FLAC | 'audio/flac' | 表示音频/flac类型。 | 560| AUDIO_MP3<sup>12+</sup> | 'audio/mpeg' | 表示音频/mpeg类型。 | 561| AUDIO_G711MU<sup>12+</sup> | 'audio/g711mu' | 表示音频/G711-mulaw类型。 | 562| AUDIO_AMR_NB<sup>18+</sup> | 'audio/3gpp' | 表示音频/amr-nb类型。 | 563| AUDIO_AMR_WB<sup>18+</sup> | 'audio/amr-wb' | 表示音频/amr-wb类型。 | 564 565## MediaDescriptionKey<sup>8+</sup> 566 567媒体信息描述枚举。 568 569**系统能力：** SystemCapability.Multimedia.Media.Core 570 571| 名称 | 值 | 说明 | 572| ------------------------ | --------------- | ------------------------------------------------------------ | 573| MD_KEY_TRACK_INDEX | 'track_index' | 表示轨道序号，其对应键值类型为number。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 574| MD_KEY_TRACK_TYPE | 'track_type' | 表示轨道类型，其对应键值类型为number，参考[MediaType](#mediatype8)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 575| MD_KEY_CODEC_MIME | 'codec_mime' | 表示codec_mime类型，其对应键值类型为string。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 576| MD_KEY_DURATION | 'duration' | 表示媒体时长，其对应键值类型为number，单位为毫秒（ms）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 577| MD_KEY_BITRATE | 'bitrate' | 表示比特率，其对应键值类型为number，单位为比特率（bps）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 578| MD_KEY_WIDTH | 'width' | 表示视频宽度，其对应键值类型为number，单位为像素（px）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 579| MD_KEY_HEIGHT | 'height' | 表示视频高度，其对应键值类型为number，单位为像素（px）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 580| MD_KEY_FRAME_RATE | 'frame_rate' | 表示视频帧率，其对应键值类型为number，单位为每100秒的帧数。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 581| MD_KEY_AUD_CHANNEL_COUNT | 'channel_count' | 表示声道数，其对应键值类型为number。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 582| MD_KEY_AUD_SAMPLE_RATE | 'sample_rate' | 表示采样率，其对应键值类型为number，单位为赫兹（Hz）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 583| MD_KEY_AUD_SAMPLE_DEPTH<sup>12+</sup> | 'sample_depth' | 表示位深，其对应键值类型为number，单位为位（bit）。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 584| MD_KEY_LANGUAGE<sup>12+</sup> | 'language' | 表示字幕语言，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 585| MD_KEY_TRACK_NAME<sup>12+</sup> | 'track_name' | 表示track名称，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 586| MD_KEY_HDR_TYPE<sup>12+</sup> | 'hdr_type' | 表示视频轨类型，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 587 588## PlaybackInfoKey<sup>12+</sup> 589 590播放信息描述枚举。 591 592**系统能力：** SystemCapability.Multimedia.Media.Core 593 594| 名称 | 值 | 说明 | 595| ------------------------ | --------------- | ------------------------------------------------------------ | 596| SERVER_IP_ADDRESS | 'server_ip_address' | 表示服务器IP地址，其对应键值类型为string。 | 597| AVG_DOWNLOAD_RATE | 'average_download_rate'| 表示平均下载速率，其对应键值类型为number，单位为比特率（bps）。 | 598| DOWNLOAD_RATE | 'download_rate' | 表示1s的下载速率，其对应键值类型为number，单位为比特率（bps）。| 599| IS_DOWNLOADING | 'is_downloading' | 表示下载状态，1表示在下载状态，0表示非下载状态（下载完成），其对应键值类型为number。| 600| BUFFER_DURATION | 'buffer_duration' | 表示缓存数据的可播放时长，其对应键值类型为number，单位为秒（s）。| 601 602## BufferingInfoType<sup>8+</sup> 603 604缓存事件类型枚举。 605 606**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 607 608**系统能力：** SystemCapability.Multimedia.Media.Core 609 610| 名称 | 值 | 说明 | 611| ----------------- | ---- | -------------------------------- | 612| BUFFERING_START | 1 | 表示开始缓冲。当上报BUFFERING_START时，播放器会暂停播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 613| BUFFERING_END | 2 | 表示结束缓冲。当上报BUFFERING_END时，播放器会恢复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 614| BUFFERING_PERCENT | 3 | 表示缓冲百分比。可参考该事件感知缓冲进度。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 615| CACHED_DURATION | 4 | 表示已缓冲数据预估可播放时长，单位为毫秒（ms）。缓冲区中的数据变化量大于500ms，上报一次。可参考该事件做进度条。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 616 617## StateChangeReason<sup>9+</sup> 618 619表示播放或录制实例状态机切换原因的枚举，伴随state一起上报。 620 621**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 622 623**系统能力：** SystemCapability.Multimedia.Media.Core 624 625| 名称 | 值 | 说明 | 626| ---------- | ---- | ------------------------------------------------------------ | 627| USER | 1 | 表示用户行为造成的状态切换，由用户或客户端主动调用接口产生。 | 628| BACKGROUND | 2 | 表示后台系统行为造成的状态切换，比如应用未注册播控中心权限，退到后台时被系统强制暂停或停止。 | 629 630## AVPlayer<sup>9+</sup> 631 632播放管理类，用于管理和播放媒体资源。在调用AVPlayer的方法前，需要先通过[createAVPlayer()](#mediacreateavplayer9)构建一个AVPlayer实例。 633 634Audio/Video播放demo可参考：[音频播放开发指导](../../media/media/using-avplayer-for-playback.md)、[视频播放开发指导](../../media/media/video-playback.md)。 635 636> **说明：** 637> 638> 在使用AVPlayer实例的方法时，建议开发者注册相关回调，主动获取当前状态变化。 639> - [on('stateChange')](#onstatechange9)：监听播放状态机AVPlayerState切换。 640> - [on('error')](#onerror9)：监听错误事件。 641 642### 属性 643 644**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 645 646| 名称 | 类型 | 只读 | 可选 | 说明 | 647| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 648| 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开始，该接口支持在原子化服务中使用。 | 649| 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开始，该接口支持在原子化服务中使用。 | 650| 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开始，该接口支持在原子化服务中使用。 | 651| 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#getxcomponentsurfaceid)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 652| loop<sup>9+</sup> | boolean | 否 | 否 | 视频循环播放属性，默认'false'，设置为'true'表示循环播放，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。<br/>直播场景不支持loop设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 653| videoScaleType<sup>9+</sup> | [VideoScaleType](#videoscaletype9) | 否 | 是 | 视频缩放模式，默认VIDEO_SCALE_TYPE_FIT，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 654| 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开始，该接口支持在原子化服务中使用。| 655| 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开始，该接口支持在原子化服务中使用。| 656| 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开始，该接口支持在原子化服务中使用。| 657| state<sup>9+</sup> | [AVPlayerState](#avplayerstate9) | 是 | 否 | 音视频播放的状态，全状态有效，可查询参数。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 658| currentTime<sup>9+</sup> | number | 是 | 否 | 视频的当前播放位置，单位为毫秒（ms），可查询参数。<br/>返回为(-1)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 659| duration<sup>9+</sup> | number | 是 | 否 | 视频时长，单位为毫秒（ms），可查询参数。<br/>返回为(-1)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 660| width<sup>9+</sup> | number | 是 | 否 | 视频宽，单位为像素（px），可查询参数。<br/>返回为(0)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 661| height<sup>9+</sup> | number | 是 | 否 | 视频高，单位为像素（px），可查询参数。<br/>返回为(0)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 662 663### on('stateChange')<sup>9+</sup> 664 665on(type: 'stateChange', callback: OnAVPlayerStateChangeHandle): void 666 667监听播放状态机AVPlayerState切换的事件。 668 669**原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 670 671**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 672 673**参数：** 674 675| 参数名 | 类型 | 必填 | 说明 | 676| -------- | -------- | ---- | ------------------------------------------------------------ | 677| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 678| callback | [OnAVPlayerStateChangeHandle](#onavplayerstatechangehandle12) | 是 | 状态机切换事件回调方法。 | 679 680**示例：** 681 682```ts 683avPlayer.on('stateChange', async (state: string, reason: media.StateChangeReason) => { 684 switch (state) { 685 case 'idle': 686 console.info('state idle called'); 687 break; 688 case 'initialized': 689 console.info('initialized prepared called'); 690 break; 691 case 'prepared': 692 console.info('state prepared called'); 693 break; 694 case 'playing': 695 console.info('state playing called'); 696 break; 697 case 'paused': 698 console.info('state paused called'); 699 break; 700 case 'completed': 701 console.info('state completed called'); 702 break; 703 case 'stopped': 704 console.info('state stopped called'); 705 break; 706 case 'released': 707 console.info('state released called'); 708 break; 709 case 'error': 710 console.info('state error called'); 711 break; 712 default: 713 console.info('unknown state :' + state); 714 break; 715 } 716}) 717``` 718 719### off('stateChange')<sup>9+</sup> 720 721off(type: 'stateChange', callback?: OnAVPlayerStateChangeHandle): void 722 723取消监听播放状态机[AVPlayerState](#avplayerstate9)切换的事件。 724 725**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 726 727**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 728 729**参数：** 730 731| 参数名 | 类型 | 必填 | 说明 | 732| ------ | ------ | ---- | ----------------------------------------------------- | 733| type | string | 是 | 状态机切换事件回调类型，取消注册的事件：'stateChange' | 734| callback | [OnAVPlayerStateChangeHandle](#onavplayerstatechangehandle12) | 否 | 状态机切换事件回调方法。<br/>从API version 12开始支持此参数。 | 735 736**示例：** 737 738```ts 739avPlayer.off('stateChange') 740``` 741 742### on('error')<sup>9+</sup> 743 744on(type: 'error', callback: ErrorCallback): void 745 746监听[AVPlayer](#avplayer9)的错误事件，该事件仅用于错误提示，不需要用户停止播控动作。如果此时[AVPlayerState](#avplayerstate9)也切至error状态，用户需要通过[reset()](#reset9)或者[release()](#release9)退出播放操作。 747 748**原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 749 750**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 751 752**参数：** 753 754| 参数名 | 类型 | 必填 | 说明 | 755| -------- | -------- | ---- | ------------------------------------------------------------ | 756| type | string | 是 | 错误事件回调类型，支持的事件：'error'，用户操作和系统都会触发此事件。 | 757| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 错误事件回调方法，使用播放器的过程中发生错误，会提供错误码ID和错误信息。 | 758 759**错误码：** 760 761以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 762 763在API version 9-13，针对网络、服务器等数据流异常，接口上报5400103；从API version 14开始，对应错误细化为错误码5411001-5411011。 764 765| 错误码ID | 错误信息 | 766| -------- | --------------------- | 767| 201 | Permission denied. | 768| 401 | The parameter check failed. | 769| 801 | Capability not supported. | 770| 5400101 | No memory. | 771| 5400102 | Operation not allowed.| 772| 5400103 | I/O error. | 773| 5400104 | Time out. | 774| 5400105 | Service died. | 775| 5400106 | Unsupported format. | 776| 5411001 | IO can not find host. | 777| 5411002 | IO connection timeout. | 778| 5411003 | IO network abnormal. | 779| 5411004 | IO network unavailable. | 780| 5411005 | IO no permission. | 781| 5411006 | IO request denied. | 782| 5411007 | IO resource not found. | 783| 5411008 | IO SSL client cert needed. | 784| 5411009 | IO SSL connect fail. | 785| 5411010 | IO SSL server cert untrusted. | 786| 5411011 | IO unsupported request. | 787 788**示例：** 789 790```ts 791import { BusinessError } from '@kit.BasicServicesKit'; 792 793avPlayer.on('error', (error: BusinessError) => { 794 console.info('error happened,and error message is :' + error.message) 795 console.info('error happened,and error code is :' + error.code) 796}) 797``` 798 799### off('error')<sup>9+</sup> 800 801off(type: 'error', callback?: ErrorCallback): void 802 803取消监听播放的错误事件。 804 805**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 806 807**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 808 809**参数：** 810 811| 参数名 | 类型 | 必填 | 说明 | 812| ------ | ------ | ---- | ----------------------------------------- | 813| type | string | 是 | 错误事件回调类型，取消注册的事件：'error' | 814| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 错误事件回调方法，使用播放器的过程中发生错误，会提供错误码ID和错误信息。<br/>从API version 12开始支持此参数。 | 815 816**示例：** 817 818```ts 819avPlayer.off('error') 820``` 821 822### setMediaSource<sup>12+</sup> 823 824setMediaSource(src:MediaSource, strategy?: PlaybackStrategy): Promise\<void> 825 826流媒体预下载资源设置，下载url对应的流媒体数据，并暂存在内存中。[视频播放开发指导](../../media/media/video-playback.md)。通过Promise获取返回值。 827 828**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 829 830**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 831 832**参数：** 833 834| 参数名 | 类型 | 必填 | 说明 | 835| -------- | -------- | ---- | -------------------- | 836| src | [MediaSource](#mediasource12) | 是 | 流媒体预下载媒体来源。 | 837| strategy | [PlaybackStrategy](#playbackstrategy12) | 否 | 流媒体预下载播放策略。 | 838 839**返回值：** 840 841| 类型 | 说明 | 842| -------------- | ------------------------------------------ | 843| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 844 845**错误码：** 846 847以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 848 849| 错误码ID | 错误信息 | 850| -------- | ----------------------------------------- | 851| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 852| 5400102 | Operation not allowed. Return by promise. | 853 854**示例：** 855 856<!--code_no_check--> 857```ts 858let player = await media.createAVPlayer(); 859let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 860let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 861let playStrategy : media.PlaybackStrategy = { 862 preferredWidth: 1, 863 preferredHeight: 2, 864 preferredBufferDuration: 3, 865 preferredHdr: false, 866 preferredBufferDurationForPlaying: 1, 867 thresholdForAutoQuickPlay: 5 868}; 869player.setMediaSource(mediaSource, playStrategy); 870``` 871 872### setPlaybackStrategy<sup>12+</sup> 873 874setPlaybackStrategy(strategy: PlaybackStrategy): Promise\<void> 875 876设置播放策略，只能在initialized状态下调用。 877 878**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 879 880**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 881 882**参数：** 883 884| 参数名 | 类型 | 必填 | 说明 | 885| -------- | -------- | ---- | -------------------- | 886| strategy | [PlaybackStrategy](#playbackstrategy12) | 是 | 播放策略。 | 887 888**返回值：** 889 890| 类型 | 说明 | 891| -------------- | ------------------------------------ | 892| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 893 894**错误码：** 895 896以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 897 898| 错误码ID | 错误信息 | 899| -------- | ----------------------------------------- | 900| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. | 901| 5400102 | Operation not allowed. Return by promise. | 902 903**示例：** 904 905<!--code_no_check--> 906```ts 907import { common } from '@kit.AbilityKit'; 908 909private context: Context | undefined; 910constructor(context: Context) { 911 this.context = context; // this.getUIContext().getHostContext(); 912} 913 914let player = await media.createAVPlayer(); 915let fileDescriptor = await this.context.resourceManager.getRawFd('xxx.mp4') 916player.fdSrc = fileDescriptor 917let playStrategy : media.PlaybackStrategy = { 918 preferredWidth: 1, 919 preferredHeight: 2, 920 preferredBufferDuration: 3, 921 preferredHdr: false, 922 mutedMediaType: media.MediaType.MEDIA_TYPE_AUD, 923 preferredBufferDurationForPlaying: 1, 924 thresholdForAutoQuickPlay: 5 925}; 926player.setPlaybackStrategy(playStrategy); 927``` 928 929### setPlaybackRange<sup>18+</sup> 930 931setPlaybackRange(startTimeMs: number, endTimeMs: number, mode?: SeekMode) : Promise\<void> 932 933设置播放区间，并通过指定的[SeekMode](#seekmode8)跳转到区间开始位置。设置之后，只播放音视频文件设定区间内的内容。该方法异步方式返回执行结果，通过Promise获取返回值。可在**initialized**/**prepared**/**paused**/**stopped**/**completed**状态下使用。 934 935**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 936 937**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 938 939**参数：** 940 941| 参数名 | 类型 | 必填 | 说明 | 942| -------- | ---------------------- | ---- | --------------------------- | 943| startTimeMs | number | 是 | 区间开始位置，单位ms，取值[0, duration)。可以设置-1值，系统将会从0位置开始播放。| 944| endTimeMs | number | 是 | 区间结束位置，单位ms，取值(startTimeMs, duration]。可以设置-1值，系统将会播放到资源末尾。| 945| mode | [SeekMode](#seekmode8) | 否 | 支持SeekMode.SEEK_PREV_SYNC和SeekMode.SEEK_CLOSEST, <br/>默认值: SeekMode.SEEK_PREV_SYNC。| 946 947**错误码：** 948 949以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 950 951| 错误码ID | 错误信息 | 952| -------- | ------------------------------------------ | 953| 401 | The parameter check failed. Return by promise. | 954| 5400102 | Operation not allowed. Return by promise. | 955 956**示例：** 957 958```ts 959import { media } from '@kit.MediaKit'; 960import { BusinessError } from '@kit.BasicServicesKit'; 961 962avPlayer.setPlaybackRange(0, 6000, media.SeekMode.SEEK_CLOSEST).then(() => { 963 console.info('Succeeded setPlaybackRange'); 964}).catch((err: BusinessError) => { 965 console.error('Failed to setPlaybackRange' + err.message); 966}); 967``` 968 969### prepare<sup>9+</sup> 970 971prepare(callback: AsyncCallback\<void>): void 972 973准备播放音频/视频，需在[stateChange](#onstatechange9)事件成功触发至initialized状态后，才能调用。使用callback方式异步获取返回值。 974 975**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 976 977**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 978 979**参数：** 980 981| 参数名 | 类型 | 必填 | 说明 | 982| -------- | -------- | ---- | -------------------- | 983| callback | AsyncCallback\<void> | 是 | 准备播放的回调方法。 | 984 985**错误码：** 986 987以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 988 989| 错误码ID | 错误信息 | 990| -------- | ------------------------------------------ | 991| 5400102 | Operation not allowed. Return by callback. | 992| 5400106 | Unsupported format. Return by callback. | 993 994**示例：** 995 996```ts 997import { BusinessError } from '@kit.BasicServicesKit'; 998 999avPlayer.prepare((err: BusinessError) => { 1000 if (err) { 1001 console.error('Failed to prepare,error message is :' + err.message) 1002 } else { 1003 console.info('Succeeded in preparing'); 1004 } 1005}) 1006``` 1007 1008### prepare<sup>9+</sup> 1009 1010prepare(): Promise\<void> 1011 1012准备播放音频/视频，需在[stateChange](#onstatechange9)事件成功触发至initialized状态后，才能调用。通过Promise获取返回值。 1013 1014**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1015 1016**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1017 1018**返回值：** 1019 1020| 类型 | 说明 | 1021| -------------- | ------------------------- | 1022| Promise\<void> | 准备播放的Promise返回值。 | 1023 1024**错误码：** 1025 1026以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1027 1028| 错误码ID | 错误信息 | 1029| -------- | ----------------------------------------- | 1030| 5400102 | Operation not allowed. Return by promise. | 1031| 5400106 | Unsupported format. Return by promise. | 1032 1033**示例：** 1034 1035```ts 1036import { BusinessError } from '@kit.BasicServicesKit'; 1037 1038avPlayer.prepare().then(() => { 1039 console.info('Succeeded in preparing'); 1040}, (err: BusinessError) => { 1041 console.error('Failed to prepare,error message is :' + err.message) 1042}) 1043``` 1044 1045### setMediaMuted<sup>12+</sup> 1046 1047setMediaMuted(mediaType: MediaType, muted: boolean ): Promise\<void> 1048 1049设置音频静音/取消音频静音。只能在prepared/playing/paused/completed状态下调用。仅支持设置mediaType为音频格式。 1050 1051**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1052 1053**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1054 1055**参数：** 1056 1057| 参数名 | 类型 | 必填 | 说明 | 1058| -------- | -------- | ---- | -------------------- | 1059| mediaType | [MediaType](#mediatype8) | 是 | 播放策略。 | 1060| muted | boolean | 是 | 是否静音播放。true表示是静音播放，false表示不是静音播放。 | 1061 1062**返回值：** 1063 1064| 类型 | 说明 | 1065| -------------- | ------------------------- | 1066| Promise\<void> | 准备播放的Promise返回值。 | 1067 1068**错误码：** 1069 1070以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1071 1072| 错误码ID | 错误信息 | 1073| -------- | ----------------------------------------- | 1074| 401 | The parameter check failed. Return by promise. | 1075| 5400102 | Operation not allowed. Return by promise. | 1076 1077**示例：** 1078 1079```ts 1080import { BusinessError } from '@kit.BasicServicesKit'; 1081 1082avPlayer.prepare().then(() => { 1083 console.info('Succeeded in preparing'); 1084 avPlayer.setMediaMuted(media.MediaType.MEDIA_TYPE_AUD, true) 1085}, (err: BusinessError) => { 1086 console.error('Failed to prepare,error message is :' + err.message) 1087}) 1088``` 1089 1090### play<sup>9+</sup> 1091 1092play(callback: AsyncCallback\<void>): void 1093 1094开始播放音视频资源，只能在prepared/paused/completed状态调用。使用callback方式异步获取返回值。 1095 1096**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1097 1098**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1099 1100**参数：** 1101 1102| 参数名 | 类型 | 必填 | 说明 | 1103| -------- | -------- | ---- | -------------------- | 1104| callback | AsyncCallback\<void> | 是 | 开始播放的回调方法。 | 1105 1106**错误码：** 1107 1108以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1109 1110| 错误码ID | 错误信息 | 1111| -------- | ------------------------------------------ | 1112| 5400102 | Operation not allowed. Return by callback. | 1113 1114**示例：** 1115 1116```ts 1117import { BusinessError } from '@kit.BasicServicesKit'; 1118 1119avPlayer.play((err: BusinessError) => { 1120 if (err) { 1121 console.error('Failed to play,error message is :' + err.message) 1122 } else { 1123 console.info('Succeeded in playing'); 1124 } 1125}) 1126``` 1127 1128### play<sup>9+</sup> 1129 1130play(): Promise\<void> 1131 1132开始播放音视频资源，只能在prepared/paused/completed状态调用。通过Promise获取返回值。 1133 1134**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1135 1136**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1137 1138**返回值：** 1139 1140| 类型 | 说明 | 1141| -------------- | ------------------------- | 1142| Promise\<void> | 开始播放的Promise返回值。 | 1143 1144**错误码：** 1145 1146以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1147 1148| 错误码ID | 错误信息 | 1149| -------- | ----------------------------------------- | 1150| 5400102 | Operation not allowed. Return by promise. | 1151 1152**示例：** 1153 1154```ts 1155import { BusinessError } from '@kit.BasicServicesKit'; 1156 1157avPlayer.play().then(() => { 1158 console.info('Succeeded in playing'); 1159}, (err: BusinessError) => { 1160 console.error('Failed to play,error message is :' + err.message) 1161}) 1162``` 1163 1164### pause<sup>9+</sup> 1165 1166pause(callback: AsyncCallback\<void>): void 1167 1168暂停播放音视频资源，只能在playing状态调用。使用callback方式异步获取返回值。 1169 1170**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1171 1172**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1173 1174**参数：** 1175 1176| 参数名 | 类型 | 必填 | 说明 | 1177| -------- | -------- | ---- | -------------------- | 1178| callback | AsyncCallback\<void> | 是 | 暂停播放的回调方法。 | 1179 1180**错误码：** 1181 1182以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1183 1184| 错误码ID | 错误信息 | 1185| -------- | ------------------------------------------ | 1186| 5400102 | Operation not allowed. Return by callback. | 1187 1188**示例：** 1189 1190```ts 1191import { BusinessError } from '@kit.BasicServicesKit'; 1192 1193avPlayer.pause((err: BusinessError) => { 1194 if (err) { 1195 console.error('Failed to pause,error message is :' + err.message) 1196 } else { 1197 console.info('Succeeded in pausing'); 1198 } 1199}) 1200``` 1201 1202### pause<sup>9+</sup> 1203 1204pause(): Promise\<void> 1205 1206暂停播放音视频资源，只能在playing状态调用。通过Promise获取返回值。 1207 1208**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1209 1210**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1211 1212**返回值：** 1213 1214| 类型 | 说明 | 1215| -------------- | ------------------------- | 1216| Promise\<void> | 暂停播放的Promise返回值。 | 1217 1218**错误码：** 1219 1220以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1221 1222| 错误码ID | 错误信息 | 1223| -------- | ----------------------------------------- | 1224| 5400102 | Operation not allowed. Return by promise. | 1225 1226**示例：** 1227 1228```ts 1229import { BusinessError } from '@kit.BasicServicesKit'; 1230 1231avPlayer.pause().then(() => { 1232 console.info('Succeeded in pausing'); 1233}, (err: BusinessError) => { 1234 console.error('Failed to pause,error message is :' + err.message) 1235}) 1236``` 1237 1238### stop<sup>9+</sup> 1239 1240stop(callback: AsyncCallback\<void>): void 1241 1242停止播放音视频资源，只能在prepared/playing/paused/completed状态调用。使用callback方式异步获取返回值。 1243 1244**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1245 1246**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1247 1248**参数：** 1249 1250| 参数名 | 类型 | 必填 | 说明 | 1251| -------- | -------- | ---- | -------------------- | 1252| callback | AsyncCallback\<void> | 是 | 停止播放的回调方法。 | 1253 1254**错误码：** 1255 1256以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1257 1258| 错误码ID | 错误信息 | 1259| -------- | ------------------------------------------ | 1260| 5400102 | Operation not allowed. Return by callback. | 1261 1262**示例：** 1263 1264```ts 1265import { BusinessError } from '@kit.BasicServicesKit'; 1266 1267avPlayer.stop((err: BusinessError) => { 1268 if (err) { 1269 console.error('Failed to stop,error message is :' + err.message) 1270 } else { 1271 console.info('Succeeded in stopping'); 1272 } 1273}) 1274``` 1275 1276### stop<sup>9+</sup> 1277 1278stop(): Promise\<void> 1279 1280停止播放音视频资源，只能在prepared/playing/paused/completed状态调用。通过Promise获取返回值。 1281 1282**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1283 1284**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1285 1286**返回值：** 1287 1288| 类型 | 说明 | 1289| -------------- | ------------------------- | 1290| Promise\<void> | 停止播放的Promise返回值。 | 1291 1292**错误码：** 1293 1294以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1295 1296| 错误码ID | 错误信息 | 1297| -------- | ----------------------------------------- | 1298| 5400102 | Operation not allowed. Return by promise. | 1299 1300**示例：** 1301 1302```ts 1303import { BusinessError } from '@kit.BasicServicesKit'; 1304 1305avPlayer.stop().then(() => { 1306 console.info('Succeeded in stopping'); 1307}, (err: BusinessError) => { 1308 console.error('Failed to stop,error message is :' + err.message) 1309}) 1310``` 1311 1312### reset<sup>9+</sup> 1313 1314reset(callback: AsyncCallback\<void>): void 1315 1316重置播放，只能在initialized/prepared/playing/paused/completed/stopped/error状态调用。使用callback方式异步获取返回值。 1317 1318**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1319 1320**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1321 1322**参数：** 1323 1324| 参数名 | 类型 | 必填 | 说明 | 1325| -------- | -------- | ---- | -------------------- | 1326| callback | AsyncCallback\<void> | 是 | 重置播放的回调方法。 | 1327 1328**错误码：** 1329 1330以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1331 1332| 错误码ID | 错误信息 | 1333| -------- | ------------------------------------------ | 1334| 5400102 | Operation not allowed. Return by callback. | 1335 1336**示例：** 1337 1338```ts 1339import { BusinessError } from '@kit.BasicServicesKit'; 1340 1341avPlayer.reset((err: BusinessError) => { 1342 if (err) { 1343 console.error('Failed to reset,error message is :' + err.message) 1344 } else { 1345 console.info('Succeeded in resetting'); 1346 } 1347}) 1348``` 1349 1350### reset<sup>9+</sup> 1351 1352reset(): Promise\<void> 1353 1354重置播放，只能在initialized/prepared/playing/paused/completed/stopped/error状态调用。通过Promise获取返回值。 1355 1356**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1357 1358**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1359 1360**返回值：** 1361 1362| 类型 | 说明 | 1363| -------------- | ------------------------- | 1364| Promise\<void> | 重置播放的Promise返回值。 | 1365 1366**错误码：** 1367 1368以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1369 1370| 错误码ID | 错误信息 | 1371| -------- | ----------------------------------------- | 1372| 5400102 | Operation not allowed. Return by promise. | 1373 1374**示例：** 1375 1376```ts 1377import { BusinessError } from '@kit.BasicServicesKit'; 1378 1379avPlayer.reset().then(() => { 1380 console.info('Succeeded in resetting'); 1381}, (err: BusinessError) => { 1382 console.error('Failed to reset,error message is :' + err.message) 1383}) 1384``` 1385 1386### release<sup>9+</sup> 1387 1388release(callback: AsyncCallback\<void>): void 1389 1390销毁播放资源，除released状态外，均可以调用。使用callback方式异步获取返回值。 1391 1392**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1393 1394**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1395 1396**参数：** 1397 1398| 参数名 | 类型 | 必填 | 说明 | 1399| -------- | -------- | ---- | -------------------- | 1400| callback | AsyncCallback\<void> | 是 | 销毁播放的回调方法。 | 1401 1402**错误码：** 1403 1404以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1405 1406| 错误码ID | 错误信息 | 1407| -------- | ------------------------------------------ | 1408| 5400102 | Operation not allowed. Return by callback. | 1409 1410**示例：** 1411 1412```ts 1413import { BusinessError } from '@kit.BasicServicesKit'; 1414 1415avPlayer.release((err: BusinessError) => { 1416 if (err) { 1417 console.error('Failed to release,error message is :' + err.message) 1418 } else { 1419 console.info('Succeeded in releasing'); 1420 } 1421}) 1422``` 1423 1424### release<sup>9+</sup> 1425 1426release(): Promise\<void> 1427 1428销毁播放资源，除released状态，都可以调用。通过Promise获取返回值。 1429 1430**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1431 1432**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1433 1434**返回值：** 1435 1436| 类型 | 说明 | 1437| -------------- | ------------------------- | 1438| Promise\<void> | 销毁播放的Promise返回值。 | 1439 1440**错误码：** 1441 1442以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1443 1444| 错误码ID | 错误信息 | 1445| -------- | ----------------------------------------- | 1446| 5400102 | Operation not allowed. Return by promise. | 1447 1448**示例：** 1449 1450```ts 1451import { BusinessError } from '@kit.BasicServicesKit'; 1452 1453avPlayer.release().then(() => { 1454 console.info('Succeeded in releasing'); 1455}, (err: BusinessError) => { 1456 console.error('Failed to release,error message is :' + err.message) 1457}) 1458``` 1459 1460### getTrackDescription<sup>9+</sup> 1461 1462getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 1463 1464获取音视频轨道信息，可以在prepared/playing/paused状态调用。获取所有音视轨道信息，应在数据加载回调后调用。使用callback方式异步获取返回值。 1465 1466**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1467 1468**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1469 1470**参数：** 1471 1472| 参数名 | 类型 | 必填 | 说明 | 1473| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1474| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是 | 回调函数，当获取音视频轨道信息成功，err为undefined，data为获取到的MediaDescription数组；否则为错误对象。| 1475 1476**错误码：** 1477 1478以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1479 1480| 错误码ID | 错误信息 | 1481| -------- | ------------------------------------------ | 1482| 5400102 | Operation not allowed. Return by callback. | 1483 1484**示例：** 1485 1486```ts 1487import { BusinessError } from '@kit.BasicServicesKit'; 1488 1489avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1490 if ((arrList) != null) { 1491 console.info('Succeeded in doing getTrackDescription'); 1492 } else { 1493 console.error(`Failed to do getTrackDescription, error:${error}`); 1494 } 1495}); 1496``` 1497 1498### getTrackDescription<sup>9+</sup> 1499 1500getTrackDescription(): Promise\<Array\<MediaDescription>> 1501 1502获取音视频轨道信息，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1503 1504**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1505 1506**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1507 1508**返回值：** 1509 1510| 类型 | 说明 | 1511| ------------------------------------------------------ | ------------------------------------------------- | 1512| Promise<Array<[MediaDescription](#mediadescription8)>> | Promise对象，返回音视频轨道信息MediaDescription数组。 | 1513 1514**错误码：** 1515 1516以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1517 1518| 错误码ID | 错误信息 | 1519| -------- | ----------------------------------------- | 1520| 5400102 | Operation not allowed. Return by promise. | 1521 1522**示例：** 1523 1524```ts 1525import { BusinessError } from '@kit.BasicServicesKit'; 1526 1527avPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 1528 console.info('Succeeded in getting TrackDescription'); 1529}).catch((error: BusinessError) => { 1530 console.error(`Failed to get TrackDescription, error:${error}`); 1531}); 1532``` 1533 1534### getSelectedTracks<sup>12+</sup> 1535 1536getSelectedTracks(): Promise\<Array\<number>> 1537 1538获取已选择的音视频轨道索引，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1539 1540**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1541 1542**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1543 1544**返回值：** 1545 1546| 类型 | 说明 | 1547| ------------------------------------------------------ | ------------------------------------------------- | 1548| Promise\<Array\<number>> | Promise对象，返回已选择音视频轨道索引数组。 | 1549 1550**错误码：** 1551 1552以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1553 1554| 错误码ID | 错误信息 | 1555| -------- | ----------------------------------------- | 1556| 5400102 | Operation not allowed. | 1557 1558**示例：** 1559 1560```ts 1561import { BusinessError } from '@kit.BasicServicesKit'; 1562 1563avPlayer.getSelectedTracks().then((arrList: Array<number>) => { 1564 console.info('Succeeded in getting SelectedTracks'); 1565}).catch((error: BusinessError) => { 1566 console.error(`Failed to get SelectedTracks, error:${error}`); 1567}); 1568``` 1569 1570### getPlaybackInfo<sup>12+</sup> 1571 1572getPlaybackInfo(): Promise\<PlaybackInfo> 1573 1574获取播放过程信息，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1575 1576**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1577 1578**返回值：** 1579 1580| 类型 | 说明 | 1581| ------------------------------------------------------ | ------------------------------------------------- | 1582| Promise<[PlaybackInfo](#playbackinfo12)> | Promise对象，返回播放器信息PlaybackInfo。 | 1583 1584**示例：** 1585 1586```ts 1587import { BusinessError } from '@kit.BasicServicesKit'; 1588 1589let avPlayer: media.AVPlayer | undefined = undefined; 1590let playbackInfo: media.PlaybackInfo | undefined = undefined; 1591media.createAVPlayer(async (err: BusinessError, player: media.AVPlayer) => { 1592 if (player != null) { 1593 avPlayer = player; 1594 console.info(`Succeeded in creating AVPlayer`); 1595 if (avPlayer) { 1596 try { 1597 playbackInfo = await avPlayer.getPlaybackInfo(); 1598 console.info(`AVPlayer getPlaybackInfo = ${JSON.stringify(playbackInfo)}`); // 打印整个PlaybackInfo的值。 1599 } catch (error) { 1600 console.error(`error = ${error}`); 1601 } 1602 } 1603 } else { 1604 console.error(`Failed to create AVPlayer, error message:${err.message}`); 1605 } 1606}); 1607``` 1608 1609### getPlaybackPosition<sup>18+</sup> 1610 1611getPlaybackPosition(): number 1612 1613获取当前播放位置，可以在prepared/playing/paused/completed状态调用。 1614 1615**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1616 1617**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1618 1619**返回值：** 1620 1621| 类型 | 说明 | 1622| ------------------------------------------------------ | ------------------------------------------------- | 1623| number | 返回当前播放位置的时间，单位：毫秒（ms）。| 1624 1625**错误码：** 1626 1627以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1628 1629| 错误码ID | 错误信息 | 1630| -------- | ----------------------------------------- | 1631| 5400102 | Operation not allowed. | 1632 1633**示例：** 1634 1635```ts 1636import { BusinessError } from '@kit.BasicServicesKit'; 1637 1638avPlayer.prepare().then(() => { 1639 console.info('Succeeded in preparing') 1640 let playbackPosition: number = avPlayer.getPlaybackPosition() 1641 console.info(`AVPlayer getPlaybackPosition== ${playbackPosition}`) 1642}, (err: BusinessError) => { 1643 console.error('Failed to prepare,error message is :' + err.message) 1644}) 1645``` 1646 1647### selectTrack<sup>12+</sup> 1648 1649selectTrack(index: number, mode?: SwitchMode): Promise\<void> 1650 1651使用AVPlayer播放多音视频轨资源时，选择指定轨道播放，通过Promise获取返回值。 1652 1653**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1654 1655**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1656 1657**参数：** 1658 1659| 参数名 | 类型 | 必填 | 说明 | 1660| -------- | -------- | ---- | -------------------- | 1661| index | number | 是 | 多音视频资源的轨道索引，可通过[getTrackDescription](#gettrackdescription9-1)接口获取当前资源的所有轨道信息[MediaDescription](#mediadescription8)。 | 1662| mode | [SwitchMode](#switchmode12) | 否 | 切换视频轨道模式，默认为SMOOTH模式，**仅在DASH协议网络流视频轨切换时生效**，其他场景当前暂不支持。 | 1663 1664**返回值：** 1665 1666| 类型 | 说明 | 1667| -------------- | ------------------------- | 1668| Promise\<void> | 选择轨道完成的Promise返回值。 | 1669 1670**错误码：** 1671 1672以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1673 1674| 错误码ID | 错误信息 | 1675| -------- | ----------------------------------------- | 1676| 401 | The parameter check failed. Return by promise. | 1677| 5400102 | Operation not allowed. Return by promise. | 1678 1679**示例：** 1680 1681<!--code_no_check--> 1682```ts 1683import { BusinessError } from '@kit.BasicServicesKit'; 1684 1685let avPlayer: media.AVPlayer = await media.createAVPlayer(); 1686let audioTrackIndex: Object = 0; 1687avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1688 if (arrList != null) { 1689 for (let i = 0; i < arrList.length; i++) { 1690 if (i != 0) { 1691 // 获取音频轨道列表。 1692 audioTrackIndex = arrList[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 1693 } 1694 } 1695 } else { 1696 console.error(`Failed to get TrackDescription, error:${error}`); 1697 } 1698}); 1699 1700// 选择其中一个音频轨道。 1701avPlayer.selectTrack(parseInt(audioTrackIndex.toString())); 1702``` 1703 1704### deselectTrack<sup>12+</sup> 1705 1706deselectTrack(index: number): Promise\<void> 1707 1708使用AVPlayer播放多音轨视频时取消指定音视频轨道播放，通过Promise获取返回值。 1709 1710**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1711 1712**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1713 1714**参数：** 1715 1716| 参数名 | 类型 | 必填 | 说明 | 1717| -------- | -------- | ---- | -------------------- | 1718| index | number | 是 | 多音视频资源的轨道索引，来自[getTrackDescription](#gettrackdescription9-1)接口所获取的轨道信息[MediaDescription](#mediadescription8)。 | 1719 1720**返回值：** 1721 1722| 类型 | 说明 | 1723| -------------- | ------------------------- | 1724| Promise\<void> | 取消选择曲目完成的Promise返回值。 | 1725 1726**错误码：** 1727 1728以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1729 1730| 错误码ID | 错误信息 | 1731| -------- | ----------------------------------------- | 1732| 401 | The parameter check failed. Return by promise. | 1733| 5400102 | Operation not allowed. Return by promise. | 1734 1735**示例：** 1736 1737<!--code_no_check--> 1738```ts 1739import { BusinessError } from '@kit.BasicServicesKit'; 1740 1741let avPlayer: media.AVPlayer = await media.createAVPlayer(); 1742let audioTrackIndex: Object = 0; 1743avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1744 if (arrList != null) { 1745 for (let i = 0; i < arrList.length; i++) { 1746 if (i != 0) { 1747 // 获取音频轨道列表。 1748 audioTrackIndex = arrList[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 1749 } 1750 } 1751 } else { 1752 console.error(`Failed to get TrackDescription, error:${error}`); 1753 } 1754}); 1755 1756// 选择其中一个音频轨道。 1757avPlayer.selectTrack(parseInt(audioTrackIndex.toString())); 1758// 取消选择上次选中的音频轨道，并恢复到默认音频轨道。 1759avPlayer.deselectTrack(parseInt(audioTrackIndex.toString())); 1760``` 1761 1762### setDecryptionConfig<sup>11+</sup> 1763 1764setDecryptionConfig(mediaKeySession: drm.MediaKeySession, secureVideoPath: boolean): void 1765 1766设置解密配置。当收到[mediaKeySystemInfoUpdate事件](#onmediakeysysteminfoupdate11)时，需根据事件上报的信息创建相关配置并设置解密配置，否则无法播放。 1767 1768**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1769 1770**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1771 1772**参数：** 1773 1774| 参数名 | 类型 | 必填 | 说明 | 1775| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1776| mediaKeySession | [drm.MediaKeySession](../apis-drm-kit/js-apis-drm.md#mediakeysession) | 是 | 解密会话 | 1777| secureVideoPath | boolean | 是 | 安全视频通路，true表示选择安全视频通路，false表示选择非安全视频通路 | 1778 1779**错误码：** 1780 1781以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1782 1783| 错误码ID | 错误信息 | 1784| -------- | ----------------------------------------- | 1785| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1786 1787**示例：** 1788 1789关于drm模块的示例具体可见[js-apis-drm.md](../apis-drm-kit/js-apis-drm.md)。 1790```ts 1791import { drm } from '@kit.DrmKit'; 1792 1793// 创建MediaKeySystem系统。 1794let keySystem:drm.MediaKeySystem = drm.createMediaKeySystem('com.clearplay.drm'); 1795// 创建MediaKeySession解密会话。 1796let keySession:drm.MediaKeySession = keySystem.createMediaKeySession(drm.ContentProtectionLevel.CONTENT_PROTECTION_LEVEL_SW_CRYPTO); 1797// 生成许可证请求、设置许可证响应等。 1798// 安全视频通路标志。 1799let secureVideoPath:boolean = false; 1800// 设置解密配置。 1801avPlayer.setDecryptionConfig(keySession, secureVideoPath); 1802``` 1803 1804### getMediaKeySystemInfos<sup>11+</sup> 1805 1806getMediaKeySystemInfos(): Array\<drm.MediaKeySystemInfo> 1807 1808获取当前播放的媒体资源的MediaKeySystemInfo。需要在[mediaKeySystemInfoUpdate事件](#onmediakeysysteminfoupdate11)触发成功后才能调用。 1809 1810**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1811 1812**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1813 1814**返回值：** 1815 1816| 类型 | 说明 | 1817| ------------------------------------------------------ | ------------------------------------------------- | 1818| Array<[drm.MediaKeySystemInfo](../apis-drm-kit/js-apis-drm.md#mediakeysysteminfo)> | MediaKeySystemInfo数组，MediaKeySystemInfo具有uuid和pssh两个属性。 | 1819 1820**示例：** 1821 1822```ts 1823import { drm } from '@kit.DrmKit'; 1824 1825const infos = avPlayer.getMediaKeySystemInfos(); 1826console.info('GetMediaKeySystemInfos count: ' + infos.length); 1827for (let i = 0; i < infos.length; i++) { 1828 console.info('GetMediaKeySystemInfos uuid: ' + infos[i]["uuid"]); 1829 console.info('GetMediaKeySystemInfos pssh: ' + infos[i]["pssh"]); 1830} 1831``` 1832 1833### seek<sup>9+</sup> 1834 1835seek(timeMs: number, mode?:SeekMode): void 1836 1837跳转到指定播放位置，只能在prepared/playing/paused/completed状态调用，可以通过[seekDone事件](#onseekdone9)确认是否生效。 1838注：直播场景不支持seek。 1839 1840**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1841 1842**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1843 1844**参数：** 1845 1846| 参数名 | 类型 | 必填 | 说明 | 1847| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 1848| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, [duration](#属性)]。SEEK_CONTINUOU模式可以额外取值-1，用于表示SEEK_CONTINUOUS模式结束。 | 1849| mode | [SeekMode](#seekmode8) | 否 | 基于视频I帧的跳转模式，默认为SEEK_PREV_SYNC模式，**仅在视频资源播放时设置**。 | 1850 1851**示例：** 1852 1853```ts 1854let seekTime: number = 1000 1855avPlayer.seek(seekTime, media.SeekMode.SEEK_PREV_SYNC) 1856``` 1857 1858```ts 1859// SEEK_CONTINUOUS 可以结合seekBar/slider的回调方法进行对应处理。 1860async onSlideMoving(position : number) : Promise<void> { 1861 // seekBar/slider移动过程中回调触发，调用seek(position, media.SeekMode.SEEK_CONTINUOUS)进行seek。 1862 this.avPlayer.seek(position, media.SeekMode.SEEK_CONTINUOUS) 1863} 1864 1865async onSlideEnd(position : number) : Promise<void> { 1866 // seekBar/slider移动结束回调触发，调用seek(-1, media.SeekMode.SEEK_CONTINUOUS)结束seek。 1867 this.avPlayer.seek(-1, media.SeekMode.SEEK_CONTINUOUS) 1868} 1869``` 1870 1871### isSeekContinuousSupported<sup>18+</sup> 1872 1873isSeekContinuousSupported() : boolean 1874 1875查询媒体源是否支持以SEEK_CONTINUOUS模式[SeekMode](#seekmode8)进行[seek](#seek9)，在prepared/playing/paused/completed状态调用返回实际值，其余状态调用返回false。对于不支持SEEK_CONTINUOUS模式进行seek的设备，返回false。 1876 1877**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1878 1879**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1880 1881**示例：** 1882 1883```ts 1884let isSupported = avPlayer.isSeekContinuousSupported() 1885``` 1886 1887### on('seekDone')<sup>9+</sup> 1888 1889on(type: 'seekDone', callback: Callback\<number>): void 1890 1891监听seek生效的事件。 1892 1893**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1894 1895**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1896 1897**参数：** 1898 1899| 参数名 | 类型 | 必填 | 说明 | 1900| -------- | -------- | ---- | ------------------------------------------------------------ | 1901| type | string | 是 | seek生效的事件回调类型，支持的事件：'seekDone'，除SEEK_CONTINUOUS外的[SeekMode](#seekmode8)每次调用seek后都会回调此事件。 | 1902| callback | Callback\<number> | 是 | 回调函数。seek生效的事件回调方法，只会上报用户请求的time位置。<br/>**视频播放：**[SeekMode](#seekmode8)会造成实际跳转位置与用户设置产生偏差，精准位置需要通过currentTime获取，事件回调的time仅代表完成用户某一次请求。 | 1903 1904**示例：** 1905 1906```ts 1907avPlayer.on('seekDone', (seekDoneTime:number) => { 1908 console.info('seekDone called,and seek time is:' + seekDoneTime) 1909}) 1910``` 1911 1912### off('seekDone')<sup>9+</sup> 1913 1914off(type: 'seekDone', callback?: Callback\<number>): void 1915 1916取消监听seek生效的事件。 1917 1918**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1919 1920**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1921 1922**参数：** 1923 1924| 参数名 | 类型 | 必填 | 说明 | 1925| ------ | ------ | ---- | ---------------------------------------------------- | 1926| type | string | 是 | seek生效的事件回调类型，取消注册的事件：'seekDone'。 | 1927| callback | Callback\<number> | 否 | 回调函数。seek生效的事件回调方法，只会上报用户请求的time位置。<br/>**视频播放：**[SeekMode](#seekmode8)会造成实际跳转位置与用户设置产生偏差，精准位置需要通过currentTime获取，事件回调的time仅代表完成用户某一次请求。<br/>从API version 12开始支持此参数。 | 1928 1929**示例：** 1930 1931```ts 1932avPlayer.off('seekDone') 1933``` 1934 1935### setSpeed<sup>9+</sup> 1936 1937setSpeed(speed: PlaybackSpeed): void 1938 1939设置倍速模式，只能在prepared/playing/paused/completed状态调用，可以通过[speedDone事件](#onspeeddone9)确认是否生效。 1940注：直播场景不支持setSpeed。 1941 1942**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1943 1944**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1945 1946**参数：** 1947 1948| 参数名 | 类型 | 必填 | 说明 | 1949| ------ | -------------------------------- | ---- | ------------------ | 1950| speed | [PlaybackSpeed](#playbackspeed8) | 是 | 指定播放倍速模式。 | 1951 1952**示例：** 1953 1954```ts 1955avPlayer.setSpeed(media.PlaybackSpeed.SPEED_FORWARD_2_00_X) 1956``` 1957 1958### on('speedDone')<sup>9+</sup> 1959 1960on(type: 'speedDone', callback: Callback\<number>): void 1961 1962监听setSpeed生效的事件 1963 1964**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1965 1966**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1967 1968**参数：** 1969 1970| 参数名 | 类型 | 必填 | 说明 | 1971| -------- | -------- | ---- | ------------------------------------------------------------ | 1972| type | string | 是 | setSpeed生效的事件回调类型，支持的事件：'speedDone'，每次调用setSpeed后都会回调此事件。 | 1973| callback | Callback\<number> | 是 | 回调函数。当setSpeed成功，上报生效的倍速模式，具体见[PlaybackSpeed](#playbackspeed8)。 | 1974 1975**示例：** 1976 1977```ts 1978avPlayer.on('speedDone', (speed:number) => { 1979 console.info('speedDone called,and speed value is:' + speed) 1980}) 1981``` 1982 1983### off('speedDone')<sup>9+</sup> 1984 1985off(type: 'speedDone', callback?: Callback\<number>): void 1986 1987取消监听setSpeed生效的事件。 1988 1989**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1990 1991**参数：** 1992 1993| 参数名 | 类型 | 必填 | 说明 | 1994| ------ | ------ | ---- | --------------------------------------------------------- | 1995| type | string | 是 | setSpeed生效的事件回调类型，取消注册的事件：'speedDone'。 | 1996| callback | Callback\<number> | 否 | 回调函数。当setSpeed成功，上报生效的倍速模式，具体见[PlaybackSpeed](#playbackspeed8)。<br/>从API version 12开始支持此参数。 | 1997 1998**示例：** 1999 2000```ts 2001avPlayer.off('speedDone') 2002``` 2003 2004### setBitrate<sup>9+</sup> 2005 2006setBitrate(bitrate: number): void 2007 2008设置比特率，以播放所指定比特率的流媒体资源，当前仅对**HLS/DASH协议网络流**有效。默认情况下，AVPlayer会根据网络连接速度选择合适的比特率。只能在prepared/playing/paused/completed状态调用，可以通过[bitrateDone](#onbitratedone9)事件确认是否生效。 2009 2010**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2011 2012**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2013 2014**参数：** 2015 2016| 参数名 | 类型 | 必填 | 说明 | 2017| ------- | ------ | ---- | ------------------------------------------------------------ | 2018| bitrate | number | 是 | 指定比特率，须通过[availableBitrates](#onavailablebitrates9)事件获得当前HLS/DASH协议网络流可用的比特率列表，如果用户指定的比特率不在此列表中，则播放器将从可用比特率列表中选择最接近的比特率。如果通过availableBitrates事件获得的比特率列表长度为0，则不支持指定比特率，也不会产生bitrateDone回调。 | 2019 2020**示例：** 2021 2022```ts 2023let bitrate: number = 96000 2024avPlayer.setBitrate(bitrate) 2025``` 2026 2027### on('bitrateDone')<sup>9+</sup> 2028 2029on(type: 'bitrateDone', callback: Callback\<number>): void 2030 2031监听setBitrate生效的事件。 2032 2033**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2034 2035**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2036 2037**参数：** 2038 2039| 参数名 | 类型 | 必填 | 说明 | 2040| -------- | -------- | ---- | ------------------------------------------------------------ | 2041| type | string | 是 | setBitrate生效的事件回调类型，支持的事件：'bitrateDone'，每次调用setBitrate后都会回调此事件。 | 2042| callback | Callback\<number> | 是 | setBitrate生效的事件回调方法，上报生效的比特率。 | 2043 2044**示例：** 2045 2046```ts 2047avPlayer.on('bitrateDone', (bitrate:number) => { 2048 console.info('bitrateDone called,and bitrate value is:' + bitrate) 2049}) 2050``` 2051 2052### off('bitrateDone')<sup>9+</sup> 2053 2054off(type: 'bitrateDone', callback?: Callback\<number>): void 2055 2056取消监听setBitrate生效的事件。 2057 2058**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2059 2060**参数：** 2061 2062| 参数名 | 类型 | 必填 | 说明 | 2063| ------ | ------ | ---- | ------------------------------------------------------------ | 2064| type | string | 是 | setBitrate生效的事件回调类型，取消注册的事件：'bitrateDone'。 | 2065| callback | Callback\<number> | 否 | setBitrate生效的事件回调方法，上报生效的比特率。<br/>从API version 12开始支持此参数。 | 2066 2067**示例：** 2068 2069```ts 2070avPlayer.off('bitrateDone') 2071``` 2072 2073### on('availableBitrates')<sup>9+</sup> 2074 2075on(type: 'availableBitrates', callback: Callback\<Array\<number>>): void 2076 2077监听HLS/DASH协议网络流可用的比特率列表，只会在切换prepared状态后上报。 2078 2079**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2080 2081**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2082 2083**参数：** 2084 2085| 参数名 | 类型 | 必填 | 说明 | 2086| -------- | -------- | ---- | ------------------------------------------------------------ | 2087| type | string | 是 | HLS/DASH协议网络流可用比特率上报事件回调类型，支持的事件：'availableBitrates'，只会在prepared之后上报一次。 | 2088| callback | Callback\<Array\<number>> | 是 | HLS/DASH协议网络流可用比特率上报事件回调方法，使用数组存放支持的比特率。如果数组长度为0，则不支持指定比特率。 | 2089 2090**示例：** 2091 2092```ts 2093avPlayer.on('availableBitrates', (bitrates: Array<number>) => { 2094 console.info('availableBitrates called,and availableBitrates length is:' + bitrates.length) 2095}) 2096``` 2097 2098### off('availableBitrates')<sup>9+</sup> 2099 2100off(type: 'availableBitrates', callback?: Callback\<Array\<number>>): void 2101 2102取消监听HLS/DASH协议网络流可用的比特率列表，调用[prepare](#prepare9)后，上报此事件。 2103 2104**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2105 2106**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2107 2108**参数：** 2109 2110| 参数名 | 类型 | 必填 | 说明 | 2111| ------ | ------ | ---- | ------------------------------------------------------------ | 2112| type | string | 是 | HLS/DASH协议网络流可用比特率上报事件回调类型，取消注册的事件：'availableBitrates'。 | 2113| callback | Callback\<Array\<number>> | 否 | HLS/DASH协议网络流可用比特率上报事件回调方法，使用数组存放支持的比特率。如果数组长度为0，则不支持指定比特率。<br/>从API version 12开始支持此参数。 | 2114 2115**示例：** 2116 2117```ts 2118avPlayer.off('availableBitrates') 2119``` 2120 2121 2122### on('mediaKeySystemInfoUpdate')<sup>11+</sup> 2123 2124on(type: 'mediaKeySystemInfoUpdate', callback: Callback\<Array\<drm.MediaKeySystemInfo>>): void 2125 2126监听mediaKeySystemInfoUpdate事件。 2127 2128**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2129 2130**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2131 2132**参数：** 2133 2134| 参数名 | 类型 | 必填 | 说明 | 2135| -------- | -------- | ---- | ------------------------------------------------------------ | 2136| type | string | 是 | 版权保护信息更新上报事件回调类型，支持的事件：'mediaKeySystemInfoUpdate'，当播放内容的版权保护信息更新时上报事件。 | 2137| callback | Callback\<Array\<drm.[MediaKeySystemInfo](../apis-drm-kit/js-apis-drm.md#mediakeysysteminfo)>> | 是 | 版权保护信息更新上报事件回调方法，上报MediaKeySystemInfo数组。 | 2138 2139**示例：** 2140 2141```ts 2142import { drm } from '@kit.DrmKit'; 2143 2144avPlayer.on('mediaKeySystemInfoUpdate', (mediaKeySystemInfo: Array<drm.MediaKeySystemInfo>) => { 2145 for (let i = 0; i < mediaKeySystemInfo.length; i++) { 2146 console.info('mediaKeySystemInfoUpdate happened uuid: ' + mediaKeySystemInfo[i]["uuid"]); 2147 console.info('mediaKeySystemInfoUpdate happened pssh: ' + mediaKeySystemInfo[i]["pssh"]); 2148 } 2149}) 2150``` 2151 2152### off('mediaKeySystemInfoUpdate')<sup>11+</sup> 2153 2154off(type: 'mediaKeySystemInfoUpdate', callback?: Callback\<Array\<drm.MediaKeySystemInfo>>): void; 2155 2156取消监听mediaKeySystemInfoUpdate事件。 2157 2158**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2159 2160**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2161 2162**参数：** 2163 2164| 参数名 | 类型 | 必填 | 说明 | 2165| ------ | ------ | ---- | ------------------------------------------------------------ | 2166| type | string | 是 | 版权保护信息更新上报事件回调类型，取消注册的事件：'mediaKeySystemInfoUpdate'。 | 2167| callback | Callback\<Array\<drm.[MediaKeySystemInfo](../apis-drm-kit/js-apis-drm.md#mediakeysysteminfo)>> | 否 | 版权保护信息更新上报事件回调方法，上报版权保护信息数组。如填写该参数，则仅取消注册此回调方法，否则取消注册mediaKeySystemInfoUpdate事件的所有回调方法。 | 2168 2169**示例：** 2170 2171```ts 2172avPlayer.off('mediaKeySystemInfoUpdate') 2173``` 2174 2175### setVolume<sup>9+</sup> 2176 2177setVolume(volume: number): void 2178 2179设置媒体播放音量，只能在prepared/playing/paused/completed状态调用，可以通过[volumeChange事件](#onvolumechange9)确认是否生效。 2180 2181**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2182 2183**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2184 2185**参数：** 2186 2187| 参数名 | 类型 | 必填 | 说明 | 2188| ------ | ------ | ---- | ------------------------------------------------------------ | 2189| volume | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 2190 2191**示例：** 2192 2193```ts 2194let volume: number = 1.0 2195avPlayer.setVolume(volume) 2196``` 2197 2198### on('volumeChange')<sup>9+</sup> 2199 2200on(type: 'volumeChange', callback: Callback\<number>): void 2201 2202监听setVolume生效的事件。 2203 2204**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2205 2206**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2207 2208**参数：** 2209 2210| 参数名 | 类型 | 必填 | 说明 | 2211| -------- | -------- | ---- | ------------------------------------------------------------ | 2212| type | string | 是 | setVolume生效的事件回调类型，支持的事件：'volumeChange'，每次调用setVolume后都会回调此事件。 | 2213| callback | Callback\<number> | 是 | setVolume生效的事件回调方法，上报生效的媒体音量。 | 2214 2215**示例：** 2216 2217```ts 2218avPlayer.on('volumeChange', (vol: number) => { 2219 console.info('volumeChange called,and new volume is :' + vol) 2220}) 2221``` 2222 2223### off('volumeChange')<sup>9+</sup> 2224 2225off(type: 'volumeChange', callback?: Callback\<number>): void 2226 2227取消监听setVolume生效的事件。 2228 2229**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2230 2231**参数：** 2232 2233| 参数名 | 类型 | 必填 | 说明 | 2234| ------ | ------ | ---- | ------------------------------------------------------------ | 2235| type | string | 是 | setVolume生效的事件回调类型，取消注册的事件：'volumeChange'。 | 2236| callback | Callback\<number> | 否 | setVolume生效的事件回调方法，上报生效的媒体音量。<br/>从API version 12开始支持此参数。 | 2237 2238**示例：** 2239 2240```ts 2241avPlayer.off('volumeChange') 2242``` 2243 2244### on('endOfStream')<sup>9+</sup> 2245 2246on(type: 'endOfStream', callback: Callback\<void>): void 2247 2248监听资源播放至结尾的事件；如果用户设置[loop](#属性)=true，播放会跳转至开头重播；如果用户没有设置loop，会通过[stateChange](#onstatechange9)上报completed状态。 2249 2250**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2251 2252**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2253 2254**参数：** 2255 2256| 参数名 | 类型 | 必填 | 说明 | 2257| -------- | -------- | ---- | ------------------------------------------------------------ | 2258| type | string | 是 | 资源播放至结尾的事件回调类型，支持的事件：'endOfStream'，当播放至结尾时会上报此事件。 | 2259| callback | Callback\<void> | 是 | 资源播放至结尾的事件回调方法。 | 2260 2261**示例：** 2262 2263```ts 2264avPlayer.on('endOfStream', () => { 2265 console.info('endOfStream called') 2266}) 2267``` 2268 2269### off('endOfStream')<sup>9+</sup> 2270 2271off(type: 'endOfStream', callback?: Callback\<void>): void 2272 2273取消监听资源播放至结尾的事件。 2274 2275**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2276 2277**参数：** 2278 2279| 参数名 | 类型 | 必填 | 说明 | 2280| ------ | ------ | ---- | ------------------------------------------------------------ | 2281| type | string | 是 | 资源播放至结尾的事件回调类型，取消注册的事件：'endOfStream'。 | 2282| callback | Callback\<void> | 否 | 资源播放至结尾的事件回调方法。<br/>从API version 12开始支持此参数。 | 2283 2284**示例：** 2285 2286```ts 2287avPlayer.off('endOfStream') 2288``` 2289 2290### on('timeUpdate')<sup>9+</sup> 2291 2292on(type: 'timeUpdate', callback: Callback\<number>): void 2293 2294监听资源播放当前时间，单位为毫秒（ms），用于刷新进度条当前位置，默认间隔100ms时间上报，因用户操作(seek)产生的时间变化会立刻上报。 2295 2296注：直播场景不支持timeUpdate上报。 2297 2298**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2299 2300**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2301 2302**参数：** 2303 2304| 参数名 | 类型 | 必填 | 说明 | 2305| -------- | -------- | ---- | ---------------------------------------------- | 2306| type | string | 是 | 时间更新的回调类型，支持的事件：'timeUpdate'。 | 2307| callback | Callback\<number> | 是 | 回调函数。返回当前时间。 | 2308 2309**示例：** 2310 2311```ts 2312avPlayer.on('timeUpdate', (time:number) => { 2313 console.info('timeUpdate called,and new time is :' + time) 2314}) 2315``` 2316 2317### off('timeUpdate')<sup>9+</sup> 2318 2319off(type: 'timeUpdate', callback?: Callback\<number>): void 2320 2321取消监听资源播放当前时间。 2322 2323**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2324 2325**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2326 2327**参数：** 2328 2329| 参数名 | 类型 | 必填 | 说明 | 2330| ------ | ------ | ---- | -------------------------------------------------- | 2331| type | string | 是 | 时间更新的回调类型，取消注册的事件：'timeUpdate'。 | 2332| callback | Callback\<number> | 否 | 回调函数。返回当前时间。<br/>从API version 12开始支持此参数。 | 2333 2334**示例：** 2335 2336```ts 2337avPlayer.off('timeUpdate') 2338``` 2339 2340### on('durationUpdate')<sup>9+</sup> 2341 2342 2343on(type: 'durationUpdate', callback: Callback\<number>): void 2344 2345监听资源播放资源的时长，单位为毫秒（ms），用于刷新进度条长度，默认只在prepared上报一次，同时允许一些特殊码流刷新多次时长。 2346注：直播场景不支持durationUpdate上报。 2347 2348**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2349 2350**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2351 2352**参数：** 2353 2354| 参数名 | 类型 | 必填 | 说明 | 2355| -------- | -------- | ---- | -------------------------------------------------- | 2356| type | string | 是 | 时长更新的回调类型，支持的事件：'durationUpdate'。 | 2357| callback | Callback\<number> | 是 | 回调函数。返回资源时长。 | 2358 2359**示例：** 2360 2361```ts 2362avPlayer.on('durationUpdate', (duration: number) => { 2363 console.info('durationUpdate called,new duration is :' + duration) 2364}) 2365``` 2366 2367### off('durationUpdate')<sup>9+</sup> 2368 2369off(type: 'durationUpdate', callback?: Callback\<number>): void 2370 2371取消监听资源播放资源的时长。 2372 2373**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2374 2375**参数：** 2376 2377| 参数名 | 类型 | 必填 | 说明 | 2378| ------ | ------ | ---- | ------------------------------------------------------ | 2379| type | string | 是 | 时长更新的回调类型，取消注册的事件：'durationUpdate'。 | 2380| callback | Callback\<number> | 否 | 回调函数。返回资源时长。<br/>从API version 12开始支持此参数。 | 2381 2382**示例：** 2383 2384```ts 2385avPlayer.off('durationUpdate') 2386``` 2387 2388### on('bufferingUpdate')<sup>9+</sup> 2389 2390on(type: 'bufferingUpdate', callback: OnBufferingUpdateHandler): void 2391 2392订阅音视频缓存更新事件，仅网络播放支持该订阅事件。 2393 2394**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2395 2396**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2397 2398**参数：** 2399 2400| 参数名 | 类型 | 必填 | 说明 | 2401| -------- | -------- | ---- | ------------------------------------------------------------ | 2402| type | string | 是 | 播放缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 2403| callback | [OnBufferingUpdateHandler](#onbufferingupdatehandler12) | 是 | 播放缓存事件回调方法。 | 2404 2405**示例：** 2406 2407```ts 2408avPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 2409 console.info('bufferingUpdate called,and infoType value is:' + infoType + ', value is :' + value) 2410}) 2411``` 2412 2413### off('bufferingUpdate')<sup>9+</sup> 2414 2415off(type: 'bufferingUpdate', callback?: OnBufferingUpdateHandler): void 2416 2417取消监听音视频缓存更新事件。 2418 2419**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2420 2421**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2422 2423**参数：** 2424 2425| 参数名 | 类型 | 必填 | 说明 | 2426| ------ | ------ | ---- | --------------------------------------------------------- | 2427| type | string | 是 | 播放缓存事件回调类型，取消注册的事件：'bufferingUpdate'。 | 2428| callback | [OnBufferingUpdateHandler](#onbufferingupdatehandler12) | 否 | 播放缓存事件回调方法。 | 2429 2430**示例：** 2431 2432```ts 2433avPlayer.off('bufferingUpdate') 2434``` 2435 2436### on('startRenderFrame')<sup>9+</sup> 2437 2438on(type: 'startRenderFrame', callback: Callback\<void>): void 2439 2440订阅视频播放开始首帧渲染的更新事件，仅视频播放支持该订阅事件，该事件仅代表播放服务将第一帧画面送显示模块，实际效果依赖显示服务渲染性能。 2441 2442**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2443 2444**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2445 2446**参数：** 2447 2448| 参数名 | 类型 | 必填 | 说明 | 2449| -------- | -------- | ---- | ------------------------------------------------------------ | 2450| type | string | 是 | 视频播放开始首帧渲染事件回调类型，支持的事件：'startRenderFrame'。 | 2451| callback | Callback\<void> | 是 | 视频播放开始首帧渲染事件回调方法。 | 2452 2453**示例：** 2454 2455```ts 2456avPlayer.on('startRenderFrame', () => { 2457 console.info('startRenderFrame called') 2458}) 2459``` 2460 2461### off('startRenderFrame')<sup>9+</sup> 2462 2463off(type: 'startRenderFrame', callback?: Callback\<void>): void 2464 2465取消监听视频播放开始首帧渲染的更新事件。 2466 2467**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2468 2469**参数：** 2470 2471| 参数名 | 类型 | 必填 | 说明 | 2472| ------ | ------ | ---- | ------------------------------------------------------------ | 2473| type | string | 是 | 视频播放开始首帧渲染事件回调类型，取消注册的事件：'startRenderFrame'。 | 2474| callback | Callback\<void> | 否 | 视频播放开始首帧渲染事件回调方法。<br/>从API version 12开始支持此参数。 | 2475 2476**示例：** 2477 2478```ts 2479avPlayer.off('startRenderFrame') 2480``` 2481 2482### on('videoSizeChange')<sup>9+</sup> 2483 2484on(type: 'videoSizeChange', callback: OnVideoSizeChangeHandler): void 2485 2486监听视频播放宽高变化事件，仅视频播放支持该订阅事件，默认只在prepared状态上报一次，但HLS协议码流会在切换分辨率时上报。 2487 2488**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2489 2490**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2491 2492**参数：** 2493 2494| 参数名 | 类型 | 必填 | 说明 | 2495| -------- | -------- | ---- | ------------------------------------------------------------ | 2496| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChange'。 | 2497| callback | [OnVideoSizeChangeHandler](#onvideosizechangehandler12) | 是 | 视频播放宽高变化事件回调方法。 | 2498 2499**示例：** 2500 2501```ts 2502avPlayer.on('videoSizeChange', (width: number, height: number) => { 2503 console.info('videoSizeChange called,and width is:' + width + ', height is :' + height) 2504}) 2505``` 2506 2507### off('videoSizeChange')<sup>9+</sup> 2508 2509off(type: 'videoSizeChange', callback?: OnVideoSizeChangeHandler): void 2510 2511取消监听视频播放宽高变化事件。 2512 2513**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2514 2515**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2516 2517**参数：** 2518 2519| 参数名 | 类型 | 必填 | 说明 | 2520| ------ | ------ | ---- | ------------------------------------------------------------ | 2521| type | string | 是 | 视频播放宽高变化事件回调类型，取消注册的事件：'videoSizeChange'。 | 2522| callback | [OnVideoSizeChangeHandler](#onvideosizechangehandler12) | 否 | 视频播放宽高变化事件回调方法。<br/>从API version 12开始支持此参数。 | 2523 2524**示例：** 2525 2526```ts 2527avPlayer.off('videoSizeChange') 2528``` 2529 2530### on('audioInterrupt')<sup>9+</sup> 2531 2532on(type: 'audioInterrupt', callback: Callback\<audio.InterruptEvent>): void 2533 2534监听音频焦点变化事件，多个音视频资源同时播放时，会根据音频焦点模型[audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9)触发此事件。应用需根据不同焦点变化事件作相应处理。具体可参考[处理音频焦点事件](../../media/audio/audio-playback-concurrency.md)。 2535 2536**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2537 2538**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2539 2540**参数：** 2541 2542| 参数名 | 类型 | 必填 | 说明 | 2543| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 2544| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 2545| callback | Callback\<[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)> | 是 | 音频焦点变化事件回调方法。 | 2546 2547**示例：** 2548 2549```ts 2550import { audio } from '@kit.AudioKit'; 2551 2552avPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 2553 console.info('audioInterrupt called,and InterruptEvent info is:' + info) 2554}) 2555``` 2556 2557### off('audioInterrupt')<sup>9+</sup> 2558 2559off(type: 'audioInterrupt', callback?: Callback<audio.InterruptEvent>): void 2560 2561取消监听音频焦点变化事件。 2562 2563**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2564 2565**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2566 2567**参数：** 2568 2569| 参数名 | 类型 | 必填 | 说明 | 2570| ------ | ------ | ---- | ------------------------------------------------------------ | 2571| type | string | 是 | 音频焦点变化事件回调类型，取消注册的事件：'audioInterrupt'。 | 2572| callback | Callback\<[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)> | 否 | 音频焦点变化事件回调方法。<br/>从API version 12开始支持此参数。 | 2573 2574**示例：** 2575 2576```ts 2577avPlayer.off('audioInterrupt') 2578``` 2579 2580### on('audioOutputDeviceChangeWithInfo')<sup>11+</sup> 2581 2582on(type: 'audioOutputDeviceChangeWithInfo', callback: Callback\<audio.AudioStreamDeviceChangeInfo>): void 2583 2584订阅监听音频流输出设备变化及原因，使用callback方式返回结果。 2585 2586在订阅此监听时，建议参考[响应音频流输出设备变更](../../media/audio/audio-output-device-change.md)自行实现设备连接或者断开时的播放器行为。 2587 2588**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2589 2590**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2591 2592**参数：** 2593 2594| 参数名 | 类型 | 必填 | 说明 | 2595| :------- | :------------------------- | :--- | :------------------------------------------ | 2596| type | string | 是 | 事件回调类型，支持的事件为：'outputDeviceChangeWithInfo'。 | 2597| callback | Callback\<[audio.AudioStreamDeviceChangeInfo](../apis-audio-kit/js-apis-audio.md#audiostreamdevicechangeinfo11)> | 是 | 回调函数，返回当前音频流的输出设备描述信息及变化原因。 | 2598 2599**错误码：** 2600 2601| 错误码ID | 错误信息 | 2602| -------- | ------------------------------------------ | 2603| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2604 2605**示例：** 2606 2607```ts 2608import { audio } from '@kit.AudioKit'; 2609 2610avPlayer.on('audioOutputDeviceChangeWithInfo', (data: audio.AudioStreamDeviceChangeInfo) => { 2611 console.info(`${JSON.stringify(data)}`); 2612}); 2613``` 2614 2615### off('audioOutputDeviceChangeWithInfo')<sup>11+</sup> 2616 2617off(type: 'audioOutputDeviceChangeWithInfo', callback?: Callback\<audio.AudioStreamDeviceChangeInfo>): void 2618 2619取消订阅监听音频流输出设备变化及原因，使用callback方式返回结果。 2620 2621**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2622 2623**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2624 2625**参数：** 2626 2627| 参数名 | 类型 | 必填 | 说明 | 2628| :------- | :------------------------- | :--- | :------------------------------------------ | 2629| type | string | 是 | 事件回调类型，支持的事件为：'outputDeviceChange'。 | 2630| callback | Callback\<[audio.AudioStreamDeviceChangeInfo](../apis-audio-kit/js-apis-audio.md#audiostreamdevicechangeinfo11)> | 否 | 回调函数，返回当前音频流的输出设备描述信息及变化原因。 | 2631 2632**错误码：** 2633 2634| 错误码ID | 错误信息 | 2635| -------- | ------------------------------------------ | 2636| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2637 2638**示例：** 2639 2640```ts 2641avPlayer.off('audioOutputDeviceChangeWithInfo'); 2642``` 2643 2644### addSubtitleFromFd<sup>12+</sup> 2645 2646addSubtitleFromFd(fd: number, offset?: number, length?: number): Promise\<void> 2647 2648依据fd为视频添加外挂字幕，当前仅支持与视频资源同时设置（在avplayer设置fdSrc视频资源后设置外挂字幕）。使用Promise方式返回结果。 2649 2650**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2651 2652**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2653 2654**参数：** 2655 2656| 参数名 | 类型 | 必填 | 说明 | 2657| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 2658| fd | number | 是 | 资源句柄，通过[resourceManager.getRawFd](../apis-localization-kit/js-apis-resource-manager.md#getrawfd9)获取。 | 2659| offset | number | 否 | 资源偏移量，需要基于预置资源的信息输入，非法值会造成字幕频资源解析错误，默认值:0。 | 2660| length | number | 否 | 资源长度，默认值为文件中从偏移量开始的剩余字节，需要基于预置资源的信息输入，非法值会造成字幕频资源解析错误，默认值:0。 | 2661 2662**返回值：** 2663 2664| 类型 | 说明 | 2665| -------------- | ------------------------------------------ | 2666| Promise\<void> | 添加外挂字幕addSubtitleFromFd方法的Promise返回值。 | 2667 2668**错误码：** 2669 2670| 错误码ID | 错误信息 | 2671| -------- | ------------------------------------------ | 2672| 401 | The parameter check failed. Return by promise. | 2673| 5400102 | Operation not allowed. Return by promise. | 2674 2675**示例：** 2676 2677<!--code_no_check--> 2678```ts 2679import { common } from '@kit.AbilityKit' 2680 2681private context: Context | undefined; 2682constructor(context: Context) { 2683 this.context = context; // this.getUIContext().getHostContext(); 2684} 2685let fileDescriptor = await this.context.resourceManager.getRawFd('xxx.srt'); 2686 2687avPlayer.addSubtitleFromFd(fileDescriptor.fd, fileDescriptor.offset, fileDescriptor.length) 2688``` 2689 2690### addSubtitleFromUrl<sup>12+</sup> 2691 2692addSubtitleFromUrl(url: string): Promise\<void> 2693 2694依据url为视频添加外挂字幕，当前仅支持与视频资源同时设置（在avplayer设置fdSrc视频资源后设置外挂字幕）。使用Promise方式返回结果。 2695 2696**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2697 2698**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2699 2700**参数：** 2701 2702| 参数名 | 类型 | 必填 | 说明 | 2703| ------ | ------ | ---- | ------------------------------------------------------------ | 2704| url | string | 是 | 外挂字幕文件地址。 | 2705 2706**返回值：** 2707 2708| 类型 | 说明 | 2709| -------------- | ------------------------------------------ | 2710| Promise\<void> | 添加外挂字幕addSubtitleFromUrl方法的Promise返回值。 | 2711 2712**错误码：** 2713 2714| 错误码ID | 错误信息 | 2715| -------- | ------------------------------------------ | 2716| 401 | The parameter check failed. Return by promise. | 2717| 5400102 | Operation not allowed. Return by promise. | 2718 2719**示例：** 2720 2721<!--code_no_check--> 2722```ts 2723let fdUrl:string = 'http://xxx.xxx.xxx/xx/index.srt' 2724 2725let avPlayer: media.AVPlayer = await media.createAVPlayer() 2726avPlayer.addSubtitleFromUrl(fdUrl) 2727``` 2728 2729### on('subtitleUpdate')<sup>12+</sup> 2730 2731on(type: 'subtitleUpdate', callback: Callback\<SubtitleInfo>): void 2732 2733订阅获取外挂字幕的事件，当有外挂字幕时，会通过订阅的回调方法通知用户。用户只能订阅一个外挂字幕事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2734 2735**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2736 2737**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2738 2739**参数：** 2740 2741| 参数名 | 类型 | 必填 | 说明 | 2742| -------- | -------- | ---- | ------------------------------------------------------------ | 2743| type | string | 是 | 事件回调类型，支持的事件为：'subtitleUpdate'。 | 2744| callback | function | 是 | 外挂字幕事件回调方法。 | 2745 2746**示例：** 2747 2748```ts 2749avPlayer.on('subtitleUpdate', async (info: media.SubtitleInfo) => { 2750 if (info) { 2751 let text = (!info.text) ? '' : info.text 2752 let startTime = (!info.startTime) ? 0 : info.startTime 2753 let duration = (!info.duration) ? 0 : info.duration 2754 console.info('subtitleUpdate info: text=' + text + ' startTime=' + startTime +' duration=' + duration) 2755 } else { 2756 console.info('subtitleUpdate info is null') 2757 } 2758}) 2759``` 2760 2761### off('subtitleUpdate')<sup>12+</sup> 2762 2763off(type: 'subtitleUpdate', callback?: Callback\<SubtitleInfo>): void 2764 2765取消订阅获取外挂字幕的事件。 2766 2767**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2768 2769**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2770 2771**参数：** 2772 2773| 参数名 | 类型 | 必填 | 说明 | 2774| -------- | -------- | ---- | ------------------------------------------------------------ | 2775| type | string | 是 | 事件回调类型，支持的事件为：'subtitleUpdate'。 | 2776| callback | function | 否 | 取消外挂字幕事件的回调方法。 | 2777 2778**示例：** 2779 2780```ts 2781avPlayer.off('subtitleUpdate') 2782``` 2783 2784### on('trackChange')<sup>12+</sup> 2785 2786on(type: 'trackChange', callback: OnTrackChangeHandler): void 2787 2788订阅获取轨道变更的事件，当播放的轨道变更时，会通过订阅的回调方法通知用户。用户只能订阅一个轨道变更事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2789 2790**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2791 2792**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2793 2794**参数：** 2795 2796| 参数名 | 类型 | 必填 | 说明 | 2797| -------- | -------- | ---- | ------------------------------------------------------------ | 2798| type | string | 是 | 事件回调类型，支持的事件为：'trackChange'。 | 2799| callback | [OnTrackChangeHandler](#ontrackchangehandler12) | 是 | 轨道变更事件回调方法。 | 2800 2801**示例：** 2802 2803```ts 2804avPlayer.on('trackChange', (index: number, isSelect: boolean) => { 2805 console.info('trackChange info: index=' + index + ' isSelect=' + isSelect) 2806}) 2807``` 2808 2809### off('trackChange')<sup>12+</sup> 2810 2811off(type: 'trackChange', callback?: OnTrackChangeHandler): void 2812 2813取消订阅获取轨道变更的事件。 2814 2815**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2816 2817**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2818 2819**参数：** 2820 2821| 参数名 | 类型 | 必填 | 说明 | 2822| -------- | -------- | ---- | ------------------------------------------------------------ | 2823| type | string | 是 | 事件回调类型，支持的事件为：'trackChange'。 | 2824| callback | [OnTrackChangeHandler](#ontrackchangehandler12) | 否 | 取消轨道变更事件的回调方法。 | 2825 2826**示例：** 2827 2828```ts 2829avPlayer.off('trackChange') 2830``` 2831 2832### on('trackInfoUpdate')<sup>12+</sup> 2833 2834on(type: 'trackInfoUpdate', callback: Callback\<Array\<MediaDescription>>): void 2835 2836订阅获取轨道信息更新的事件，当播放的轨道有更新时，会通过订阅的回调方法通知用户。用户只能订阅一个轨道变更事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2837 2838**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2839 2840**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2841 2842**参数：** 2843 2844| 参数名 | 类型 | 必填 | 说明 | 2845| -------- | -------- | ---- | ------------------------------------------------------------ | 2846| type | string | 是 | 事件回调类型，支持的事件为：'trackInfoUpdate'。 | 2847| callback | Callback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 轨道信息更新事件回调方法。 | 2848 2849**示例：** 2850 2851```ts 2852avPlayer.on('trackInfoUpdate', (info: Array<media.MediaDescription>) => { 2853 if (info) { 2854 for (let i = 0; i < info.length; i++) { 2855 let propertyIndex: Object = info[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 2856 let propertyType: Object = info[i][media.MediaDescriptionKey.MD_KEY_TRACK_TYPE]; 2857 console.info('track info: index=' + propertyIndex + ' tracktype=' + propertyType) 2858 } 2859 } else { 2860 console.info('track info is null') 2861 } 2862}) 2863``` 2864 2865### off('trackInfoUpdate')<sup>12+</sup> 2866 2867off(type: 'trackInfoUpdate', callback?: Callback\<Array\<MediaDescription>>): void 2868 2869取消订阅获取轨道变更的事件。 2870 2871**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2872 2873**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2874 2875**参数：** 2876 2877| 参数名 | 类型 | 必填 | 说明 | 2878| -------- | -------- | ---- | ------------------------------------------------------------ | 2879| type | string | 是 | 事件回调类型，支持的事件为：'trackInfoUpdate'。 | 2880| callback | Callback\<Array\<[MediaDescription](#mediadescription8)>> | 否 | 取消轨道信息更新事件的回调方法。 | 2881 2882**示例：** 2883 2884```ts 2885avPlayer.off('trackInfoUpdate') 2886``` 2887 2888### on('amplitudeUpdate')<sup>13+</sup> 2889 2890on(type: 'amplitudeUpdate', callback: Callback\<Array\<number>>): void 2891 2892订阅音频最大电平值，音频资源播放时定时上报。 2893 2894**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2895 2896**参数：** 2897 2898| 参数名 | 类型 | 必填 | 说明 | 2899| -------- | -------- | ---- | ------------------------------------------------------------ | 2900| type | string | 是 | 事件回调类型，支持的事件为：'amplitudeUpdate'。 | 2901| callback | Callback\<Array\<number>> | 是 | 音频最大电平值更新事件回调方法。 | 2902 2903**示例：** 2904 2905```ts 2906avPlayer.on('amplitudeUpdate', (value: Array<number>) => { 2907 console.info('amplitudeUpdate called,and amplitudeUpdate = ${value}') 2908}) 2909``` 2910 2911### off('amplitudeUpdate')<sup>13+</sup> 2912 2913off(type: 'amplitudeUpdate', callback?: Callback\<Array\<number>>): void 2914 2915取消订阅获取音频最大电平值事件。 2916 2917**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2918 2919**参数：** 2920 2921| 参数名 | 类型 | 必填 | 说明 | 2922| ------ | ------ | ---- | ------------------------------------------------------------ | 2923| type | string | 是 | 事件回调类型，支持的事件为：'amplitudeUpdate'。 | 2924| callback | Callback\<Array\<number>> | 否 | 取消音频最大电平值更新事件回调方法。 | 2925 2926**示例：** 2927 2928```ts 2929avPlayer.off('amplitudeUpdate') 2930``` 2931 2932### on('seiMessageReceived')<sup>18+</sup> 2933 2934on(type: 'seiMessageReceived', payloadTypes: Array\<number>, callback: OnSeiMessageHandle): void 2935 2936订阅获取SEI信息事件，仅适用于HTTP-FLV直播，视频流中包含SEI信息时上报。需在prepare之前订阅，当用户重复订阅时，以最后一次订阅的回调接口为准。 2937 2938**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2939 2940**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2941 2942**参数：** 2943 2944| 参数名 | 类型 | 必填 | 说明 | 2945| -------- | -------- | ---- | ------------------------------------------------------------ | 2946| type | string | 是 | 事件回调类型，支持的事件为：'seiMessageReceived'。 | 2947| payloadTypes | Array\<number> | 是 | SEI信息的订阅负载类型数组。当前仅支持负载类型为5，即payloadType = 5。| 2948| callback | [OnSeiMessageHandle](#onseimessagehandle18) | 是 | 用于监听SEI信息事件的回调函数，接收订阅的负载类型。 | 2949 2950**示例：** 2951 2952```ts 2953import util from '@ohos.util'; 2954 2955avPlayer.on('seiMessageReceived', [5], (messages: Array<media.SeiMessage>, playbackPosition?: number) => 2956{ 2957 console.info('seiMessageReceived playbackPosition ' + playbackPosition) 2958 2959 for (let key = 0; key < messages.length; key++) { 2960 console.info('seiMessageReceived messages payloadType ' + messages[key].payloadType + ' payload size ' + messages[key].payload.byteLength) 2961 2962 let textDecoder = util.TextDecoder.create("utf-8",{ignoreBOM: true}) 2963 let ab = messages[key]?.payload?.slice(16, messages[key].payload.byteLength) 2964 let result: Uint8Array = new Uint8Array(ab) 2965 let retStr: string = textDecoder.decodeToString(result) 2966 console.info('seiMessageReceived messages payload ' + retStr) 2967 } 2968}); 2969``` 2970 2971### off('seiMessageReceived')<sup>18+</sup> 2972 2973off(type: 'seiMessageReceived', payloadTypes?: Array\<number>, callback?: OnSeiMessageHandle): void 2974 2975取消订阅获取SEI信息事件。 2976 2977**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 2978 2979**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2980 2981**参数：** 2982 2983| 参数名 | 类型 | 必填 | 说明 | 2984| ------ | ------ | ---- | ------------------------------------------------------------ | 2985| type | string | 是 | 事件回调类型，支持的事件为：'seiMessageReceived'。 | 2986| payloadTypes | Array\<number> | 否 | SEI信息的订阅负载类型。 | 2987| callback | [OnSeiMessageHandle](#onseimessagehandle18) | 否 | 用于监听SEI信息事件的回调函数，接收订阅的负载类型。 | 2988 2989**示例：** 2990 2991```ts 2992avPlayer.off('seiMessageReceived') 2993``` 2994 2995### setSuperResolution<sup>18+</sup> 2996 2997setSuperResolution(enabled: boolean) : Promise\<void> 2998 2999动态开启/关闭超分算法，可以在 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' 状态调用。使用Promise方式返回结果。 3000 3001在调用[prepare()](#prepare9)前先通过[PlaybackStrategy](#playbackstrategy12)使能超分。 3002 3003**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3004 3005**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3006 3007**参数：** 3008 3009| 参数名 | 类型 | 必填 | 说明 | 3010| ------ | ------ | ---- | ------------------------------------------------------------ | 3011| enabled | boolean | 是 | 表示是否开启超分。true表示开启超分，false表示关闭超分。 | 3012 3013**返回值：** 3014 3015| 类型 | 说明 | 3016| -------------- | ------------------------------------------ | 3017| Promise\<void> | 开启/关闭超分setSuperResolution方法的Promise返回值。 | 3018 3019**错误码：** 3020 3021以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3022 3023| 错误码ID | 错误信息 | 3024| -------- | ------------------------------------------ | 3025| 5400102 | Operation not allowed. Return by promise. | 3026| 5410003 | Super-resolution not supported. Return by promise. | 3027| 5410004 | Missing enable super-resolution feature in [PlaybackStrategy](#playbackstrategy12). Return by promise. | 3028 3029**示例：** 3030 3031```ts 3032avPlayer.setSuperResolution(true) 3033``` 3034 3035### setVideoWindowSize<sup>18+</sup> 3036 3037setVideoWindowSize(width: number, height: number) : Promise\<void> 3038 3039动态设置超分算法的输出分辨率，可以在 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' 状态调用。使用Promise方式返回结果。输入参数须在 320x320 ~ 1920x1080 范围内，单位为像素。 3040 3041在调用[prepare()](#prepare9)前先通过[PlaybackStrategy](#playbackstrategy12)使能超分。 3042 3043**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3044 3045**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3046 3047**参数：** 3048 3049| 参数名 | 类型 | 必填 | 说明 | 3050| ------ | ------ | ---- | ------------------------------------------------------------ | 3051| width | number | 是 | 超分算法的目标输出视频宽度，取值范围为[320-1920]，单位为像素。 | 3052| height | number | 是 | 超分算法的目标输出视频高度，取值范围为[320-1080]，单位为像素。 | 3053 3054**返回值：** 3055 3056| 类型 | 说明 | 3057| -------------- | ------------------------------------------ | 3058| Promise\<void> | 配置超分目标输出分辨率setVideoWindowSize方法的Promise返回值。 | 3059 3060**错误码：** 3061 3062以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体错误码](errorcode-media.md)。 3063 3064| 错误码ID | 错误信息 | 3065| -------- | ------------------------------------------ | 3066| 401 | Parameter error. Return by promise. | 3067| 5400102 | Operation not allowed. Return by promise. | 3068| 5410003 | Super-resolution not supported. Return by promise. | 3069| 5410004 | Missing enable super-resolution feature in [PlaybackStrategy](#playbackstrategy12). Return by promise. | 3070 3071**示例：** 3072 3073```ts 3074avPlayer.setVideoWindowSize(1920, 1080) 3075``` 3076 3077### on('superResolutionChanged')<sup>18+</sup> 3078 3079on(type:'superResolutionChanged', callback: OnSuperResolutionChanged): void 3080 3081订阅监听超分算法开启/关闭事件。 3082 3083**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3084 3085**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3086 3087**参数：** 3088 3089| 参数名 | 类型 | 必填 | 说明 | 3090| -------- | -------- | ---- | ------------------------------------------------------------ | 3091| type | string | 是 | 事件回调类型，支持的事件为：'superResolutionChanged'，当超分算法开启/关闭状态变化时，触发该事件。 | 3092| callback | [OnSuperResolutionChanged](#onsuperresolutionchanged-18) | 是 | 超分开关事件回调方法。 | 3093 3094**示例：** 3095 3096```ts 3097avPlayer.on('superResolutionChanged', (enabled: boolean) => { 3098 console.info('superResolutionChanged called, and enabled is:' + enabled) 3099}) 3100``` 3101 3102### off('superResolutionChanged')<sup>18+</sup> 3103 3104off(type:'superResolutionChanged', callback?: OnSuperResolutionChanged): void 3105 3106取消监听超分算法开启/关闭事件。 3107 3108**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3109 3110**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3111 3112**参数：** 3113 3114| 参数名 | 类型 | 必填 | 说明 | 3115| -------- | -------- | ---- | ------------------------------------------------------------ | 3116| type | string | 是 | 事件回调类型，支持的事件为：'superResolutionChanged'，当超分算法开启/关闭状态变化时，触发该事件。 | 3117| callback | [OnSuperResolutionChanged](#onsuperresolutionchanged-18) | 否 | 超分开关事件回调方法。 | 3118 3119**示例：** 3120 3121```ts 3122avPlayer.off('superResolutionChanged') 3123``` 3124 3125## AVPlayerState<sup>9+</sup> 3126 3127type AVPlayerState = 'idle' | 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' | 'released' | 'error' 3128 3129[AVPlayer](#avplayer9)的状态机，可通过state属性主动获取当前状态，也可通过监听[stateChange](#onstatechange9)事件上报当前状态，状态机之间的切换规则，可参考[音频播放开发指导](../../media/media/using-avplayer-for-playback.md)。 3130 3131**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3132 3133**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3134 3135| 类型 | 说明 | 3136| :-----------------------------: | :----------------------------------------------------------- | 3137| '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属性会被重置，其他用户设置的属性将被保留。 | 3138| 'initialized' | 资源初始化，在idle 状态设置 url<sup>9+</sup> 或 fdSrc<sup>9+</sup>属性，AVPlayer会进入initialized状态，此时可以配置窗口、音频等静态属性。 | 3139| 'prepared' | 已准备状态，在initialized状态调用[prepare()](#prepare9)方法，AVPlayer会进入prepared状态，此时播放引擎的资源已准备就绪。 | 3140| 'playing' | 正在播放状态，在prepared/paused/completed状态调用[play()](#play9)方法，AVPlayer会进入playing状态。 | 3141| 'paused' | 暂停状态，在playing状态调用pause方法，AVPlayer会进入paused状态。 | 3142| 'completed' | 播放至结尾状态，当媒体资源播放至结尾时，如果用户未设置循环播放（loop = true），AVPlayer会进入completed状态，此时调用[play()](#play9)会进入playing状态和重播，调用[stop()](#stop9)会进入stopped状态。 | 3143| 'stopped' | 停止状态，在prepared/playing/paused/completed状态调用[stop()](#stop9)方法，AVPlayer会进入stopped状态，此时播放引擎只会保留属性，但会释放内存资源，可以调用[prepare()](#prepare9)重新准备，也可以调用[reset()](#reset9)重置，或者调用[release()](#release9)彻底销毁。 | 3144| 'released' | 销毁状态，销毁与当前AVPlayer关联的播放引擎，无法再进行状态转换，调用[release()](#release9)方法后，会进入released状态，结束流程。 | 3145| '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：播放过程发现码流问题，导致容器、解码短暂异常，不影响连续播放和播控操作的，不需要客户端设计容错机制。 | 3146 3147## OnTrackChangeHandler<sup>12+</sup> 3148 3149type OnTrackChangeHandler = (index: number, isSelected: boolean) => void 3150 3151track变更事件回调方法。 3152 3153**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3154 3155**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3156 3157| 参数名 | 类型 | 必填 | 说明 | 3158| ------ | ------ | ------ | ---------------------------------------------------------- | 3159| index | number | 是 | 当前选中的track索引。 | 3160| isSelected | boolean | 是 | 当前索引的选中状态。 | 3161 3162## OnAVPlayerStateChangeHandle<sup>12+</sup> 3163 3164type OnAVPlayerStateChangeHandle = (state: AVPlayerState, reason: StateChangeReason) => void 3165 3166状态机切换事件回调方法。 3167 3168**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3169 3170**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3171 3172| 参数名 | 类型 | 必填 | 说明 | 3173| ------ | ------ | ------ | ---------------------------------------------------------- | 3174| state | [AVPlayerState](#avplayerstate9) | 是 | 当前播放状态。 | 3175| reason | [StateChangeReason](#statechangereason9) | 是 | 当前播放状态的切换原因。 | 3176 3177## OnBufferingUpdateHandler<sup>12+</sup> 3178 3179type OnBufferingUpdateHandler = (infoType: BufferingInfoType, value: number) => void 3180 3181播放缓存事件回调方法。 3182 3183**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3184 3185**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3186 3187| 参数名 | 类型 | 必填 | 说明 | 3188| ------ | ------ | ------ | ------------------------------------------------------------ | 3189| infoType | [BufferingInfoType](#bufferinginfotype8) | 是 | 缓存时间类型。 | 3190| value | number | 是 | value值固定为0。 | 3191 3192## OnVideoSizeChangeHandler<sup>12+</sup> 3193 3194type OnVideoSizeChangeHandler = (width: number, height: number) => void 3195 3196视频播放宽高变化事件回调方法。 3197 3198**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3199 3200**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3201 3202| 参数名 | 类型 | 必填 | 说明 | 3203| ------ | ------ | ------ | ------------------------------------------------------------ | 3204| width | number | 是 | 视频宽度，单位为像素（px）。| 3205| height | number | 是 | 视频高度，单位为像素（px）。| 3206 3207## OnSeiMessageHandle<sup>18+</sup> 3208 3209type OnSeiMessageHandle = (messages: Array\<SeiMessage>, playbackPosition?: number) => void 3210 3211获取SEI信息，使用场景：订阅SEI信息事件，回调返回SEI详细信息。 3212 3213**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3214 3215**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3216 3217**参数：** 3218 3219| 参数名 | 类型 | 必填 | 说明 | 3220| ------ | ------ | ---- | ------------------------------------------------------------ | 3221| messages | Array\<[SeiMessage](#seimessage18)> | 是 | SEI信息。 | 3222| playbackPosition | number | 否 | 获取当前播放位置（单位：毫秒）。 | 3223 3224## OnSuperResolutionChanged <sup>18+</sup> 3225 3226type OnSuperResolutionChanged = (enabled: boolean) => void 3227 3228视频超分开关事件回调方法。若通过[PlaybackStrategy](#playbackstrategy12)正确使能超分，超分算法状态变化时会通过此回调上报，视频起播时也会上报超分初始开启/关闭状态。若未使能超分，不会触发该回调。 3229 3230出现以下两种情况，超分算法会自动关闭。 3231* 目前超分算法最高仅支持30帧及以下的视频。若视频帧率超过30帧，或者在倍速播放等场景下导致输入帧率超出超分算法处理能力，超分会自动关闭。 3232* 目前超分算法支持输入分辨率范围为320x320 ~ 1920x1080，单位为像素。若播放过程中输入视频分辨率超出此范围，超分算法会自动关闭。 3233 3234**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3235 3236**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3237 3238| 参数名 | 类型 | 必填 | 说明 | 3239| ------ | ------ | ------ | ------------------------------------------------------------ | 3240| enabled | boolean | 是 | 表示当前超分是否开启。true表示超分开启，false表示超分关闭。 | 3241 3242## AVFileDescriptor<sup>9+</sup> 3243 3244音视频文件资源描述，一种特殊资源的播放方式，使用场景：应用中的音频资源被连续存储在同一个文件中，需要根据偏移量和长度进行播放。 3245 3246**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3247 3248**系统能力：** SystemCapability.Multimedia.Media.Core 3249 3250| 名称 | 类型 | 必填 | 说明 | 3251| ------ | ------ | ---- | ------------------------------------------------------------ | 3252| 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)获取。 | 3253| offset | number | 否 | 资源偏移量，默认值为0，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 3254| length | number | 否 | 资源长度，默认值为文件中从偏移量开始的剩余字节，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 3255 3256## AVDataSrcDescriptor<sup>10+</sup> 3257 3258音视频文件资源描述，用于DataSource播放方式，使用场景：应用在未获取完整音视频资源时，允许用户创建播放实例并开始播放，达到提前播放的目的。 3259 3260**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3261 3262**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 3263 3264| 名称 | 类型 | 必填 | 说明 | 3265| ------ | ------ | ---- | ------------------------------------------------------------ | 3266| fileSize | number | 是 | 待播放文件大小（字节），-1代表大小未知。如果fileSize设置为-1, 播放模式类似于直播，不能进行seek及setSpeed操作，不能设置loop属性，因此不能重新播放。 | 3267| 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表示遇到不可恢复的错误。| 3268 3269## SubtitleInfo<sup>12+</sup> 3270 3271外挂字幕信息，使用场景：订阅外挂字幕事件，回调返回外挂字幕详细信息。 3272 3273**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3274 3275**系统能力：** SystemCapability.Multimedia.Media.Core 3276 3277| 名称 | 类型 | 必填 | 说明 | 3278| ------ | ------ | ---- | ------------------------------------------------------------ | 3279| text | string | 否 | 字幕文本信息。 | 3280| startTime | number | 否 | 显示当前字幕文本的开始时间（单位：毫秒）。 | 3281| duration | number | 否 | 显示当前字幕文本的持续时间（单位：毫秒）。 | 3282 3283## SeiMessage<sup>18+</sup> 3284 3285SEI信息内容，描述SEI信息的负载类型和数据。 3286 3287**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 3288 3289**系统能力：** SystemCapability.Multimedia.Media.Core 3290 3291| 名称 | 类型 | 只读 | 可选 | 说明 | 3292| ------ | ------ | ---- | ---- | ------------------------------------------------------------ | 3293| payloadType | number | 否 | 否 | SEI信息的负载类型。 | 3294| payload | ArrayBuffer | 否 | 否 | SEI信息的负载数据。 | 3295 3296## SeekMode<sup>8+</sup> 3297 3298视频播放的Seek模式枚举，可通过seek方法作为参数传递下去。 3299 3300**系统能力：** SystemCapability.Multimedia.Media.Core 3301 3302| 名称 | 值 | 说明 | 3303| -------------- | ---- | ------------------------------------------------------------ | 3304| SEEK_NEXT_SYNC | 0 | 表示跳转到指定时间点的下一个关键帧，建议向后快进的时候用这个枚举值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 3305| SEEK_PREV_SYNC | 1 | 表示跳转到指定时间点的上一个关键帧，建议向前快进的时候用这个枚举值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 3306| SEEK_CLOSEST<sup>12+</sup> | 2 | 表示跳转到距离指定时间点最近的帧，建议精准跳转进度的时候用这个枚举值。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3307| 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开始，该接口支持在原子化服务中使用。 | 3308 3309## SwitchMode<sup>12+</sup> 3310 3311视频播放的selectTrack模式枚举，可通过selectTrack方法作为参数传递下去，当前仅DASH协议视频轨支持该扩展参数。 3312 3313**系统能力：** SystemCapability.Multimedia.Media.Core 3314 3315| 名称 | 值 | 说明 | 3316| -------------- | ---- | ------------------------------------------------------------ | 3317| SMOOTH | 0 | 表示切换后视频平滑播放，该模式切换存在延迟，不会立即生效。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3318| SEGMENT | 1 | 表示切换后从当前分片开始位置播放，该模式立即切换，会有重复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3319| CLOSEST | 2 | 表示从距离当前播放时间点最近的帧开始播放，该模式立即切换，切换后会卡住3到5s，然后恢复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3320 3321## PlaybackSpeed<sup>8+</sup> 3322 3323视频播放的倍速枚举，可通过setSpeed方法作为参数传递下去。 3324 3325**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3326 3327**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 3328 3329| 名称 | 值 | 说明 | 3330| -------------------- | ---- | ------------------------------ | 3331| SPEED_FORWARD_0_75_X | 0 | 表示视频播放正常播速的0.75倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3332| SPEED_FORWARD_1_00_X | 1 | 表示视频播放正常播速。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3333| SPEED_FORWARD_1_25_X | 2 | 表示视频播放正常播速的1.25倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3334| SPEED_FORWARD_1_75_X | 3 | 表示视频播放正常播速的1.75倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3335| SPEED_FORWARD_2_00_X | 4 | 表示视频播放正常播速的2.00倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3336| SPEED_FORWARD_0_50_X<sup>12+</sup> | 5 | 表示视频播放正常播速的0.50倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3337| SPEED_FORWARD_1_50_X<sup>12+</sup> | 6 | 表示视频播放正常播速的1.50倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3338| SPEED_FORWARD_3_00_X<sup>13+</sup> | 7 | 表示视频播放正常播速的3.00倍。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 3339| SPEED_FORWARD_0_25_X<sup>12+</sup> | 8 | 表示视频播放正常播速的0.25倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3340| SPEED_FORWARD_0_125_X<sup>12+</sup> | 9 | 表示视频播放正常播速的0.125倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 3341 3342## VideoScaleType<sup>9+</sup> 3343 3344枚举，视频缩放模式。 3345 3346**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 3347 3348**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 3349 3350| 名称 | 值 | 说明 | 3351| ------------------------- | ---- | ------------------------------------------------ | 3352| VIDEO_SCALE_TYPE_FIT | 0 | 默认比例类型，视频拉伸至与窗口等大。 | 3353| VIDEO_SCALE_TYPE_FIT_CROP | 1 | 保持视频宽高比拉伸至填满窗口，内容可能会有裁剪。 | 3354 3355## MediaDescription<sup>8+</sup> 3356 3357通过key-value方式获取媒体信息。 3358 3359**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 3360 3361**系统能力：** SystemCapability.Multimedia.Media.Core 3362 3363| 名称 | 类型 | 必填 | 说明 | 3364| ------------- | ------ | ---- | ------------------------------------------------------------ | 3365| [key: string] | Object | 是 | 该键值对支持的key取值范围，请参考[MediaDescriptionKey](#mediadescriptionkey8);每个key值的Object类型和范围，请参考[MediaDescriptionKey](#mediadescriptionkey8)对应Key值的说明 | 3366 3367**示例：** 3368 3369```ts 3370import { BusinessError } from '@kit.BasicServicesKit'; 3371 3372function printfItemDescription(obj: media.MediaDescription, key: string) { 3373 let property: Object = obj[key]; 3374 console.info('audio key is ' + key); // 通过key值获取对应的value。key值具体可见[MediaDescriptionKey]。 3375 console.info('audio value is ' + property); //对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[MediaDescriptionKey]。 3376} 3377 3378let avPlayer: media.AVPlayer | undefined = undefined; 3379media.createAVPlayer((err: BusinessError, player: media.AVPlayer) => { 3380 if(player != null) { 3381 avPlayer = player; 3382 console.info(`Succeeded in creating AVPlayer`); 3383 avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 3384 if (arrList != null) { 3385 for (let i = 0; i < arrList.length; i++) { 3386 printfItemDescription(arrList[i], media.MediaDescriptionKey.MD_KEY_TRACK_TYPE); //打印出每条轨道MD_KEY_TRACK_TYPE的值。 3387 } 3388 } else { 3389 console.error(`Failed to get TrackDescription, error:${error}`); 3390 } 3391 }); 3392 } else { 3393 console.error(`Failed to create AVPlayer, error message:${err.message}`); 3394 } 3395}); 3396``` 3397 3398## PlaybackInfo<sup>12+</sup> 3399 3400通过key-value方式获取播放信息。 3401 3402**系统能力：** SystemCapability.Multimedia.Media.Core 3403 3404| 名称 | 类型 | 必填 | 说明 | 3405| ------------- | ------ | ---- | ------------------------------------------------------------ | 3406| [key: string] | Object | 是 | 该键值对支持的key取值范围，请参考[PlaybackInfoKey](#playbackinfokey12);每个key值的Object类型和范围，请参考[PlaybackInfoKey](#playbackinfokey12)对应Key值的说明。 | 3407 3408**示例：** 3409 3410```ts 3411import { BusinessError } from '@kit.BasicServicesKit'; 3412 3413function printfPlaybackInfo(obj: media.PlaybackInfo, key: string) { 3414 let property: Object = obj[key]; 3415 console.info('key is ' + key); // 通过key值获取对应的value。key值具体可见[PlaybackInfoKey]。 3416 console.info('value is ' + property); //对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[PlaybackInfoKey]。 3417} 3418 3419let avPlayer: media.AVPlayer | undefined = undefined; 3420let playbackInfo: media.PlaybackInfo | undefined = undefined; 3421media.createAVPlayer(async (err: BusinessError, player: media.AVPlayer) => { 3422 if (player != null) { 3423 avPlayer = player; 3424 console.info(`Succeeded in creating AVPlayer`); 3425 if (avPlayer) { 3426 try { 3427 playbackInfo = await avPlayer.getPlaybackInfo(); 3428 console.info(`AVPlayer getPlaybackInfo = ${JSON.stringify(playbackInfo)}`); // 打印整个PlaybackInfo的值。 3429 printfPlaybackInfo(playbackInfo, media.PlaybackInfoKey.SERVER_IP_ADDRESS); // 打印ip的值。 3430 } catch (error) { 3431 console.error(`error = ${error}`); 3432 } 3433 } 3434 } else { 3435 console.error(`Failed to create AVPlayer, error message:${err.message}`); 3436 } 3437}); 3438``` 3439 3440## AVRecorder<sup>9+</sup> 3441 3442音视频录制管理类，用于音视频媒体录制。在调用AVRecorder的方法前，需要先通过[createAVRecorder()](#mediacreateavrecorder9)构建一个AVRecorder实例。 3443 3444音视频录制demo可参考：[音频录制开发指导](../../media/media/using-avrecorder-for-recording.md)、[视频录制开发指导](../../media/media/video-recording.md)。 3445 3446> **说明：** 3447> 3448> 使用相机进行视频录制时，需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/js-apis-camera.md)。 3449 3450### 属性 3451 3452**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3453 3454| 名称 | 类型 | 只读 | 可选 | 说明 | 3455| ------- | ------------------------------------ | ---- | ---- | ------------------ | 3456| state9+ | [AVRecorderState](#avrecorderstate9) | 是 | 否 | 音视频录制的状态。<br>**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 3457 3458### prepare<sup>9+</sup> 3459 3460prepare(config: AVRecorderConfig, callback: AsyncCallback\<void>): void 3461 3462异步方式进行音视频录制的参数设置。通过注册回调函数获取返回值。 3463 3464**需要权限：** ohos.permission.MICROPHONE 3465 3466不涉及音频录制时，可以不需要获取ohos.permission.MICROPHONE权限。 3467 3468使用相机视频录制还需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/js-apis-camera.md)。 3469 3470**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3471 3472**参数：** 3473 3474| 参数名 | 类型 | 必填 | 说明 | 3475| -------- | -------------------------------------- | ---- | ------------------------------------- | 3476| config | [AVRecorderConfig](#avrecorderconfig9) | 是 | 配置音视频录制的相关参数。 | 3477| callback | AsyncCallback\<void> | 是 | 回调函数。当prepare方法成功，err为undefined，否则为错误对象。 | 3478 3479**错误码：** 3480 3481以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3482 3483| 错误码ID | 错误信息 | 3484| -------- | --------------------------------------- | 3485| 201 | Permission denied. Return by callback. | 3486| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3487| 5400102 | Operate not permit. Return by callback. | 3488| 5400105 | Service died. Return by callback. | 3489 3490**示例：** 3491 3492```ts 3493import { BusinessError } from '@kit.BasicServicesKit'; 3494 3495// 配置参数以实际硬件设备支持的范围为准。 3496let avRecorderProfile: media.AVRecorderProfile = { 3497 audioBitrate : 48000, 3498 audioChannels : 2, 3499 audioCodec : media.CodecMimeType.AUDIO_AAC, 3500 audioSampleRate : 48000, 3501 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 3502 videoBitrate : 2000000, 3503 videoCodec : media.CodecMimeType.VIDEO_AVC, 3504 videoFrameWidth : 640, 3505 videoFrameHeight : 480, 3506 videoFrameRate : 30 3507} 3508let avRecorderConfig: media.AVRecorderConfig = { 3509 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 3510 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 3511 profile : avRecorderProfile, 3512 url : 'fd://', // 文件需先由调用者创建，赋予读写权限，将文件fd传给此参数，eg.fd://45 3513 rotation : 0, // 合理值0、90、180、270，非合理值prepare接口将报错。 3514 location : { latitude : 30, longitude : 130 } 3515} 3516 3517avRecorder.prepare(avRecorderConfig, (err: BusinessError) => { 3518 if (err) { 3519 console.error('Failed to prepare and error is ' + err.message); 3520 } else { 3521 console.info('Succeeded in preparing'); 3522 } 3523}) 3524``` 3525 3526### prepare<sup>9+</sup> 3527 3528prepare(config: AVRecorderConfig): Promise\<void> 3529 3530异步方式进行音视频录制的参数设置。通过Promise获取返回值。 3531 3532**需要权限：** ohos.permission.MICROPHONE 3533 3534不涉及音频录制时，可以不需要获ohos.permission.MICROPHONE权限。 3535 3536使用相机视频录制还需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/js-apis-camera.md)。 3537 3538**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3539 3540**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3541 3542**参数：** 3543 3544| 参数名 | 类型 | 必填 | 说明 | 3545| ------ | -------------------------------------- | ---- | -------------------------- | 3546| config | [AVRecorderConfig](#avrecorderconfig9) | 是 | 配置音视频录制的相关参数。 | 3547 3548**返回值：** 3549 3550| 类型 | 说明 | 3551| -------------- | ------------------------------------------ | 3552| Promise\<void> | 异步音视频录制prepare方法的Promise返回值。 | 3553 3554**错误码：** 3555 3556以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3557 3558| 错误码ID | 错误信息 | 3559| -------- | -------------------------------------- | 3560| 201 | Permission denied. Return by promise. | 3561| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3562| 5400102 | Operate not permit. Return by promise. | 3563| 5400105 | Service died. Return by promise. | 3564 3565**示例：** 3566 3567```ts 3568import { BusinessError } from '@kit.BasicServicesKit'; 3569 3570// 配置参数以实际硬件设备支持的范围为准。 3571let avRecorderProfile: media.AVRecorderProfile = { 3572 audioBitrate : 48000, 3573 audioChannels : 2, 3574 audioCodec : media.CodecMimeType.AUDIO_AAC, 3575 audioSampleRate : 48000, 3576 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 3577 videoBitrate : 2000000, 3578 videoCodec : media.CodecMimeType.VIDEO_AVC, 3579 videoFrameWidth : 640, 3580 videoFrameHeight : 480, 3581 videoFrameRate : 30 3582} 3583let avRecorderConfig: media.AVRecorderConfig = { 3584 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 3585 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 3586 profile : avRecorderProfile, 3587 url : 'fd://', // 文件需先由调用者创建，赋予读写权限，将文件fd传给此参数，eg.fd://45 3588 rotation : 0, // 合理值0、90、180、270，非合理值prepare接口报错。 3589 location : { latitude : 30, longitude : 130 } 3590} 3591 3592avRecorder.prepare(avRecorderConfig).then(() => { 3593 console.info('Succeeded in preparing'); 3594}).catch((err: BusinessError) => { 3595 console.error('Failed to prepare and catch error is ' + err.message); 3596}); 3597``` 3598 3599### getInputSurface<sup>9+</sup> 3600 3601getInputSurface(callback: AsyncCallback\<string>): void 3602 3603异步方式获得录制需要的surface。通过注册回调函数获取返回值。此surface提供给调用者，调用者从此surface中获取surfaceBuffer，填入相应的视频数据。 3604 3605应当注意，填入的视频数据需要携带时间戳（单位ns）和buffersize。时间戳的起始时间请以系统启动时间为基准。 3606 3607需在[prepare()](#prepare9-2)事件成功触发后，才能调用getInputSurface()方法。 3608 3609**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3610 3611**参数：** 3612 3613| 参数名 | 类型 | 必填 | 说明 | 3614| -------- | ---------------------- | ---- | --------------------------- | 3615| callback | AsyncCallback\<string> | 是 | 回调函数。当获取surface成功，err为undefined，data为获取到的surfaceId，否则为错误对象。 | 3616 3617**错误码：** 3618 3619以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3620 3621| 错误码ID | 错误信息 | 3622| -------- | --------------------------------------- | 3623| 5400102 | Operate not permit. Return by callback. | 3624| 5400103 | IO error. Return by callback. | 3625| 5400105 | Service died. Return by callback. | 3626 3627**示例：** 3628 3629```ts 3630import { BusinessError } from '@kit.BasicServicesKit'; 3631let surfaceID: string; // 该surfaceID用于传递给相机接口创造videoOutput。 3632 3633avRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 3634 if (err) { 3635 console.error('Failed to do getInputSurface and error is ' + err.message); 3636 } else { 3637 console.info('Succeeded in doing getInputSurface'); 3638 surfaceID = surfaceId; 3639 } 3640}); 3641 3642``` 3643 3644### getInputSurface<sup>9+</sup> 3645 3646getInputSurface(): Promise\<string> 3647 3648异步方式获得录制需要的surface。通过Promise获取返回值。此surface提供给调用者，调用者从此surface中获取surfaceBuffer，填入相应的视频数据。 3649 3650应当注意，填入的视频数据需要携带时间戳（单位ns）和buffersize。时间戳的起始时间请以系统启动时间为基准。 3651 3652需在[prepare()](#prepare9-3)事件成功触发后，才能调用getInputSurface方法。 3653 3654**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3655 3656**返回值：** 3657 3658| 类型 | 说明 | 3659| ---------------- | -------------------------------- | 3660| Promise\<string> | 异步获得surface的Promise返回值。 | 3661 3662**错误码：** 3663 3664以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3665 3666| 错误码ID | 错误信息 | 3667| -------- | -------------------------------------- | 3668| 5400102 | Operate not permit. Return by promise. | 3669| 5400103 | IO error. Return by promise. | 3670| 5400105 | Service died. Return by promise. | 3671 3672**示例：** 3673 3674```ts 3675import { BusinessError } from '@kit.BasicServicesKit'; 3676let surfaceID: string; // 该surfaceID用于传递给相机接口创造videoOutput。 3677 3678avRecorder.getInputSurface().then((surfaceId: string) => { 3679 console.info('Succeeded in getting InputSurface'); 3680 surfaceID = surfaceId; 3681}).catch((err: BusinessError) => { 3682 console.error('Failed to get InputSurface and catch error is ' + err.message); 3683}); 3684``` 3685 3686### updateRotation<sup>12+</sup> 3687 3688updateRotation(rotation: number): Promise\<void> 3689 3690更新视频旋转角度。通过Promise获取返回值。 3691 3692当且仅当[prepare()](#prepare9-3)事件成功触发后，且在[start()](#start9)之前，才能调用updateRotation方法。 3693 3694**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3695 3696**参数：** 3697 3698| 参数名 | 类型 | 必填 | 说明 | 3699| -------- | -------------------- | ---- | --------------------------- | 3700| rotation | number | 是 | 旋转角度，取值仅支持0、90、180、270度。 | 3701 3702**返回值：** 3703 3704| 类型 | 说明 | 3705| ---------------- | -------------------------------- | 3706| Promise\<void> | 异步返回函数执行结果。 | 3707 3708**错误码：** 3709 3710以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3711 3712| 错误码ID | 错误信息 | 3713| -------- | -------------------------------------- | 3714| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3715| 5400102 | Operation not allowed. Return by promise. | 3716| 5400103 | IO error. Return by promise. | 3717| 5400105 | Service died. Return by promise. | 3718 3719**示例：** 3720 3721```ts 3722import { BusinessError } from '@kit.BasicServicesKit'; 3723 3724let rotation = 90 3725 3726avRecorder.updateRotation(rotation).then(() => { 3727 console.info('Succeeded in updateRotation'); 3728}).catch((err: BusinessError) => { 3729 console.error('Failed to updateRotation and catch error is ' + err.message); 3730}); 3731``` 3732 3733### start<sup>9+</sup> 3734 3735start(callback: AsyncCallback\<void>): void 3736 3737异步方式开始视频录制。通过注册回调函数获取返回值。 3738 3739纯音频录制需在[prepare()](#prepare9-2)事件成功触发后，才能调用start方法。纯视频录制，音视频录制需在[getInputSurface()](#getinputsurface9)事件成功触发后，才能调用start方法。 3740 3741**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3742 3743**参数：** 3744 3745| 参数名 | 类型 | 必填 | 说明 | 3746| -------- | -------------------- | ---- | ---------------------------- | 3747| callback | AsyncCallback\<void> | 是 |回调函数。当开始录制视频成功，err为undefined，否则为错误对象。 | 3748 3749**错误码：** 3750 3751以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3752 3753| 错误码ID | 错误信息 | 3754| -------- | --------------------------------------- | 3755| 5400102 | Operate not permit. Return by callback. | 3756| 5400103 | IO error. Return by callback. | 3757| 5400105 | Service died. Return by callback. | 3758 3759**示例：** 3760 3761```ts 3762import { BusinessError } from '@kit.BasicServicesKit'; 3763 3764avRecorder.start((err: BusinessError) => { 3765 if (err) { 3766 console.error('Failed to start AVRecorder and error is ' + err.message); 3767 } else { 3768 console.info('Succeeded in starting AVRecorder'); 3769 } 3770}); 3771``` 3772 3773### start<sup>9+</sup> 3774 3775start(): Promise\<void> 3776 3777异步方式开始视频录制。通过Promise获取返回值。 3778 3779纯音频录制需在[prepare()](#prepare9-3)事件成功触发后，才能调用start方法。纯视频录制，音视频录制需在[getInputSurface()](#getinputsurface9-1)事件成功触发后，才能调用start方法。 3780 3781**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3782 3783**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3784 3785**返回值：** 3786 3787| 类型 | 说明 | 3788| -------------- | ------------------------------------- | 3789| Promise\<void> | 异步开始视频录制方法的Promise返回值。 | 3790 3791**错误码：** 3792 3793以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3794 3795| 错误码ID | 错误信息 | 3796| -------- | -------------------------------------- | 3797| 5400102 | Operate not permit. Return by promise. | 3798| 5400103 | IO error. Return by promise. | 3799| 5400105 | Service died. Return by promise. | 3800 3801**示例：** 3802 3803```ts 3804import { BusinessError } from '@kit.BasicServicesKit'; 3805 3806avRecorder.start().then(() => { 3807 console.info('Succeeded in starting AVRecorder'); 3808}).catch((err: BusinessError) => { 3809 console.error('Failed to start AVRecorder and catch error is ' + err.message); 3810}); 3811``` 3812 3813### pause<sup>9+</sup> 3814 3815pause(callback: AsyncCallback\<void>): void 3816 3817异步方式暂停视频录制。通过注册回调函数获取返回值。 3818 3819需要[start()](#start9)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume9)接口来恢复录制。 3820 3821**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3822 3823**参数：** 3824 3825| 参数名 | 类型 | 必填 | 说明 | 3826| -------- | -------------------- | ---- | --------------------------- | 3827| callback | AsyncCallback\<void> | 是 | 回调函数。当暂停视频录制成功，err为undefined，否则为错误对象。 | 3828 3829**错误码：** 3830 3831以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3832 3833| 错误码ID | 错误信息 | 3834| -------- | --------------------------------------- | 3835| 5400102 | Operate not permit. Return by callback. | 3836| 5400103 | IO error. Return by callback. | 3837| 5400105 | Service died. Return by callback. | 3838 3839**示例：** 3840 3841```ts 3842import { BusinessError } from '@kit.BasicServicesKit'; 3843 3844avRecorder.pause((err: BusinessError) => { 3845 if (err) { 3846 console.error('Failed to pause AVRecorder and error is ' + err.message); 3847 } else { 3848 console.info('Succeeded in pausing'); 3849 } 3850}); 3851``` 3852 3853### pause<sup>9+</sup> 3854 3855pause(): Promise\<void> 3856 3857异步方式暂停视频录制。通过Promise获取返回值。 3858 3859需要[start()](#start9-1)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume9-1)接口来恢复录制。 3860 3861**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3862 3863**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3864 3865**返回值：** 3866 3867| 类型 | 说明 | 3868| -------------- | ------------------------------------- | 3869| Promise\<void> | 异步暂停视频录制方法的Promise返回值。 | 3870 3871**错误码：** 3872 3873以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3874 3875| 错误码ID | 错误信息 | 3876| -------- | -------------------------------------- | 3877| 5400102 | Operate not permit. Return by promise. | 3878| 5400103 | IO error. Return by promise. | 3879| 5400105 | Service died. Return by promise. | 3880 3881**示例：** 3882 3883```ts 3884import { BusinessError } from '@kit.BasicServicesKit'; 3885 3886avRecorder.pause().then(() => { 3887 console.info('Succeeded in pausing'); 3888}).catch((err: BusinessError) => { 3889 console.error('Failed to pause AVRecorder and catch error is ' + err.message); 3890}); 3891``` 3892 3893### resume<sup>9+</sup> 3894 3895resume(callback: AsyncCallback\<void>): void 3896 3897异步方式恢复视频录制。通过注册回调函数获取返回值。 3898 3899需要在[pause()](#pause9-2)事件成功触发后，才能调用resume方法。 3900 3901**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3902 3903**参数：** 3904 3905| 参数名 | 类型 | 必填 | 说明 | 3906| -------- | -------------------- | ---- | ---------------------------- | 3907| callback | AsyncCallback\<void> | 是 | 回调函数。当恢复视频录制成功，err为undefined，否则为错误对象。 | 3908 3909**错误码：** 3910 3911以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3912 3913| 错误码ID | 错误信息 | 3914| -------- | --------------------------------------- | 3915| 5400102 | Operate not permit. Return by callback. | 3916| 5400103 | IO error. Return by callback. | 3917| 5400105 | Service died. Return by callback. | 3918 3919**示例：** 3920 3921```ts 3922import { BusinessError } from '@kit.BasicServicesKit'; 3923 3924avRecorder.resume((err: BusinessError) => { 3925 if (err) { 3926 console.error('Failed to resume AVRecorder and error is ' + err.message); 3927 } else { 3928 console.info('Succeeded in resuming AVRecorder'); 3929 } 3930}); 3931``` 3932 3933### resume<sup>9+</sup> 3934 3935resume(): Promise\<void> 3936 3937异步方式恢复视频录制。通过Promise获取返回值。 3938 3939需要在[pause()](#pause9-3)事件成功触发后，才能调用resume方法。 3940 3941**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3942 3943**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3944 3945**返回值：** 3946 3947| 类型 | 说明 | 3948| -------------- | ------------------------------------- | 3949| Promise\<void> | 异步恢复视频录制方法的Promise返回值。 | 3950 3951**错误码：** 3952 3953以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3954 3955| 错误码ID | 错误信息 | 3956| -------- | -------------------------------------- | 3957| 5400102 | Operate not permit. Return by promise. | 3958| 5400103 | IO error. Return by promise. | 3959| 5400105 | Service died. Return by promise. | 3960 3961**示例：** 3962 3963```ts 3964import { BusinessError } from '@kit.BasicServicesKit'; 3965 3966avRecorder.resume().then(() => { 3967 console.info('Succeeded in resuming AVRecorder'); 3968}).catch((err: BusinessError) => { 3969 console.error('Failed to resume AVRecorder failed and catch error is ' + err.message); 3970}); 3971``` 3972 3973### stop<sup>9+</sup> 3974 3975stop(callback: AsyncCallback\<void>): void 3976 3977异步方式停止视频录制。通过注册回调函数获取返回值。 3978 3979需要在[start()](#start9)或[pause()](#pause9-2)事件成功触发后，才能调用stop方法。 3980 3981纯音频录制时，需要重新调用[prepare()](#prepare9-2)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-2)和[getInputSurface()](#getinputsurface9)接口才能重新录制。 3982 3983**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3984 3985**参数：** 3986 3987| 参数名 | 类型 | 必填 | 说明 | 3988| -------- | -------------------- | ---- | ---------------------------- | 3989| callback | AsyncCallback\<void> | 是 | 回调函数。当停止视频录制成功，err为undefined，否则为错误对象。 | 3990 3991**错误码：** 3992 3993以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3994 3995| 错误码ID | 错误信息 | 3996| -------- | --------------------------------------- | 3997| 5400102 | Operate not permit. Return by callback. | 3998| 5400103 | IO error. Return by callback. | 3999| 5400105 | Service died. Return by callback. | 4000 4001**示例：** 4002 4003```ts 4004import { BusinessError } from '@kit.BasicServicesKit'; 4005 4006avRecorder.stop((err: BusinessError) => { 4007 if (err) { 4008 console.error('Failed to stop AVRecorder and error is ' + err.message); 4009 } else { 4010 console.info('Succeeded in stopping AVRecorder'); 4011 } 4012}); 4013``` 4014 4015### stop<sup>9+</sup> 4016 4017stop(): Promise\<void> 4018 4019异步方式停止视频录制。通过Promise获取返回值。 4020 4021需要在[start()](#start9-1)或[pause()](#pause9-3)事件成功触发后，才能调用stop方法。 4022 4023纯音频录制时，需要重新调用[prepare()](#prepare9-3)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-3)和[getInputSurface()](#getinputsurface9-1)接口才能重新录制。 4024 4025**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 4026 4027**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4028 4029**返回值：** 4030 4031| 类型 | 说明 | 4032| -------------- | ------------------------------------- | 4033| Promise\<void> | 异步停止视频录制方法的Promise返回值。 | 4034 4035**错误码：** 4036 4037以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4038 4039| 错误码ID | 错误信息 | 4040| -------- | -------------------------------------- | 4041| 5400102 | Operate not permit. Return by promise. | 4042| 5400103 | IO error. Return by promise. | 4043| 5400105 | Service died. Return by promise. | 4044 4045**示例：** 4046 4047```ts 4048import { BusinessError } from '@kit.BasicServicesKit'; 4049 4050avRecorder.stop().then(() => { 4051 console.info('Succeeded in stopping AVRecorder'); 4052}).catch((err: BusinessError) => { 4053 console.error('Failed to stop AVRecorder and catch error is ' + err.message); 4054}); 4055``` 4056 4057### reset<sup>9+</sup> 4058 4059reset(callback: AsyncCallback\<void>): void 4060 4061异步方式重置音视频录制。通过注册回调函数获取返回值。 4062 4063纯音频录制时，需要重新调用[prepare()](#prepare9-2)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-2)和[getInputSurface()](#getinputsurface9)接口才能重新录制。 4064 4065**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4066 4067**参数：** 4068 4069| 参数名 | 类型 | 必填 | 说明 | 4070| -------- | -------------------- | ---- | ------------------------------ | 4071| callback | AsyncCallback\<void> | 是 | 回调函数。当重置音视频录制成功，err为undefined，否则为错误对象。 | 4072 4073**错误码：** 4074 4075以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4076 4077| 错误码ID | 错误信息 | 4078| -------- | --------------------------------- | 4079| 5400103 | IO error. Return by callback. | 4080| 5400105 | Service died. Return by callback. | 4081 4082**示例：** 4083 4084```ts 4085import { BusinessError } from '@kit.BasicServicesKit'; 4086 4087avRecorder.reset((err: BusinessError) => { 4088 if (err) { 4089 console.error('Failed to reset AVRecorder and error is ' + err.message); 4090 } else { 4091 console.info('Succeeded in resetting AVRecorder'); 4092 } 4093}); 4094``` 4095 4096### reset<sup>9+</sup> 4097 4098reset(): Promise\<void> 4099 4100异步方式重置音视频录制。通过Promise获取返回值。 4101 4102纯音频录制时，需要重新调用[prepare()](#prepare9-3)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-3)和[getInputSurface()](#getinputsurface9-1)接口才能重新录制。 4103 4104**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4105 4106**返回值：** 4107 4108| 类型 | 说明 | 4109| -------------- | --------------------------------------- | 4110| Promise\<void> | 异步重置音视频录制方法的Promise返回值。 | 4111 4112**错误码：** 4113 4114以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4115 4116| 错误码ID | 错误信息 | 4117| -------- | -------------------------------- | 4118| 5400103 | IO error. Return by promise. | 4119| 5400105 | Service died. Return by promise. | 4120 4121**示例：** 4122 4123```ts 4124import { BusinessError } from '@kit.BasicServicesKit'; 4125 4126avRecorder.reset().then(() => { 4127 console.info('Succeeded in resetting AVRecorder'); 4128}).catch((err: BusinessError) => { 4129 console.error('Failed to reset and catch error is ' + err.message); 4130}); 4131``` 4132 4133### release<sup>9+</sup> 4134 4135release(callback: AsyncCallback\<void>): void 4136 4137异步方式释放音视频录制资源。通过注册回调函数获取返回值。 4138 4139释放音视频录制资源之后，该AVRecorder实例不能再进行任何操作。 4140 4141**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4142 4143**参数：** 4144 4145| 参数名 | 类型 | 必填 | 说明 | 4146| -------- | -------------------- | ---- | ---------------------------------- | 4147| callback | AsyncCallback\<void> | 是 | 回调函数。当释放音视频录制资源成功，err为undefined，否则为错误对象。 | 4148 4149**错误码：** 4150 4151以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4152 4153| 错误码ID | 错误信息 | 4154| -------- | --------------------------------- | 4155| 5400105 | Service died. Return by callback. | 4156 4157**示例：** 4158 4159```ts 4160import { BusinessError } from '@kit.BasicServicesKit'; 4161 4162avRecorder.release((err: BusinessError) => { 4163 if (err) { 4164 console.error('Failed to release AVRecorder and error is ' + err.message); 4165 } else { 4166 console.info('Succeeded in releasing AVRecorder'); 4167 } 4168}); 4169``` 4170 4171### release<sup>9+</sup> 4172 4173release(): Promise\<void> 4174 4175异步方式释放音视频录制资源。通过Promise获取返回值。 4176 4177释放音视频录制资源之后，该AVRecorder实例不能再进行任何操作。 4178 4179**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 4180 4181**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4182 4183**返回值：** 4184 4185| 类型 | 说明 | 4186| -------------- | ------------------------------------------- | 4187| Promise\<void> | 异步释放音视频录制资源方法的Promise返回值。 | 4188 4189**错误码：** 4190 4191以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4192 4193| 错误码ID | 错误信息 | 4194| -------- | --------------------------------- | 4195| 5400105 | Service died. Return by callback. | 4196 4197**示例：** 4198 4199```ts 4200import { BusinessError } from '@kit.BasicServicesKit'; 4201 4202avRecorder.release().then(() => { 4203 console.info('Succeeded in releasing AVRecorder'); 4204}).catch((err: BusinessError) => { 4205 console.error('Failed to release AVRecorder and catch error is ' + err.message); 4206}); 4207``` 4208 4209### getCurrentAudioCapturerInfo<sup>11+</sup> 4210 4211getCurrentAudioCapturerInfo(callback: AsyncCallback\<audio.AudioCapturerChangeInfo>): void 4212 4213异步方式获取当前音频采集参数。通过注册回调函数获取返回值。 4214 4215在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 4216 4217**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4218 4219**参数**： 4220 4221| 参数名 | 类型 | 必填 | 说明 | 4222| -------- | ------------------------------------------------------------ | ---- | ------------------------------------ | 4223| callback | AsyncCallback\<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 是 | 回调函数。当获取音频采集参数成功时，err为undefined，data为获取到的audio.AudioCapturerChangeInfo，否则为错误对象。 | 4224 4225**错误码**： 4226 4227以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4228 4229| 错误码ID | 错误信息 | 4230| -------- | ------------------------------------------ | 4231| 5400102 | Operation not allowed. | 4232| 5400103 | I/O error. | 4233| 5400105 | Service died. Return by callback. | 4234 4235**示例**： 4236 4237```ts 4238import { audio } from '@kit.AudioKit'; 4239 4240let currentCapturerInfo: audio.AudioCapturerChangeInfo; 4241 4242avRecorder.getCurrentAudioCapturerInfo((err: BusinessError, capturerInfo: audio.AudioCapturerChangeInfo) => { 4243 if (err) { 4244 console.error('Failed to get CurrentAudioCapturerInfo and error is ' + err.message); 4245 } else { 4246 console.info('Succeeded in getting CurrentAudioCapturerInfo'); 4247 currentCapturerInfo = capturerInfo; 4248 } 4249}); 4250``` 4251 4252### getCurrentAudioCapturerInfo<sup>11+</sup> 4253 4254getCurrentAudioCapturerInfo(): Promise\<audio.AudioCapturerChangeInfo> 4255 4256异步方式获取当前音频采集参数。通过Promise获取返回值。 4257 4258在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 4259 4260**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4261 4262**返回值**： 4263 4264| 类型 | 说明 | 4265| ------------------------------------------------------------ | ------------------------------------------------- | 4266| Promise\<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | Promise对象，返回获取的当前音频采集参数。 | 4267 4268**错误码**： 4269 4270以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4271 4272| 错误码ID | 错误信息 | 4273| -------- | -------------------------------- | 4274| 5400102 | Operation not allowed. | 4275| 5400103 | I/O error. | 4276| 5400105 | Service died. Return by promise. | 4277 4278**示例**： 4279 4280```ts 4281import { audio } from '@kit.AudioKit'; 4282 4283let currentCapturerInfo: audio.AudioCapturerChangeInfo; 4284 4285avRecorder.getCurrentAudioCapturerInfo().then((capturerInfo: audio.AudioCapturerChangeInfo) => { 4286 console.info('Succeeded in getting CurrentAudioCapturerInfo'); 4287 currentCapturerInfo = capturerInfo; 4288}).catch((err: BusinessError) => { 4289 console.error('Failed to get CurrentAudioCapturerInfo and catch error is ' + err.message); 4290}); 4291``` 4292 4293### getAudioCapturerMaxAmplitude<sup>11+</sup> 4294 4295getAudioCapturerMaxAmplitude(callback: AsyncCallback\<number>): void 4296 4297异步方式获取当前音频最大振幅。通过注册回调函数获取返回值。 4298 4299在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 4300 4301调用接口时，获取到的返回值是上一次获取最大振幅的时刻到当前这段区间内的音频最大振幅。即，如果在1s的时刻获取了一次最大振幅，在2s时再获取到的最大振幅时1-2s这个区间里面的最大值。 4302 4303**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4304 4305**参数**： 4306 4307| 参数名 | 类型 | 必填 | 说明 | 4308| -------- | ---------------------- | ---- | ------------------------------------ | 4309| callback | AsyncCallback\<number> | 是 | 回调函数。获取当前音频最大振幅成功时，err为undefined，data为获取到的最大振幅，否则为错误对象。 | 4310 4311**错误码**： 4312 4313以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4314 4315| 错误码ID | 错误信息 | 4316| -------- | ------------------------------------------ | 4317| 5400102 | Operation not allowed. | 4318| 5400105 | Service died. Return by callback. | 4319 4320**示例**： 4321 4322```ts 4323let maxAmplitude: number; 4324 4325avRecorder.getAudioCapturerMaxAmplitude((err: BusinessError, amplitude: number) => { 4326 if (err) { 4327 console.error('Failed to get AudioCapturerMaxAmplitude and error is ' + err.message); 4328 } else { 4329 console.info('Succeeded in getting AudioCapturerMaxAmplitude'); 4330 maxAmplitude = amplitude; 4331 } 4332}); 4333``` 4334 4335### getAudioCapturerMaxAmplitude<sup>11+</sup> 4336 4337getAudioCapturerMaxAmplitude(): Promise\<number> 4338 4339异步方式获取当前音频最大振幅参数。通过Promise获取返回值。 4340 4341在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 4342 4343调用接口时，获取到的返回值是上一次获取最大振幅的时刻到当前这段区间内的音频最大振幅。即，如果在1s的时刻获取了一次最大振幅，在2s时再获取到的最大振幅时1-2s这个区间里面的最大值。 4344 4345**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4346 4347**返回值**： 4348 4349| 类型 | 说明 | 4350| ---------------- | ------------------------------------------------- | 4351| Promise\<number> | Promise对象，返回获取的当前音频最大振幅。 | 4352 4353**错误码**： 4354 4355以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4356 4357| 错误码ID | 错误信息 | 4358| -------- | -------------------------------- | 4359| 5400102 | Operation not allowed. | 4360| 5400105 | Service died. Return by promise. | 4361 4362**示例**： 4363 4364```ts 4365let maxAmplitude: number; 4366 4367avRecorder.getAudioCapturerMaxAmplitude().then((amplitude: number) => { 4368 console.info('Succeeded in getting AudioCapturerMaxAmplitude'); 4369 maxAmplitude = amplitude; 4370}).catch((err: BusinessError) => { 4371 console.error('Failed to get AudioCapturerMaxAmplitude and catch error is ' + err.message); 4372}); 4373``` 4374 4375### getAvailableEncoder<sup>11+</sup> 4376 4377getAvailableEncoder(callback: AsyncCallback\<Array\<EncoderInfo>>): void 4378 4379异步方式获取可用的编码器参数。通过注册回调函数获取返回值。 4380 4381**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4382 4383**参数**： 4384 4385| 参数名 | 类型 | 必填 | 说明 | 4386| -------- | ----------------------------------------------------- | ---- | ------------------------------------ | 4387| callback | AsyncCallback\<Array\<[EncoderInfo](#encoderinfo11)>> | 是 | 回调函数。获取可用的编码器参数成功时，err为undefined，data为获取到的编码器参数，否则为错误对象。 | 4388 4389**错误码**： 4390 4391以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4392 4393| 错误码ID | 错误信息 | 4394| -------- | ------------------------------------------ | 4395| 5400102 | Operation not allowed. | 4396| 5400105 | Service died. Return by callback. | 4397 4398**示例**： 4399 4400```ts 4401let encoderInfo: media.EncoderInfo; 4402 4403avRecorder.getAvailableEncoder((err: BusinessError, info: media.EncoderInfo[]) => { 4404 if (err) { 4405 console.error('Failed to get AvailableEncoder and error is ' + err.message); 4406 } else { 4407 console.info('Succeeded in getting AvailableEncoder'); 4408 encoderInfo = info[0]; 4409 } 4410}); 4411``` 4412 4413### getAvailableEncoder<sup>11+</sup> 4414 4415getAvailableEncoder(): Promise\<Array\<EncoderInfo>> 4416 4417异步方式获取可用的编码器参数。通过注册回调函数获取返回值。 4418 4419**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4420 4421**返回值**： 4422 4423| 类型 | 说明 | 4424| ----------------------------------------------- | ----------------------------------------------- | 4425| Promise\<Array\<[EncoderInfo](#encoderinfo11)>> | Promise对象，返回获取的可用的编码器参数。 | 4426 4427**错误码**： 4428 4429以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4430 4431| 错误码ID | 错误信息 | 4432| -------- | -------------------------------- | 4433| 5400102 | Operation not allowed. | 4434| 5400105 | Service died. Return by promise. | 4435 4436**示例**： 4437 4438```ts 4439let encoderInfo: media.EncoderInfo; 4440 4441avRecorder.getAvailableEncoder().then((info: media.EncoderInfo[]) => { 4442 console.info('Succeeded in getting AvailableEncoder'); 4443 encoderInfo = info[0]; 4444}).catch((err: BusinessError) => { 4445 console.error('Failed to get AvailableEncoder and catch error is ' + err.message); 4446}); 4447``` 4448 4449### getAVRecorderConfig<sup>11+</sup> 4450 4451getAVRecorderConfig(callback: AsyncCallback\<AVRecorderConfig>): void 4452 4453异步方式获取实时的配置参数。通过注册回调函数获取返回值。 4454 4455只能在[prepare()](#prepare9-2)接口调用后调用。 4456 4457**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4458 4459**参数：** 4460 4461| 参数名 | 类型 | 必填 | 说明 | 4462| -------- | ---------------------- | ---- | --------------------------- | 4463| callback | AsyncCallback\<[AVRecorderConfig](#avrecorderconfig9)> | 是 | 回调函数。获取实时配置的参数成功时，err为undefined，data为获取到的配置参数，否则为错误对象。 | 4464 4465**错误码：** 4466 4467以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 4468 4469| 错误码ID | 错误信息 | 4470| -------- | ------------------------------------------ | 4471| 5400102 | Operate not permit. Return by callback. | 4472| 5400103 | IO error. Return by callback. | 4473| 5400105 | Service died. Return by callback. | 4474 4475**示例：** 4476 4477```ts 4478import { BusinessError } from '@kit.BasicServicesKit'; 4479 4480let avConfig: media.AVRecorderConfig; 4481 4482avRecorder.getAVRecorderConfig((err: BusinessError, config: media.AVRecorderConfig) => { 4483 if (err) { 4484 console.error('Failed to get avConfig and error is ' + err.message); 4485 } else { 4486 console.info('Succeeded in getting AVRecorderConfig'); 4487 avConfig = config; 4488 } 4489}); 4490``` 4491 4492### getAVRecorderConfig<sup>11+</sup> 4493 4494getAVRecorderConfig(): Promise\<AVRecorderConfig>; 4495 4496异步方式获取实时的配置参数。通过Promise获取返回值。 4497 4498只能在[prepare()](#prepare9-3)接口调用后调用。 4499 4500**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4501 4502**返回值：** 4503 4504| 类型 | 说明 | 4505| ---------------- | -------------------------------- | 4506| Promise\<[AVRecorderConfig](#avrecorderconfig9)> | 异步获得实时配置参数的回调方法。 | 4507 4508**错误码：** 4509 4510以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 4511 4512| 错误码ID | 错误信息 | 4513| -------- | ----------------------------------------- | 4514| 5400102 | Operate not permit. Return by promise. | 4515| 5400103 | IO error. Return by promise. | 4516| 5400105 | Service died. Return by promise. | 4517 4518**示例：** 4519 4520```ts 4521import { BusinessError } from '@kit.BasicServicesKit'; 4522 4523let avConfig: media.AVRecorderConfig; 4524 4525avRecorder.getAVRecorderConfig().then((config: media.AVRecorderConfig) => { 4526 console.info('Succeeded in getting AVRecorderConfig'); 4527 avConfig = config; 4528}).catch((err: BusinessError) => { 4529 console.error('Failed to get AVRecorderConfig and catch error is ' + err.message); 4530}); 4531``` 4532 4533### on('stateChange')<sup>9+</sup> 4534 4535on(type: 'stateChange', callback: OnAVRecorderStateChangeHandler): void 4536 4537订阅录制状态机AVRecorderState切换的事件，当 AVRecorderState状态机发生变化时，会通过订阅的回调方法通知用户。用户只能订阅一个状态机切换事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 4538 4539**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4540 4541**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4542 4543**参数：** 4544 4545| 参数名 | 类型 | 必填 | 说明 | 4546| -------- | -------- | ---- | ------------------------------------------------------------ | 4547| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 4548| callback | [OnAVRecorderStateChangeHandler](#onavrecorderstatechangehandler12) | 是 | 状态机切换事件回调方法。 | 4549 4550**错误码：** 4551 4552以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4553 4554| 错误码ID | 错误信息 | 4555| -------- | --------------------------------- | 4556| 5400103 | IO error. Return by callback. | 4557| 5400105 | Service died. Return by callback. | 4558 4559**示例：** 4560 4561```ts 4562avRecorder.on('stateChange', async (state: media.AVRecorderState, reason: media.StateChangeReason) => { 4563 console.info('case state has changed, new state is :' + state + ',and new reason is : ' + reason); 4564}); 4565``` 4566 4567### off('stateChange')<sup>9+</sup> 4568 4569off(type: 'stateChange', callback?: OnAVRecorderStateChangeHandler): void 4570 4571取消订阅播放状态机[AVRecorderState](#avrecorderstate9)切换的事件。 4572 4573**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4574 4575**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4576 4577**参数：** 4578 4579| 参数名 | 类型 | 必填 | 说明 | 4580| ------ | ------ | ---- | ------------------------------------------------------------ | 4581| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 4582| callback | [OnAVRecorderStateChangeHandler](#onavrecorderstatechangehandler12) | 否 | 状态机切换事件回调方法。<br/>从API version 12开始支持此参数。 | 4583 4584**示例：** 4585 4586```ts 4587avRecorder.off('stateChange'); 4588``` 4589 4590### on('error')<sup>9+</sup> 4591 4592on(type: 'error', callback: ErrorCallback): void 4593 4594订阅AVRecorder的错误事件，该事件仅用于错误提示，不需要用户停止播控动作。如果此时[AVRecorderState](#avrecorderstate9)也切至error状态，用户需要通过[reset()](#reset9-2)或者[release()](#release9-2)退出录制操作。 4595 4596用户只能订阅一个错误事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 4597 4598**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4599 4600**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4601 4602**参数：** 4603 4604| 参数名 | 类型 | 必填 | 说明 | 4605| -------- | ------------- | ---- | ------------------------------------------------------------ | 4606| type | string | 是 | 录制错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 4607| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录制错误事件回调方法。 | 4608 4609**错误码：** 4610 4611以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4612 4613| 错误码ID | 错误信息 | 4614| -------- | ------------------------------------------ | 4615| 201 | Permission denied. | 4616| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 4617| 801 | Capability not supported. | 4618| 5400101 | No memory. | 4619| 5400102 | Operation not allowed. | 4620| 5400103 | I/O error. | 4621| 5400104 | Time out. | 4622| 5400105 | Service died. | 4623| 5400106 | Unsupported format. | 4624| 5400107 | Audio interrupted. | 4625 4626**示例：** 4627 4628```ts 4629import { BusinessError } from '@kit.BasicServicesKit'; 4630 4631avRecorder.on('error', (err: BusinessError) => { 4632 console.info('case avRecorder.on(error) called, errMessage is ' + err.message); 4633}); 4634``` 4635 4636### off('error')<sup>9+</sup> 4637 4638off(type: 'error', callback?: ErrorCallback): void 4639 4640取消订阅录制错误事件，取消后不再接收到AVRecorder的错误事件。 4641 4642**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4643 4644**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4645 4646**参数：** 4647 4648| 参数名 | 类型 | 必填 | 说明 | 4649| ------ | ------ | ---- | ------------------------------------------------------------ | 4650| type | string | 是 | 录制错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 4651| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 录制错误事件回调方法。<br/>从API version 12开始支持此参数。 | 4652 4653**示例：** 4654 4655```ts 4656avRecorder.off('error'); 4657``` 4658 4659### on('audioCapturerChange')<sup>11+</sup> 4660 4661on(type: 'audioCapturerChange', callback: Callback<audio.AudioCapturerChangeInfo>): void 4662 4663订阅录音配置变化的回调，任意录音配置的变化会触发变化后的录音配置全量信息回调。 4664 4665当用户重复订阅时，以最后一次订阅的回调接口为准。 4666 4667**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4668 4669**参数：** 4670 4671| 参数名 | 类型 | 必填 | 说明 | 4672| -------- | -------- | ---- | ------------------------------------------------------------ | 4673| type | string | 是 |录音配置变化的回调类型，支持的事件：'audioCapturerChange'。 | 4674| callback | Callback<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 是 | 变化后的录音配置全量信息。| 4675 4676**错误码：** 4677 4678| 错误码ID | 错误信息 | 4679| -------- | ------------------------------------------ | 4680| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 4681 4682**示例：** 4683 4684```ts 4685import { audio } from '@kit.AudioKit' 4686 4687let capturerChangeInfo: audio.AudioCapturerChangeInfo; 4688 4689avRecorder.on('audioCapturerChange', (audioCapturerChangeInfo: audio.AudioCapturerChangeInfo) => { 4690 console.info('audioCapturerChange called'); 4691 capturerChangeInfo = audioCapturerChangeInfo; 4692}); 4693``` 4694 4695### off('audioCapturerChange')<sup>11+</sup> 4696 4697off(type: 'audioCapturerChange', callback?: Callback<audio.AudioCapturerChangeInfo>): void 4698 4699取消订阅录音变化的回调事件。 4700 4701**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4702 4703**参数：** 4704 4705| 参数名 | 类型 | 必填 | 说明 | 4706| ------ | ------ | ---- | ------------------------------------------------------------ | 4707| type | string | 是 | 录音配置变化的回调类型，支持的事件：'audioCapturerChange'。 | 4708| callback | Callback<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 否 | 变化后的录音配置全量信息。<br/>从API version 12开始支持此参数。| 4709 4710**示例：** 4711 4712```ts 4713avRecorder.off('audioCapturerChange'); 4714``` 4715 4716### on('photoAssetAvailable')<sup>12+</sup> 4717 4718on(type: 'photoAssetAvailable', callback: Callback\<photoAccessHelper.PhotoAsset>): void 4719 4720订阅媒体资源回调事件，当[FileGenerationMode](#filegenerationmode12)枚举设置为系统创建媒体文件时，会在[stop](#stop9-2)操作结束后把[PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)对象回调给应用。 4721 4722当用户重复订阅时，以最后一次订阅的回调接口为准。 4723 4724**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4725 4726**参数：** 4727 4728| 参数名 | 类型 | 必填 | 说明 | 4729| -------- | -------- | ---- | ------------------------------------------------------------ | 4730| type | string | 是 |录像资源的回调类型，支持的事件：'photoAssetAvailable'。 | 4731| callback | Callback<[photoAccessHelper.PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)> | 是 | 系统创建的资源文件对应的PhotoAsset对象。| 4732 4733**错误码：** 4734 4735| 错误码ID | 错误信息 | 4736| -------- | ------------------------------------------ | 4737| 5400103 | IO error. Return by callback. | 4738| 5400105 | Service died. Return by callback. | 4739 4740**示例：** 4741 4742<!--code_no_check--> 4743```ts 4744import { photoAccessHelper } from '@kit.MediaLibraryKit'; 4745import { common } from '@kit.AbilityKit' 4746let photoAsset: photoAccessHelper.PhotoAsset; 4747private context: Context | undefined; 4748constructor(context: Context) { 4749 this.context = context; // this.getUIContext().getHostContext(); 4750} 4751 4752// 例:处理photoAsset回调，保存video。 4753async function saveVideo(asset: photoAccessHelper.PhotoAsset) { 4754 console.info("saveVideo called"); 4755 try { 4756 let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(this.context); 4757 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset); 4758 assetChangeRequest.saveCameraPhoto(); 4759 await phAccessHelper.applyChanges(assetChangeRequest); 4760 console.info('apply saveVideo successfully'); 4761 } catch (err) { 4762 console.error(`apply saveVideo failed with error: ${err.code}, ${err.message}`); 4763 } 4764} 4765// 注册photoAsset监听。 4766avRecorder.on('photoAssetAvailable', (asset: photoAccessHelper.PhotoAsset) => { 4767 console.info('photoAssetAvailable called'); 4768 if (asset != undefined) { 4769 photoAsset = asset; 4770 // 处理photoAsset回调。 4771 // 例: this.saveVideo(asset); 4772 } else { 4773 console.error('photoAsset is undefined'); 4774 } 4775}); 4776``` 4777 4778### off('photoAssetAvailable')<sup>12+</sup> 4779 4780off(type: 'photoAssetAvailable', callback?: Callback<photoAccessHelper.PhotoAsset>): void 4781 4782取消订阅媒体资源的回调类型。 4783 4784**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4785 4786**参数：** 4787 4788| 参数名 | 类型 | 必填 | 说明 | 4789| ------ | ------ | ---- | ------------------------------------------------------------ | 4790| type | string | 是 | 录音配置变化的回调类型，支持的事件：'photoAssetAvailable'。 | 4791| callback | Callback<[photoAccessHelper.PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)> | 否 | 系统创建的资源文件对应的PhotoAsset对象。| 4792 4793**示例：** 4794 4795```ts 4796avRecorder.off('photoAssetAvailable'); 4797``` 4798 4799## AVRecorderState<sup>9+</sup> 4800 4801type AVRecorderState = 'idle' | 'prepared' | 'started' | 'paused' | 'stopped' | 'released' | 'error' 4802 4803音视频录制的状态机。可通过state属性获取当前状态。 4804 4805**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 4806 4807**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4808 4809| 类型 | 说明 | 4810| -------- | ------------------------------------------------------------ | 4811| 'idle' | 闲置状态。此时可以调用[AVRecorder.prepare()](#prepare9-2)方法设置录制参数，进入prepared状态。AVRecorder刚被创建，或者在任何非released状态下调用[AVRecorder.reset()](#reset9-2)方法，均进入idle状态。 | 4812| 'prepared' | 参数设置完成。此时可以调用[AVRecorder.start()](#start9)方法开始录制，进入started状态。 | 4813| 'started' | 正在录制。此时可以调用[AVRecorder.pause()](#pause9-2)方法暂停录制，进入paused状态。也可以调用[AVRecorder.stop()](#stop9-2)方法结束录制，进入stopped状态。 | 4814| 'paused' | 录制暂停。此时可以调用[AVRecorder.resume()](#resume9)方法继续录制，进入started状态。也可以调用[AVRecorder.stop()](#stop9-2)方法结束录制，进入stopped状态。 | 4815| 'stopped' | 录制停止。此时可以调用[AVRecorder.prepare()](#prepare9-2)方法设置录制参数，重新进入prepared状态。 | 4816| 'released' | 录制资源释放。此时不能再进行任何操作。在任何其他状态下，均可以通过调用[AVRecorder.release()](#release9-2)方法进入released状态。 | 4817| 'error' | 错误状态。当AVRecorder实例发生不可逆错误，会转换至当前状态。切换至error状态时会伴随[AVRecorder.on('error')事件](#onerror9-1)，该事件会上报详细错误原因。在error状态时，用户需要调用[AVRecorder.reset()](#reset9-2)方法重置AVRecorder实例，或者调用[AVRecorder.release()](#release9-2)方法释放资源。 | 4818 4819## OnAVRecorderStateChangeHandler<sup>12+</sup> 4820 4821type OnAVRecorderStateChangeHandler = (state: AVRecorderState, reason: StateChangeReason) => void 4822 4823状态机切换事件回调方法。 4824 4825**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4826 4827**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4828 4829| 参数名 | 类型 | 必填 | 说明 | 4830| ------ | ------ | ------ | ------------------------------------------------------------ | 4831| state | [AVRecorderState](#avrecorderstate9) | 是 | 当前录制状态。 | 4832| reason | [StateChangeReason](#statechangereason9) | 是 | 当前录制状态的切换原因。 | 4833 4834## AVRecorderConfig<sup>9+</sup> 4835 4836表示音视频录制的参数设置。 4837 4838通过audioSourceType和videoSourceType区分纯音频录制、纯视频录制或音视频录制。纯音频录制时，仅需要设置audioSourceType；纯视频录制时，仅需要设置videoSourceType；音视频录制时，audioSourceType和videoSourceType均需要设置。 4839 4840**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4841 4842| 名称 | 类型 | 必填 | 说明 | 4843| --------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 4844| audioSourceType | [AudioSourceType](#audiosourcetype9) | 否 | 选择录制的音频源类型。选择音频录制时必填。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4845| videoSourceType | [VideoSourceType](#videosourcetype9) | 否 | 选择录制的视频源类型。选择视频录制时必填。 | 4846| profile | [AVRecorderProfile](#avrecorderprofile9) | 是 | 录制的profile，必要参数。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4847| url | string | 是 | 录制输出URL：fd://xx (fd number) ，必要参数。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4848|fileGenerationMode<sup>12+</sup> | [FileGenerationMode](#filegenerationmode12) | 否 | 创建媒体文件的模式，配合[on('photoAssetAvailable')](#onphotoassetavailable12)监听使用。| 4849| rotation<sup>(deprecated)</sup> | number | 否 | 录制的视频旋转角度，mp4格式支持0，90，180，270，默认值为0。<br>从API version 6开始支持，从API version 12开始废弃。建议使用[AVMetadata](#avmetadata11).videoOrientation替代。如果同时设置两个值，将会采用[AVMetadata](#avmetadata11).videoOrientation。 | 4850| location<sup>(deprecated)</sup> | [Location](#location) | 否 | 录制的地理位置，默认不记录地理位置信息。<br>从API version 6开始支持，从API version 12开始废弃。建议使用 [AVMetadata](#avmetadata11).location。如果同时设置两个值，将会采用[AVMetadata](#avmetadata11).location。 | 4851| metadata<sup>12+</sup> | [AVMetadata](#avmetadata11) | 否 | 设置元数据信息。详情见 [AVMetadata](#avmetadata11)。 | 4852| maxDuration<sup>18+</sup> | number | 否 | 设置录制的最大时长，单位为秒，有效值取值范围[1 , 2^31-1]，无效输入会重置为最大值。录制到达设定时长后，录制会自动停止，并通过stateChange回调录制状态，[AVRecorderState](#avrecorderstate9) = 'stopped'，[StateChangeReason](#statechangereason9) = BACKGROUND。| 4853 4854## AVRecorderProfile<sup>9+</sup> 4855 4856音视频录制的配置文件。 4857 4858> **说明：** 4859> 此处提供音频参数配置的对照表，每项的具体释义，可查看下述字段解释。 4860> 4861> |编码格式|封装格式|采样率|比特率|声道数| 4862> |----|----|----|----|----| 4863> |AUDIO_AAC|MP4,M4A|[8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000]|[32000-500000]|[1-8]| 4864> |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]| 4865> |AUDIO_G711MU|WAV|[8000]|[64000]|[1]| 4866> |AUDIO_AMR_NB<sup>18+</sup> |AMR|[8000]|[4750, 5150, 5900, 6700, 7400, 7950, 10200, 12200]|[1]| 4867> |AUDIO_AMR_WB<sup>18+</sup> |AMR|[16000]|[6600, 8850, 12650, 14250, 15850, 18250, 19850, 23050, 23850]|[1]| 4868 4869**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4870 4871| 名称 | 类型 | 必填 | 说明 | 4872| ---------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 4873| 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 开始，该接口支持在原子化服务中使用。 | 4874| 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 开始，该接口支持在原子化服务中使用。 | 4875| audioCodec | [CodecMimeType](#codecmimetype8) | 否 | 音频编码格式，选择音频录制时必填。当前支持AUDIO_AAC，AUDIO_MP3，AUDIO_G711MU, AUDIO_AMR_NB, AUDIO_AMR_WB。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4876| 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 开始，该接口支持在原子化服务中使用。 | 4877| fileFormat | [ContainerFormatType](#containerformattype8) | 是 | 文件的容器格式，必要参数。当前支持MP4、M4A、MP3、WAV、AMR封装格式，不支持在MP4封装格式下使用AUDIO_MP3编码格式。<br>**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4878| videoBitrate | number | 否 | 视频编码比特率，选择视频录制时必填，支持范围[10000 - 100000000]。 | 4879| videoCodec | [CodecMimeType](#codecmimetype8) | 否 | 视频编码格式，选择视频录制时必填。当前支持VIDEO_AVC。| 4880| videoFrameWidth | number | 否 | 视频帧的宽，选择视频录制时必填，支持范围[176 - 4096]。 | 4881| videoFrameHeight | number | 否 | 视频帧的高，选择视频录制时必填，支持范围[144 - 4096]。 | 4882| videoFrameRate | number | 否 | 视频帧率，选择视频录制时必填，支持范围[1 - 60]。 | 4883| isHdr<sup>11+</sup> | boolean | 否 | HDR编码，选择视频录制时选填，isHdr默认为false，对应编码格式没有要求，isHdr为true时，对应的编码格式必须为video/hevc。| 4884| enableTemporalScale<sup>12+</sup> | boolean | 否 | 视频录制是否支持时域分层编码功能，选择视频录制时选填，enableTemporalScale默认为false。设置为true时，编码输出的码流中部分帧可以支持跳过不编码。| 4885 4886## AudioSourceType<sup>9+</sup> 4887 4888表示视频录制中音频源类型的枚举。 4889 4890**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4891 4892| 名称 | 值 | 说明 | 4893| ------------------------- | ---- | ---------------------- | 4894| AUDIO_SOURCE_TYPE_DEFAULT | 0 | 默认的音频输入源类型。 | 4895| AUDIO_SOURCE_TYPE_MIC | 1 | 表示MIC的音频输入源。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4896| AUDIO_SOURCE_TYPE_VOICE_RECOGNITION<sup>12+</sup> | 2 | 表示语音识别场景的音频源。 | 4897| AUDIO_SOURCE_TYPE_VOICE_COMMUNICATION<sup>12+</sup> | 7 | 表示语音通话场景的音频源。 | 4898| AUDIO_SOURCE_TYPE_VOICE_MESSAGE<sup>12+</sup> | 10 | 表示短语音消息的音频源。 | 4899| AUDIO_SOURCE_TYPE_CAMCORDER<sup>12+</sup> | 13 | 表示相机录像的音频源。 | 4900 4901## VideoSourceType<sup>9+</sup> 4902 4903表示视频录制中视频源类型的枚举。 4904 4905**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4906 4907| 名称 | 值 | 说明 | 4908| ----------------------------- | ---- | ------------------------------- | 4909| VIDEO_SOURCE_TYPE_SURFACE_YUV | 0 | 输入surface中携带的是raw data。 | 4910| VIDEO_SOURCE_TYPE_SURFACE_ES | 1 | 输入surface中携带的是ES data。 | 4911 4912## ContainerFormatType<sup>8+</sup> 4913 4914表示容器格式类型的枚举，缩写为CFT。 4915 4916**系统能力：** SystemCapability.Multimedia.Media.Core 4917 4918| 名称 | 值 | 说明 | 4919| ----------- | ----- | --------------------- | 4920| CFT_MPEG_4 | 'mp4' | 视频的容器格式，MP4。 | 4921| CFT_MPEG_4A | 'm4a' | 音频的容器格式，M4A。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4922| CFT_MP3<sup>12+</sup> | 'mp3' | 音频的容器格式，MP3。 | 4923| CFT_WAV<sup>12+</sup> | 'wav' | 音频的容器格式，WAV。 | 4924| CFT_AMR<sup>18+</sup> | 'amr' | 音频的容器格式，AMR。 | 4925 4926## Location 4927 4928视频录制的地理位置。 4929 4930**系统能力：** SystemCapability.Multimedia.Media.Core 4931 4932| 名称 | 类型 | 必填 | 说明 | 4933| --------- | ------ | ---- | ---------------- | 4934| latitude | number | 是 | 地理位置的纬度，取值范围为[-90, 90]。 | 4935| longitude | number | 是 | 地理位置的经度，取值范围为[-180, 180]。 | 4936 4937## EncoderInfo<sup>11+</sup> 4938 4939编码器和规格参数 4940 4941系统能力：SystemCapability.Multimedia.Media.AVRecorder 4942 4943| 名称 | 类型 | 可读 | 可写 | 说明 | 4944| ---------- | -------------------------------- | ---- | ---- | ------------------------------------------------------------ | 4945| mimeType | [CodecMimeType](#codecmimetype8) | 是 | 否 | 编码器MIME类型名称。 | 4946| type | string | 是 | 否 | 编码器类型，audio表示音频编码器，video表示视频编码器。 | 4947| bitRate | [Range](#range11) | 是 | 否 | 比特率，包含该编码器的最大和最小值。 | 4948| frameRate | [Range](#range11) | 是 | 否 | 视频帧率，包含帧率的最大和最小值，仅视频编码器拥有。 | 4949| width | [Range](#range11) | 是 | 否 | 视频帧的宽度，包含宽度的最大和最小值，仅视频编码器拥有。 | 4950| height | [Range](#range11) | 是 | 否 | 视频帧的高度，包含高度的最大和最小值，仅视频编码器拥有。 | 4951| channels | [Range](#range11) | 是 | 否 | 音频采集声道数，包含声道数的最大和最小值，仅音频编码器拥有。 | 4952| sampleRate | Array\<number> | 是 | 否 | 音频采样率，包含所有可以使用的音频采样率值数组，具体数值依赖编码器类型，仅音频编码器拥有。 | 4953 4954## Range<sup>11+</sup> 4955 4956表示一个类型的范围 4957 4958系统能力：SystemCapability.Multimedia.Media.AVRecorder 4959 4960| 名称 | 类型 | 可读 | 可写 | 说明 | 4961| ---- | ------ | ---- | ---- | ------------ | 4962| min | number | 是 | 否 | 范围的最小值。 | 4963| max | number | 是 | 否 | 范围的最大值。 | 4964 4965## FileGenerationMode<sup>12+</sup> 4966 4967表示创建媒体文件模式的枚举。 4968 4969**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4970 4971| 名称 | 值 | 说明 | 4972| ----------------------------- | ---- | ------------------------------- | 4973| APP_CREATE | 0 | 由应用自行在沙箱创建媒体文件。 | 4974| AUTO_CREATE_CAMERA_SCENE | 1 | 由系统创建媒体文件，当前仅在相机录制场景下生效，会忽略应用设置的url。 | 4975 4976## AVTranscoder<sup>12+</sup> 4977 4978视频转码管理类，用于视频转码。在调用AVTranscoder的方法前，需要先通过createAVTranscoder()构建一个AVTranscoder实例。 4979 4980视频转码demo可参考：[视频转码开发指导](../../media/media/using-avtranscoder-for-transcodering.md) 4981 4982### 属性 4983 4984**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4985 4986| 名称 | 类型 | 只读 | 可选 | 说明 | 4987| ------- | ------------------------------------ | ---- | ---- | ------------------ | 4988| fdSrc<sup>12+</sup> | [AVFileDescriptor](#avfiledescriptor9) | 否 | 否 | 源媒体文件描述，通过该属性设置数据源。<br/> **使用示例**：<br/>假设一个连续存储的媒体文件，地址偏移:0，字节长度:100。其文件描述为 AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVTranscoder 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。 | 4989| fdDst<sup>12+</sup> | number | 否 | 否 | 目标媒体文件描述，通过该属性设置数据输出。在创建AVTranscoder实例后，必须设置fdSrc和fdDst属性。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVTranscoder 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。 | 4990 4991### prepare<sup>12+</sup> 4992 4993prepare(config: AVTranscoderConfig): Promise\<void> 4994 4995异步方式进行视频转码的参数设置。通过Promise获取返回值。 4996 4997**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4998 4999**参数：** 5000 5001| 参数名 | 类型 | 必填 | 说明 | 5002| ------ | -------------------------------------- | ---- | -------------------------- | 5003| config | [AVTranscoderConfig](#avtranscoderconfig12) | 是 | 配置视频转码的相关参数。 | 5004 5005**返回值：** 5006 5007| 类型 | 说明 | 5008| -------------- | ------------------------------------------ | 5009| Promise\<void> | 异步视频转码prepare方法的Promise返回值。 | 5010 5011**错误码：** 5012 5013以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5014 5015| 错误码ID | 错误信息 | 5016| -------- | -------------------------------------- | 5017| 401 | The parameter check failed. Return by promise. | 5018| 5400102 | Operation not allowed. Return by promise. | 5019| 5400105 | Service died. Return by promise. | 5020| 5400106 | Unsupported format. Returned by promise. | 5021 5022**示例：** 5023 5024```ts 5025import { BusinessError } from '@kit.BasicServicesKit'; 5026 5027// 配置参数以实际硬件设备支持的范围为准。 5028let avTranscoderConfig: media.AVTranscoderConfig = { 5029 audioBitrate : 200000, 5030 audioCodec : media.CodecMimeType.AUDIO_AAC, 5031 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 5032 videoBitrate : 3000000, 5033 videoCodec : media.CodecMimeType.VIDEO_AVC, 5034 videoFrameWidth : 1280, 5035 videoFrameHeight : 720, 5036} 5037 5038avTranscoder.prepare(avTranscoderConfig).then(() => { 5039 console.info('prepare success'); 5040}).catch((err: BusinessError) => { 5041 console.error('prepare failed and catch error is ' + err.message); 5042}); 5043``` 5044 5045### start<sup>12+</sup> 5046 5047start(): Promise\<void> 5048 5049异步方式开始视频转码。通过Promise获取返回值。 5050 5051需要[prepare()](#prepare12)事件成功触发后，才能调用start方法。 5052 5053**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5054 5055**返回值：** 5056 5057| 类型 | 说明 | 5058| -------------- | ------------------------------------- | 5059| Promise\<void> | 异步开始视频转码方法的Promise返回值。 | 5060 5061**错误码：** 5062 5063以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5064 5065| 错误码ID | 错误信息 | 5066| -------- | -------------------------------------- | 5067| 5400102 | Operation not allowed. Return by promise. | 5068| 5400103 | IO error. Return by promise. | 5069| 5400105 | Service died. Return by promise. | 5070 5071**示例：** 5072 5073```ts 5074import { BusinessError } from '@kit.BasicServicesKit'; 5075 5076avTranscoder.start().then(() => { 5077 console.info('start AVTranscoder success'); 5078}).catch((err: BusinessError) => { 5079 console.error('start AVTranscoder failed and catch error is ' + err.message); 5080}); 5081``` 5082 5083### pause<sup>12+</sup> 5084 5085pause(): Promise\<void> 5086 5087异步方式暂停视频转码。通过Promise获取返回值。 5088 5089需要[start()](#start12)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume12)接口来恢复转码。 5090 5091**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5092 5093**返回值：** 5094 5095| 类型 | 说明 | 5096| -------------- | ------------------------------------- | 5097| Promise\<void> | 异步暂停视频转码方法的Promise返回值。 | 5098 5099**错误码：** 5100 5101以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5102 5103| 错误码ID | 错误信息 | 5104| -------- | -------------------------------------- | 5105| 5400102 | Operation not allowed. Return by promise. | 5106| 5400103 | IO error. Return by promise. | 5107| 5400105 | Service died. Return by promise. | 5108 5109**示例：** 5110 5111```ts 5112import { BusinessError } from '@kit.BasicServicesKit'; 5113 5114avTranscoder.pause().then(() => { 5115 console.info('pause AVTranscoder success'); 5116}).catch((err: BusinessError) => { 5117 console.error('pause AVTranscoder failed and catch error is ' + err.message); 5118}); 5119``` 5120 5121### resume<sup>12+</sup> 5122 5123resume(): Promise\<void> 5124 5125异步方式恢复视频转码。通过Promise获取返回值。 5126 5127需要在[pause()](#pause12)事件成功触发后，才能调用resume方法。 5128 5129**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5130 5131**返回值：** 5132 5133| 类型 | 说明 | 5134| -------------- | ------------------------------------- | 5135| Promise\<void> | 异步恢复视频转码方法的Promise返回值。 | 5136 5137**错误码：** 5138 5139以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5140 5141| 错误码ID | 错误信息 | 5142| -------- | -------------------------------------- | 5143| 5400102 | Operation not allowed. Return by promise. | 5144| 5400103 | IO error. Return by promise. | 5145| 5400105 | Service died. Return by promise. | 5146 5147**示例：** 5148 5149```ts 5150import { BusinessError } from '@kit.BasicServicesKit'; 5151 5152avTranscoder.resume().then(() => { 5153 console.info('resume AVTranscoder success'); 5154}).catch((err: BusinessError) => { 5155 console.error('resume AVTranscoder failed and catch error is ' + err.message); 5156}); 5157``` 5158 5159### cancel<sup>12+</sup> 5160 5161cancel(): Promise\<void> 5162 5163异步方式取消视频转码。通过Promise获取返回值。 5164 5165需要在[prepare()](#prepare12)、[start()](#start12)、[pause()](#pause12)或[resume()](#resume12)事件成功触发后，才能调用cancel方法。 5166 5167**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5168 5169**返回值：** 5170 5171| 类型 | 说明 | 5172| -------------- | ------------------------------------- | 5173| Promise\<void> | 异步取消视频转码方法的Promise返回值。 | 5174 5175**错误码：** 5176 5177以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5178 5179| 错误码ID | 错误信息 | 5180| -------- | -------------------------------------- | 5181| 5400102 | Operation not allowed. Return by promise. | 5182| 5400103 | IO error. Return by promise. | 5183| 5400105 | Service died. Return by promise. | 5184 5185**示例：** 5186 5187```ts 5188import { BusinessError } from '@kit.BasicServicesKit'; 5189 5190avTranscoder.cancel().then(() => { 5191 console.info('cancel AVTranscoder success'); 5192}).catch((err: BusinessError) => { 5193 console.error('cancel AVTranscoder failed and catch error is ' + err.message); 5194}); 5195``` 5196 5197### release<sup>12+</sup> 5198 5199release(): Promise\<void> 5200 5201异步方式释放视频转码资源。通过Promise获取返回值。 5202 5203释放视频转码资源之后，该AVTranscoder实例不能再进行任何操作。 5204 5205**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5206 5207**返回值：** 5208 5209| 类型 | 说明 | 5210| -------------- | ------------------------------------------- | 5211| Promise\<void> | 异步释放视频转码资源方法的Promise返回值。 | 5212 5213**错误码：** 5214 5215以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5216 5217| 错误码ID | 错误信息 | 5218| -------- | --------------------------------- | 5219| 5400102 | Operation not allowed. Return by promise. | 5220| 5400105 | Service died. Return by promise. | 5221 5222**示例：** 5223 5224```ts 5225import { BusinessError } from '@kit.BasicServicesKit'; 5226 5227avTranscoder.release().then(() => { 5228 console.info('release AVTranscoder success'); 5229}).catch((err: BusinessError) => { 5230 console.error('release AVTranscoder failed and catch error is ' + err.message); 5231}); 5232``` 5233 5234### on('progressUpdate')<sup>12+</sup> 5235 5236on(type: 'progressUpdate', callback: Callback\<number>): void 5237 5238注册转码进度更新事件，并通过注册的回调方法通知用户。用户只能注册一个进度更新事件的回调方法，当用户重复注册时，以最后一次注册的回调接口为准。 5239 5240**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5241 5242**参数：** 5243 5244| 参数名 | 类型 | 必填 | 说明 | 5245| -------- | -------- | ---- | ------------------------------------------------------------ | 5246| type | string | 是 | 进度更新事件回调类型，支持的事件：'progressUpdate'，在转码过程中系统会自动触发此事件。 | 5247| callback | [Callback\<number>](../apis-basic-services-kit/js-apis-base.md#callback) | 是 | 进度更新事件回调方法，progress: number，表示当前转码进度。 | 5248 5249**示例：** 5250 5251```ts 5252avTranscoder.on('progressUpdate', (progress: number) => { 5253 console.info('avTranscoder progressUpdate = ' + progress); 5254}); 5255``` 5256 5257### off('progressUpdate')<sup>12+</sup> 5258 5259off(type:'progressUpdate', callback?: Callback\<number>): void 5260 5261取消注册转码进度更新事件。 5262 5263**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5264 5265**参数：** 5266 5267| 参数名 | 类型 | 必填 | 说明 | 5268| ------ | ------ | ---- | ------------------------------------------------------------ | 5269| type | string | 是 | 进度更新事件回调类型，支持的事件：'progressUpdate'，用户操作和系统都会触发此事件。 | 5270| callback | [Callback\<number>](../apis-basic-services-kit/js-apis-base.md#callback) | 否 | 已注册的进度更新事件回调。由于当前回调注册时，仅会保留最后一次注册的回调，建议此参数缺省。 | 5271 5272**示例：** 5273 5274```ts 5275avTranscoder.off('progressUpdate'); 5276``` 5277 5278### on('error')<sup>12+</sup> 5279 5280on(type: 'error', callback: ErrorCallback): void 5281 5282注册AVtranscoder的错误事件，该事件仅用于错误提示。如果AVTranscoder上报error事件，用户需要通过[release()](#release12)退出转码操作。 5283 5284用户只能订阅一个错误事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 5285 5286**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5287 5288**参数：** 5289 5290| 参数名 | 类型 | 必填 | 说明 | 5291| -------- | ------------- | ---- | ------------------------------------------------------------ | 5292| type | string | 是 | 转码错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 5293| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 转码错误事件回调方法。 | 5294 5295**错误码：** 5296 5297以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 5298 5299| 错误码ID | 错误信息 | 5300| -------- | ------------------------------------------ | 5301| 401 | The parameter check failed. | 5302| 801 | Capability not supported. | 5303| 5400101 | No memory. | 5304| 5400102 | Operation not allowed. | 5305| 5400103 | I/O error. | 5306| 5400104 | Time out. | 5307| 5400105 | Service died. | 5308| 5400106 | Unsupported format. | 5309 5310**示例：** 5311 5312```ts 5313import { BusinessError } from '@kit.BasicServicesKit'; 5314 5315avTranscoder.on('error', (err: BusinessError) => { 5316 console.info('case avTranscoder.on(error) called, errMessage is ' + err.message); 5317}); 5318``` 5319 5320### off('error')<sup>12+</sup> 5321 5322off(type:'error', callback?: ErrorCallback): void 5323 5324取消注册转码错误事件，取消后不再接收到AVTranscoder的错误事件。 5325 5326**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5327 5328**参数：** 5329 5330| 参数名 | 类型 | 必填 | 说明 | 5331| ------ | ------ | ---- | ------------------------------------------------------------ | 5332| type | string | 是 | 转码错误事件回调类型'error'。 <br>- 'error'：转码过程中发生错误，触发该事件。 | 5333| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 错误事件回调方法。 | 5334 5335**示例：** 5336 5337```ts 5338avTranscoder.off('error'); 5339``` 5340 5341### on('complete')<sup>12+</sup> 5342 5343on(type: 'complete', callback: Callback\<void>): void 5344 5345注册转码完成事件，并通过注册的回调方法通知用户。用户只能注册一个进度更新事件的回调方法，当用户重复注册时，以最后一次注册的回调接口为准。 5346 5347当AVTranscoder上报complete事件时，当前转码操作已完成，用户需要通过[release()](#release12)退出转码操作。 5348 5349**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5350 5351**参数：** 5352 5353| 参数名 | 类型 | 必填 | 说明 | 5354| -------- | -------- | ---- | ------------------------------------------------------------ | 5355| type | string | 是 | 完成事件回调类型，支持的事件：'complete'，在转码过程中系统会自动触发此事件。 | 5356| callback | [Callback\<void>](../apis-basic-services-kit/js-apis-base.md#callback) | 是 | 完成事件回调方法。 | 5357 5358**示例：** 5359 5360```ts 5361avTranscoder.on('complete', async () => { 5362 console.info('avTranscoder complete'); 5363 // 用户须在此监听转码完成事件 5364 // 须等待avTranscoder.release()完成之后，再对转码后的文件进行转发、上传、转存等处理 5365 await avTranscoder.release(); 5366 avTranscoder = undefined; 5367}); 5368``` 5369 5370### off('complete')<sup>12+</sup> 5371 5372off(type:'complete', callback?: Callback\<void>): void 5373 5374取消注册转码完成事件。 5375 5376**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5377 5378**参数：** 5379 5380| 参数名 | 类型 | 必填 | 说明 | 5381| ------ | ------ | ---- | ------------------------------------------------------------ | 5382| type | string | 是 | 转码完成事件回调类型，支持的事件：'complete'，用户操作和系统都会触发此事件。 | 5383| callback | [Callback\<void>](../apis-basic-services-kit/js-apis-base.md#callback) | 否 | 完成事件回调方法。 | 5384 5385**示例：** 5386 5387```ts 5388avTranscoder.off('complete'); 5389``` 5390 5391## AVTranscoderConfig<sup>12+</sup> 5392 5393表示视频转码的参数设置。 5394 5395**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 5396 5397| 名称 | 类型 | 只读 | 可选 | 说明 | 5398| --------------- | ---------------------------------------- |---- | ---- | ------------------------------------------------------------ | 5399| audioBitrate | number | 否 | 是 | 输出音频的码率，单位为比特率（bps），支持范围[1-500000]。默认设置为48Kbps。| 5400| audioCodec | [CodecMimeType](#codecmimetype8) | 否 | 是 | 输出音频的编码格式，当前仅支持AAC。默认设置为AAC。 | 5401| fileFormat | [ContainerFormatType](#containerformattype8) | 否 | 否 | 输出视频文件的封装格式，当前视频文件仅支持MP4。| 5402| videoBitrate | number | 否 | 是 | 输出视频的码率，单位为比特率（bps）。默认码率按输出视频的分辨率设置，[240p，480P]默认码率值为1Mbps，(480P,720P]默认码率值为2Mbps，(720P,1080P]默认码率值为4Mbps，1080P及以上默认值为8Mbps。| 5403| videoCodec | [CodecMimeType](#codecmimetype8) | 否 | 是 | 输出视频的编码格式，当前仅支持AVC和HEVC。若源视频编码格式为HEVC，则默认设置为HEVC，否则默认设置为AVC。| 5404| videoFrameWidth | number | 否 | 是 | 输出视频帧的宽，单位为像素（px），支持范围[240-3840]。默认设置为源视频帧的宽。| 5405| videoFrameHeight | number | 否 | 是 | 输出视频帧的高，单位为像素（px），支持范围[240-2160]。默认设置为源视频帧的高。| 5406 5407 5408 5409## AVMetadataExtractor<sup>11+</sup> 5410 5411元数据获取类，用于从媒体资源中获取元数据。在调用AVMetadataExtractor的方法前，需要先通过[createAVMetadataExtractor()](#mediacreateavmetadataextractor11)构建一个AVMetadataExtractor实例。 5412 5413获取音频或视频元数据的demo可参考：[获取音视频元数据开发指导](../../media/media/avmetadataextractor.md)。 5414 5415### 属性 5416 5417**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5418 5419| 名称 | 类型 | 可读 | 可写 | 说明 | 5420| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 5421| 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。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致音视频元数据获取异常。 | 5422| dataSrc<sup>11+</sup> | [AVDataSrcDescriptor](#avdatasrcdescriptor10) | 是 | 是 | 流式媒体资源描述，通过该属性设置数据源。在获取元数据之前，必须设置数据源属性，只能设置fdSrc和dataSrc的其中一个。<br/> 当应用从远端获取音视频媒体文件，在应用未下载完整音视频资源时，可以设置dataSrc提前获取该资源的元数据。| 5423 5424### fetchMetadata<sup>11+</sup> 5425 5426fetchMetadata(callback: AsyncCallback\<AVMetadata>): void 5427 5428异步方式获取媒体元数据。通过注册回调函数获取返回值。 5429 5430**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5431 5432**参数：** 5433 5434| 参数名 | 类型 | 必填 | 说明 | 5435| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5436| callback | AsyncCallback\<[AVMetadata](#avmetadata11)> | 是 | 回调函数。异步返回音视频元数据对象（AVMetadata）。| 5437 5438**错误码：** 5439 5440以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5441 5442| 错误码ID | 错误信息 | 5443| -------- | ------------------------------------------ | 5444| 5400102 | Operation not allowed. Returned by callback. | 5445| 5400106 | Unsupported format. Returned by callback. | 5446 5447**示例：** 5448 5449```ts 5450import { BusinessError } from '@kit.BasicServicesKit'; 5451 5452avMetadataExtractor.fetchMetadata((error: BusinessError, metadata: media.AVMetadata) => { 5453 if (error) { 5454 console.error(`Failed to fetch Metadata, err = ${JSON.stringify(error)}`); 5455 return; 5456 } 5457 console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`); 5458}); 5459``` 5460 5461### fetchMetadata<sup>11+</sup> 5462 5463fetchMetadata(): Promise\<AVMetadata> 5464 5465异步方式获取媒体元数据。通过Promise获取返回值。 5466 5467**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5468 5469**返回值：** 5470 5471| 类型 | 说明 | 5472| -------------- | ---------------------------------------- | 5473| Promise\<[AVMetadata](#avmetadata11)> | Promise对象。异步返回音视频元数据对象（AVMetadata）。 | 5474 5475**错误码：** 5476 5477以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5478 5479| 错误码ID | 错误信息 | 5480| -------- | ----------------------------------------- | 5481| 5400102 | Operation not allowed. Returned by promise. | 5482| 5400106 | Unsupported format. Returned by promise. | 5483 5484**示例：** 5485 5486```ts 5487import { BusinessError } from '@kit.BasicServicesKit'; 5488 5489avMetadataExtractor.fetchMetadata().then((metadata: media.AVMetadata) => { 5490 console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`) 5491}).catch((error: BusinessError) => { 5492 console.error(`Failed to fetch Metadata, error message:${error.message}`); 5493}); 5494``` 5495 5496### fetchAlbumCover<sup>11+</sup> 5497 5498fetchAlbumCover(callback: AsyncCallback\<image.PixelMap>): void 5499 5500异步方式获取音频专辑封面。通过注册回调函数获取返回值。 5501 5502**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5503 5504**参数：** 5505 5506| 参数名 | 类型 | 必填 | 说明 | 5507| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5508| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | 回调函数。异步返回专辑封面。 | 5509 5510**错误码：** 5511 5512以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5513 5514| 错误码ID | 错误信息 | 5515| -------- | ------------------------------------------ | 5516| 5400102 | Operation not allowed. Return by callback. | 5517| 5400106 | Unsupported format. Returned by callback. | 5518 5519**示例：** 5520 5521```ts 5522import { BusinessError } from '@kit.BasicServicesKit'; 5523import { image } from '@kit.ImageKit'; 5524 5525let pixel_map : image.PixelMap | undefined = undefined; 5526 5527avMetadataExtractor.fetchAlbumCover((error: BusinessError, pixelMap: image.PixelMap) => { 5528 if (error) { 5529 console.error(`Failed to fetch AlbumCover, error = ${JSON.stringify(error)}`); 5530 return; 5531 } 5532 pixel_map = pixelMap; 5533}); 5534``` 5535 5536### fetchAlbumCover<sup>11+</sup> 5537 5538fetchAlbumCover(): Promise\<image.PixelMap> 5539 5540异步方式获取专辑封面。通过Promise获取返回值。 5541 5542**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5543 5544**返回值：** 5545 5546| 类型 | 说明 | 5547| -------------- | ---------------------------------------- | 5548| Promise\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise对象。异步返回专辑封面。 | 5549 5550**错误码：** 5551 5552以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5553 5554| 错误码ID | 错误信息 | 5555| -------- | ----------------------------------------- | 5556| 5400102 | Operation not allowed. Returned by promise. | 5557| 5400106 | Unsupported format. Returned by promise. | 5558 5559**示例：** 5560 5561```ts 5562import { BusinessError } from '@kit.BasicServicesKit'; 5563import { image } from '@kit.ImageKit'; 5564 5565let pixel_map : image.PixelMap | undefined = undefined; 5566 5567avMetadataExtractor.fetchAlbumCover().then((pixelMap: image.PixelMap) => { 5568 pixel_map = pixelMap; 5569}).catch((error: BusinessError) => { 5570 console.error(`Failed to fetch AlbumCover, error message:${error.message}`); 5571}); 5572``` 5573 5574### release<sup>11+</sup> 5575 5576release(callback: AsyncCallback\<void>): void 5577 5578异步方式释放资源。通过注册回调函数获取返回值。 5579 5580**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5581 5582**参数：** 5583 5584| 参数名 | 类型 | 必填 | 说明 | 5585| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5586| callback | AsyncCallback\<void> | 是 |回调函数。当释放资源成功，err为undefined，否则为错误对象。 | 5587 5588**错误码：** 5589 5590以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5591 5592| 错误码ID | 错误信息 | 5593| -------- | ------------------------------------------ | 5594| 5400102 | Operation not allowed. Returned by callback. | 5595 5596**示例：** 5597 5598```ts 5599import { BusinessError } from '@kit.BasicServicesKit'; 5600 5601avMetadataExtractor.release((error: BusinessError) => { 5602 if (error) { 5603 console.error(`Failed to release, err = ${JSON.stringify(error)}`); 5604 return; 5605 } 5606 console.info(`Succeeded in releasing.`); 5607}); 5608``` 5609 5610### release<sup>11+</sup> 5611 5612release(): Promise\<void> 5613 5614异步方式释放资源。通过Promise获取返回值。 5615 5616**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5617 5618**返回值：** 5619 5620| 类型 | 说明 | 5621| -------------- | ---------------------------------------- | 5622| Promise\<void> | 异步方式释放资源release方法的Promise返回值。 | 5623 5624**错误码：** 5625 5626以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5627 5628| 错误码ID | 错误信息 | 5629| -------- | ----------------------------------------- | 5630| 5400102 | Operation not allowed. Returned by promise. | 5631 5632**示例：** 5633 5634```ts 5635import { BusinessError } from '@kit.BasicServicesKit'; 5636 5637avMetadataExtractor.release().then(() => { 5638 console.info(`Succeeded in releasing.`); 5639}).catch((error: BusinessError) => { 5640 console.error(`Failed to release, error message:${error.message}`); 5641}); 5642``` 5643 5644## AVMetadata<sup>11+</sup> 5645 5646音视频元数据，包含各个元数据字段。在[AVRecorderConfig](#avrecorderconfig9)中使用时未声明为当前版本只读的参数可以作为使用[AVRecorder](#avrecorder9)录制时的入参。 5647 5648**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5649 5650| 名称 | 类型 | 必填 | 说明 | 5651| ------ | ------ | ---- | ------------------------------------------------------------ | 5652| album | string | 否 | 专辑的标题。当前版本为只读参数。 | 5653| albumArtist | string | 否 | 专辑的艺术家。当前版本为只读参数。 | 5654| artist | string | 否 | 媒体资源的艺术家。当前版本为只读参数。 | 5655| author | string | 否 | 媒体资源的作者。当前版本为只读参数。 | 5656| dateTime | string | 否 | 媒体资源的创建时间。当前版本为只读参数。 | 5657| dateTimeFormat | string | 否 | 媒体资源的创建时间，按YYYY-MM-DD HH:mm:ss格式输出。当前版本为只读参数。 | 5658| composer | string | 否 | 媒体资源的作曲家。当前版本为只读参数。 | 5659| duration | string | 否 | 媒体资源的时长。当前版本为只读参数。 | 5660| genre | string | 否 | 媒体资源的类型或体裁。| 5661| hasAudio | string | 否 | 媒体资源是否包含音频。当前版本为只读参数。 | 5662| hasVideo | string | 否 | 媒体资源是否包含视频。当前版本为只读参数。 | 5663| mimeType | string | 否 | 媒体资源的mime类型。当前版本为只读参数。 | 5664| trackCount | string | 否 | 媒体资源的轨道数量。当前版本为只读参数。 | 5665| sampleRate | string | 否 | 音频的采样率，单位为赫兹（Hz）。当前版本为只读参数。 | 5666| title | string | 否 | 媒体资源的标题。当前版本为只读参数。当前版本为只读参数。 | 5667| videoHeight | string | 否 | 视频的高度，单位为像素。当前版本为只读参数。 | 5668| videoWidth | string | 否 | 视频的宽度，单位为像素。当前版本为只读参数。 | 5669| videoOrientation | string | 否 | 视频的旋转方向，单位为度（°）。| 5670| hdrType<sup>12+</sup> | [HdrType](#hdrtype12) | 否 | 媒体资源的HDR类型。当前版本为只读参数。 | 5671| location<sup>12+</sup> | [Location](#location) | 否 | 视频的地理位置信息。 | 5672| customInfo<sup>12+</sup> | Record<string, string> | 否 | 从moov.meta.list 获取的自定义参数键值映射。| 5673 5674## HdrType<sup>12+</sup> 5675 5676表示视频HDR类型的枚举。 5677 5678**系统能力：** SystemCapability.Multimedia.Media.Core 5679 5680| 名称 | 值 | 说明 | 5681| ------------------------- | ---- | ---------------------- | 5682| AV_HDR_TYPE_NONE | 0 | 表示无HDR类型。 | 5683| AV_HDR_TYPE_VIVID | 1 | 表示为HDR VIVID类型。 | 5684 5685## media.createAudioPlayer<sup>(deprecated)</sup> 5686 5687createAudioPlayer(): AudioPlayer 5688 5689同步方式创建音频播放实例。 5690 5691> **说明：** 5692> 从API version 6开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9)替代。 5693 5694**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5695 5696**返回值：** 5697 5698| 类型 | 说明 | 5699| --------------------------- | ------------------------------------------------------------ | 5700| [AudioPlayer](#audioplayerdeprecated) | 返回AudioPlayer类实例，失败时返回null。可用于音频播放、暂停、停止等操作。 | 5701 5702**示例：** 5703 5704```ts 5705let audioPlayer: media.AudioPlayer = media.createAudioPlayer(); 5706``` 5707 5708## media.createVideoPlayer<sup>(deprecated)</sup> 5709 5710createVideoPlayer(callback: AsyncCallback\<VideoPlayer>): void 5711 5712异步方式创建视频播放实例，通过注册回调函数获取返回值。 5713 5714> **说明：** 5715> 从API version 8开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9)替代。 5716 5717**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5718 5719**参数：** 5720 5721| 参数名 | 类型 | 必填 | 说明 | 5722| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 5723| callback | AsyncCallback<[VideoPlayer](#videoplayerdeprecated)> | 是 | 回调函数。创建VideoPlayer实例成功时，err为undefined，data为获取到的VideoPlayer实例，否则为错误对象。 | 5724 5725**示例：** 5726 5727```ts 5728import { BusinessError } from '@kit.BasicServicesKit'; 5729 5730let videoPlayer: media.VideoPlayer; 5731media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 5732 if (video != null) { 5733 videoPlayer = video; 5734 console.info('Succeeded in creating VideoPlayer'); 5735 } else { 5736 console.error(`Failed to create VideoPlayer, error:${error}`); 5737 } 5738}); 5739``` 5740 5741## media.createVideoPlayer<sup>(deprecated)</sup> 5742 5743createVideoPlayer(): Promise\<VideoPlayer> 5744 5745异步方式创建视频播放实例，通过Promise获取返回值。 5746 5747> **说明：** 5748> 从API version 8开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9-1)替代。 5749 5750**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5751 5752**返回值：** 5753 5754| 类型 | 说明 | 5755| ------------------------------------ | ------------------------------------------------------------ | 5756| Promise<[VideoPlayer](#videoplayerdeprecated)> | Promise对象。异步返回VideoPlayer实例，失败时返回null。可用于管理和播放视频媒体。 | 5757 5758**示例：** 5759 5760```ts 5761import { BusinessError } from '@kit.BasicServicesKit'; 5762 5763let videoPlayer: media.VideoPlayer; 5764media.createVideoPlayer().then((video: media.VideoPlayer) => { 5765 if (video != null) { 5766 videoPlayer = video; 5767 console.info('Succeeded in creating VideoPlayer'); 5768 } else { 5769 console.error('Failed to create VideoPlayer'); 5770 } 5771}).catch((error: BusinessError) => { 5772 console.error(`Failed to create VideoPlayer, error:${error}`); 5773}); 5774``` 5775 5776## media.createAudioRecorder<sup>(deprecated)</sup> 5777 5778createAudioRecorder(): AudioRecorder 5779 5780创建音频录制的实例来控制音频的录制。 5781一台设备只允许创建一个录制实例。 5782 5783> **说明：** 5784> 从API version 6开始支持，从API version 9开始废弃，建议使用[createAVRecorder](#mediacreateavrecorder9)替代。 5785 5786**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 5787 5788**返回值:** 5789 5790| 类型 | 说明 | 5791| ------------------------------- | ------------------------------------------------------------ | 5792| [AudioRecorder](#audiorecorderdeprecated) | 返回AudioRecorder类实例，失败时返回null。可用于录制音频媒体。 | 5793 5794**示例：** 5795 5796```ts 5797let audioRecorder: media.AudioRecorder = media.createAudioRecorder(); 5798``` 5799 5800## MediaErrorCode<sup>(deprecated)</sup> 5801 5802媒体服务错误类型枚举。 5803 5804> **说明：** 5805> 从API version 8开始支持，从API version 11开始废弃，建议使用[媒体错误码](#averrorcode9)替代。 5806 5807**系统能力：** SystemCapability.Multimedia.Media.Core 5808 5809| 名称 | 值 | 说明 | 5810| -------------------------- | ---- | -------------------------------------- | 5811| MSERR_OK | 0 | 表示操作成功。 | 5812| MSERR_NO_MEMORY | 1 | 表示申请内存失败，系统可能无可用内存。 | 5813| MSERR_OPERATION_NOT_PERMIT | 2 | 表示无权限执行此操作。 | 5814| MSERR_INVALID_VAL | 3 | 表示传入入参无效。 | 5815| MSERR_IO | 4 | 表示发生IO错误。 | 5816| MSERR_TIMEOUT | 5 | 表示操作超时。 | 5817| MSERR_UNKNOWN | 6 | 表示未知错误。 | 5818| MSERR_SERVICE_DIED | 7 | 表示服务端失效。 | 5819| MSERR_INVALID_STATE | 8 | 表示在当前状态下，不允许执行此操作。 | 5820| MSERR_UNSUPPORTED | 9 | 表示在当前版本下，不支持此操作。 | 5821 5822## AudioPlayer<sup>(deprecated)</sup> 5823 5824> **说明：** 5825> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer](#avplayer9)替代。 5826 5827音频播放管理类，用于管理和播放音频媒体。在调用AudioPlayer的方法前，需要先通过[createAudioPlayer()](#mediacreateaudioplayerdeprecated)构建一个AudioPlayer实例。 5828 5829### 属性<sup>(deprecated)</sup> 5830 5831**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5832 5833| 名称 | 类型 | 只读 | 可选 | 说明 | 5834| ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 5835| 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。 | 5836| 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/> | 5837| loop | boolean | 否 | 否 | 音频循环播放属性，设置为'true'表示循环播放。 | 5838| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9) | 是 | 是 | 音频焦点模型。 | 5839| currentTime | number | 是 | 否 | 音频的当前播放位置，单位为毫秒（ms）。 | 5840| duration | number | 是 | 否 | 音频时长，单位为毫秒（ms）。 | 5841| state | [AudioState](#audiostatedeprecated) | 是 | 否 | 可以查询音频播放的状态，该状态不可作为调用play/pause/stop等状态切换的触发条件。 | 5842 5843### play<sup>(deprecated)</sup> 5844 5845play(): void 5846 5847开始播放音频资源，需在'dataLoad'事件成功触发后，才能调用。 5848 5849> **说明：** 5850> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9)替代。 5851 5852**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5853 5854**示例：** 5855 5856```ts 5857audioPlayer.on('play', () => { //设置'play'事件回调。 5858 console.info('audio play called'); 5859}); 5860audioPlayer.play(); 5861``` 5862 5863### pause<sup>(deprecated)</sup> 5864 5865pause(): void 5866 5867暂停播放音频资源。 5868 5869> **说明：** 5870> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9)替代。 5871 5872**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5873 5874**示例：** 5875 5876```ts 5877audioPlayer.on('pause', () => { //设置'pause'事件回调。 5878 console.info('audio pause called'); 5879}); 5880audioPlayer.pause(); 5881``` 5882 5883### stop<sup>(deprecated)</sup> 5884 5885stop(): void 5886 5887停止播放音频资源。 5888 5889> **说明：** 5890> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9)替代。 5891 5892**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5893 5894**示例：** 5895 5896```ts 5897audioPlayer.on('stop', () => { //设置'stop'事件回调。 5898 console.info('audio stop called'); 5899}); 5900audioPlayer.stop(); 5901``` 5902 5903### reset<sup>(deprecated)</sup> 5904 5905reset(): void 5906 5907重置播放音频资源。 5908 5909> **说明：** 5910> 从API version 7开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9)替代。 5911 5912**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5913 5914**示例：** 5915 5916```ts 5917audioPlayer.on('reset', () => { //设置'reset'事件回调。 5918 console.info('audio reset called'); 5919}); 5920audioPlayer.reset(); 5921``` 5922 5923### seek<sup>(deprecated)</sup> 5924 5925seek(timeMs: number): void 5926 5927跳转到指定播放位置。 5928 5929> **说明：** 5930> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 5931 5932**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5933 5934**参数：** 5935 5936| 参数名 | 类型 | 必填 | 说明 | 5937| ------ | ------ | ---- | ----------------------------------------------------------- | 5938| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围[0, duration]。 | 5939 5940**示例：** 5941 5942```ts 5943audioPlayer.on('timeUpdate', (seekDoneTime: number) => { //设置'timeUpdate'事件回调。 5944 if (seekDoneTime == null) { 5945 console.error('Failed to seek'); 5946 return; 5947 } 5948 console.info('Succeeded in seek. seekDoneTime: ' + seekDoneTime); 5949}); 5950audioPlayer.seek(30000); //seek到30000ms的位置。 5951``` 5952 5953### setVolume<sup>(deprecated)</sup> 5954 5955setVolume(vol: number): void 5956 5957设置音量。 5958 5959> **说明：** 5960> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 5961 5962**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5963 5964**参数：** 5965 5966| 参数名 | 类型 | 必填 | 说明 | 5967| ------ | ------ | ---- | ------------------------------------------------------------ | 5968| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 5969 5970**示例：** 5971 5972```ts 5973audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调。 5974 console.info('audio volumeChange called'); 5975}); 5976audioPlayer.setVolume(1); //设置音量到100%。 5977``` 5978 5979### release<sup>(deprecated)</sup> 5980 5981release(): void 5982 5983释放音频资源。 5984 5985> **说明：** 5986> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9)替代。 5987 5988**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5989 5990**示例：** 5991 5992```ts 5993audioPlayer.release(); 5994audioPlayer = undefined; 5995``` 5996 5997### getTrackDescription<sup>(deprecated)</sup> 5998 5999getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 6000 6001获取音频轨道信息。需在'dataLoad'事件成功触发后，才能调用。通过回调函数获取返回值。 6002 6003> **说明：** 6004> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9)替代。 6005 6006**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6007 6008**参数：** 6009 6010| 参数名 | 类型 | 必填 | 说明 | 6011| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 6012| callback | AsyncCallback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 回调函数。获取音频轨道信息成功时，err为undefined，data为获取到的MediaDescription数组，否则为错误对象。 | 6013 6014**示例：** 6015 6016```ts 6017import { BusinessError } from '@kit.BasicServicesKit'; 6018 6019audioPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 6020 if (arrList != null) { 6021 console.info('Succeeded in getting TrackDescription'); 6022 } else { 6023 console.error(`Failed to get TrackDescription, error:${error}`); 6024 } 6025}); 6026``` 6027 6028### getTrackDescription<sup>(deprecated)</sup> 6029 6030getTrackDescription(): Promise\<Array\<MediaDescription>> 6031 6032获取音频轨道信息。需在'dataLoad'事件成功触发后，才能调用。通过Promise获取返回值。 6033 6034> **说明：** 6035> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9-1)替代。 6036 6037**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6038 6039**返回值：** 6040 6041| 类型 | 说明 | 6042| ------------------------------------------------------ | ----------------------------------------------- | 6043| Promise<Array<[MediaDescription](#mediadescription8)>> | 音频轨道信息MediaDescription数组Promise返回值。 | 6044 6045**示例：** 6046 6047```ts 6048import { BusinessError } from '@kit.BasicServicesKit'; 6049 6050audioPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 6051 console.info('Succeeded in getting TrackDescription'); 6052}).catch((error: BusinessError) => { 6053 console.error(`Failed to get TrackDescription, error:${error}`); 6054}); 6055``` 6056 6057### on('bufferingUpdate')<sup>(deprecated)</sup> 6058 6059on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void 6060 6061开始订阅音频缓存更新事件。仅网络播放支持该订阅事件。 6062 6063> **说明：** 6064> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('bufferingUpdate')](#onbufferingupdate9)替代。 6065 6066**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6067 6068**参数：** 6069 6070| 参数名 | 类型 | 必填 | 说明 | 6071| -------- | -------- | ---- | ------------------------------------------------------------ | 6072| type | string | 是 | 音频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 6073| callback | function | 是 | 音频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)value值固定为0。 | 6074 6075**示例：** 6076 6077```ts 6078audioPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 6079 console.info('audio bufferingInfo type: ' + infoType); 6080 console.info('audio bufferingInfo value: ' + value); 6081}); 6082``` 6083 6084### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')<sup>(deprecated)</sup> 6085 6086on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void): void 6087 6088开始订阅音频播放事件。 6089 6090> **说明：** 6091> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('stateChange')](#onstatechange9)替代。 6092 6093**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6094 6095**参数：** 6096 6097| 参数名 | 类型 | 必填 | 说明 | 6098| -------- | ---------- | ---- | ------------------------------------------------------------ | 6099| 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)调用，播放音量改变后触发该事件。 | 6100| callback | () => void | 是 | 播放事件回调方法。 | 6101 6102**示例：** 6103 6104```ts 6105import { fileIo as fs } from '@kit.CoreFileKit'; 6106import { BusinessError } from '@kit.BasicServicesKit'; 6107 6108let audioPlayer: media.AudioPlayer = media.createAudioPlayer(); //创建一个音频播放实例。 6109audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调，src属性设置成功后，触发此回调。 6110 console.info('audio set source called'); 6111 audioPlayer.play(); //开始播放，并触发'play'事件回调。 6112}); 6113audioPlayer.on('play', () => { //设置'play'事件回调。 6114 console.info('audio play called'); 6115 audioPlayer.seek(30000); //调用seek方法，并触发'timeUpdate'事件回调。 6116}); 6117audioPlayer.on('pause', () => { //设置'pause'事件回调。 6118 console.info('audio pause called'); 6119 audioPlayer.stop(); //停止播放，并触发'stop'事件回调。 6120}); 6121audioPlayer.on('reset', () => { //设置'reset'事件回调。 6122 console.info('audio reset called'); 6123 audioPlayer.release(); //释放播放实例资源。 6124 audioPlayer = undefined; 6125}); 6126audioPlayer.on('timeUpdate', (seekDoneTime: number) => { //设置'timeUpdate'事件回调。 6127 if (seekDoneTime == null) { 6128 console.error('Failed to seek'); 6129 return; 6130 } 6131 console.info('Succeeded in seek, and seek time is ' + seekDoneTime); 6132 audioPlayer.setVolume(0.5); //设置音量为50%，并触发'volumeChange'事件回调。 6133}); 6134audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调。 6135 console.info('audio volumeChange called'); 6136 audioPlayer.pause(); //暂停播放，并触发'pause'事件回调。 6137}); 6138audioPlayer.on('finish', () => { //设置'finish'事件回调。 6139 console.info('audio play finish'); 6140 audioPlayer.stop(); //停止播放，并触发'stop'事件回调。 6141}); 6142audioPlayer.on('error', (error: BusinessError) => { //设置'error'事件回调。 6143 console.error(`audio error called, error: ${error}`); 6144}); 6145 6146// 用户选择音频设置fd(本地播放)。 6147let fdPath = 'fd://'; 6148// path路径的码流可通过"hdc file send D:\xxx\01.mp3 /data/accounts/account_0/appdata" 命令，将其推送到设备上。 6149let path = '/data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3'; 6150fs.open(path).then((file) => { 6151 fdPath = fdPath + '' + file.fd; 6152 console.info('Succeeded in opening fd, fd is' + fdPath); 6153 audioPlayer.src = fdPath; //设置src属性，并触发'dataLoad'事件回调。 6154}, (err: BusinessError) => { 6155 console.error('Failed to open fd, err is' + err); 6156}).catch((err: BusinessError) => { 6157 console.error('Failed to open fd, err is' + err); 6158}); 6159``` 6160 6161### on('timeUpdate')<sup>(deprecated)</sup> 6162 6163on(type: 'timeUpdate', callback: Callback\<number>): void 6164 6165开始订阅音频播放时间更新事件。处于播放状态时，每隔1s上报一次该事件。 6166 6167> **说明：** 6168> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('timeUpdate')](#ontimeupdate9)替代。 6169 6170**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6171 6172**参数：** 6173 6174| 参数名 | 类型 | 必填 | 说明 | 6175| -------- | ----------------- | ---- | ------------------------------------------------------------ | 6176| type | string | 是 | 播放事件回调类型，支持的事件包括：'timeUpdate'。<br>- 'timeUpdate'：音频播放时间戳更新，开始播放后自动触发该事件。 | 6177| callback | Callback\<number> | 是 | 播放事件回调方法。回调方法入参为更新后的时间戳。 | 6178 6179**示例：** 6180 6181```ts 6182audioPlayer.on('timeUpdate', (newTime: number) => { //设置'timeUpdate'事件回调。 6183 if (newTime == null) { 6184 console.error('Failed to do timeUpadate'); 6185 return; 6186 } 6187 console.info('Succeeded in doing timeUpadate. seekDoneTime: ' + newTime); 6188}); 6189audioPlayer.play(); //开始播放后，自动触发时间戳更新事件。 6190``` 6191 6192### on('audioInterrupt')<sup>(deprecated)</sup> 6193 6194on(type: 'audioInterrupt', callback: (info: audio.InterruptEvent) => void): void 6195 6196监听音频焦点变化事件，参考[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)。 6197 6198> **说明：** 6199> 从API version 9开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('audioInterrupt')](#onaudiointerrupt9)替代。 6200 6201**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6202 6203**参数：** 6204 6205| 参数名 | 类型 | 必填 | 说明 | 6206| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 6207| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 6208| callback | function | 是 | 音频焦点变化事件回调方法。 | 6209 6210**示例：** 6211 6212```ts 6213import { audio } from '@kit.AudioKit'; 6214 6215audioPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 6216 console.info('audioInterrupt called,and InterruptEvent info is:' + info) 6217}) 6218``` 6219 6220### on('error')<sup>(deprecated)</sup> 6221 6222on(type: 'error', callback: ErrorCallback): void 6223 6224开始订阅音频播放错误事件，当上报error错误事件后，用户需处理error事件，退出播放操作。 6225 6226> **说明：** 6227> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('error')](#onerror9)替代。 6228 6229**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6230 6231**参数：** 6232 6233| 参数名 | 类型 | 必填 | 说明 | 6234| -------- | ------------- | ---- | ------------------------------------------------------------ | 6235| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：音频播放中发生错误，触发该事件。 | 6236| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 播放错误事件回调方法。 | 6237 6238**示例：** 6239 6240```ts 6241import { BusinessError } from '@kit.BasicServicesKit'; 6242 6243audioPlayer.on('error', (error: BusinessError) => { //设置'error'事件回调。 6244 console.error(`audio error called, error: ${error}`); 6245}); 6246audioPlayer.setVolume(3); //设置volume为无效值，触发'error'事件。 6247``` 6248 6249## AudioState<sup>(deprecated)</sup> 6250 6251type AudioState = 'idle' | 'playing' | 'paused' | 'stopped' | 'error' 6252 6253音频播放的状态机。可通过state属性获取当前状态。 6254 6255> **说明：** 6256> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayerState](#avplayerstate9)替代。 6257 6258**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 6259 6260| 类型 | 说明 | 6261| ------- | ---------------------------------------------- | 6262| 'idle' | 音频播放空闲，dataload/reset成功后处于此状态。 | 6263| 'playing' | 音频正在播放，play成功后处于此状态。 | 6264| 'paused' | 音频暂停播放，pause成功后处于此状态。 | 6265| 'stopped' | 音频播放停止，stop/播放结束后处于此状态。 | 6266| 'error' | 错误状态。 | 6267 6268## VideoPlayer<sup>(deprecated)</sup> 6269 6270> **说明：** 6271> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer](#avplayer9)替代。 6272 6273视频播放管理类，用于管理和播放视频媒体。在调用VideoPlayer的方法前，需要先通过[createVideoPlayer()](#mediacreatevideoplayerdeprecated)构建一个VideoPlayer实例。 6274 6275### 属性 6276 6277**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6278 6279| 名称 | 类型 | 只读 | 可选 | 说明 | 6280| ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 6281| 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。 | 6282| 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/> | 6283| loop<sup>8+</sup> | boolean | 否 | 否 | 视频循环播放属性，设置为'true'表示循环播放。 | 6284| videoScaleType<sup>9+</sup> | [VideoScaleType](#videoscaletype9) | 否 | 是 | 视频缩放模式。默认值为VIDEO_SCALE_TYPE_FIT。 | 6285| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9) | 否 | 是 | 音频焦点模型。 | 6286| currentTime<sup>8+</sup> | number | 是 | 否 | 视频的当前播放位置，单位为毫秒（ms）。 | 6287| duration<sup>8+</sup> | number | 是 | 否 | 视频时长，单位为毫秒（ms），返回-1表示直播模式。 | 6288| state<sup>8+</sup> | [VideoPlayState](#videoplaystatedeprecated) | 是 | 否 | 视频播放的状态。 | 6289| width<sup>8+</sup> | number | 是 | 否 | 视频宽，单位为像素（px）。 | 6290| height<sup>8+</sup> | number | 是 | 否 | 视频高，单位为像素（px）。 | 6291 6292### setDisplaySurface<sup>(deprecated)</sup> 6293 6294setDisplaySurface(surfaceId: string, callback: AsyncCallback\<void>): void 6295 6296设置SurfaceId。通过回调函数获取返回值。 6297 6298*注意：SetDisplaySurface需要在设置url和Prepare之间，无音频的视频流必须设置Surface否则Prepare失败。 6299 6300> **说明：** 6301> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.surfaceId](#属性)替代。 6302 6303**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6304 6305**参数：** 6306 6307| 参数名 | 类型 | 必填 | 说明 | 6308| --------- | -------------------- | ---- | ------------------------- | 6309| surfaceId | string | 是 | SurfaceId. | 6310| callback | AsyncCallback\<void> | 是 | 回调函数。当设置SurfaceId成功，err为undefined，否则为错误对象。 | 6311 6312**示例：** 6313 6314```ts 6315import { BusinessError } from '@kit.BasicServicesKit'; 6316 6317let surfaceId: string = ''; 6318videoPlayer.setDisplaySurface(surfaceId, (err: BusinessError) => { 6319 if (err) { 6320 console.error('Failed to set DisplaySurface!'); 6321 } else { 6322 console.info('Succeeded in setting DisplaySurface!'); 6323 } 6324}); 6325``` 6326 6327### setDisplaySurface<sup>(deprecated)</sup> 6328 6329setDisplaySurface(surfaceId: string): Promise\<void> 6330 6331设置SurfaceId。通过Promise获取返回值。 6332 6333*注意：SetDisplaySurface需要在设置url和Prepare之间，无音频的视频流必须设置Surface否则Prepare失败。 6334 6335> **说明：** 6336> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.surfaceId](#属性)替代。 6337 6338**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6339 6340**参数：** 6341 6342| 参数名 | 类型 | 必填 | 说明 | 6343| --------- | ------ | ---- | --------- | 6344| surfaceId | string | 是 | SurfaceId. | 6345 6346**返回值：** 6347 6348| 类型 | 说明 | 6349| -------------- | ------------------------------ | 6350| Promise\<void> | 设置SurfaceId的Promise返回值。 | 6351 6352**示例：** 6353 6354```ts 6355import { BusinessError } from '@kit.BasicServicesKit'; 6356 6357let surfaceId: string = ''; 6358videoPlayer.setDisplaySurface(surfaceId).then(() => { 6359 console.info('Succeeded in setting DisplaySurface'); 6360}).catch((error: BusinessError) => { 6361 console.error(`video catchCallback, error:${error}`); 6362}); 6363``` 6364 6365### prepare<sup>(deprecated)</sup> 6366 6367prepare(callback: AsyncCallback\<void>): void 6368 6369准备播放视频。通过回调函数获取返回值。 6370 6371> **说明：** 6372> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.prepare](#prepare9)替代。 6373 6374**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6375 6376**参数：** 6377 6378| 参数名 | 类型 | 必填 | 说明 | 6379| -------- | -------------------- | ---- | ------------------------ | 6380| callback | AsyncCallback\<void> | 是 | 回调函数。当准备播放视频成功，err为undefined，否则为错误对象。| 6381 6382**示例：** 6383 6384```ts 6385import { BusinessError } from '@kit.BasicServicesKit'; 6386 6387videoPlayer.prepare((err: BusinessError) => { 6388 if (err) { 6389 console.error('Failed to prepare!'); 6390 } else { 6391 console.info('Succeeded in preparing!'); 6392 } 6393}); 6394``` 6395 6396### prepare<sup>(deprecated)</sup> 6397 6398prepare(): Promise\<void> 6399 6400准备播放视频。通过Promise获取返回值。 6401 6402> **说明：** 6403> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.prepare](#prepare9-1)替代。 6404 6405**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6406 6407**返回值：** 6408 6409| 类型 | 说明 | 6410| -------------- | ----------------------------- | 6411| Promise\<void> | 准备播放视频的Promise返回值。 | 6412 6413**示例：** 6414 6415```ts 6416import { BusinessError } from '@kit.BasicServicesKit'; 6417 6418videoPlayer.prepare().then(() => { 6419 console.info('Succeeded in preparing'); 6420}).catch((error: BusinessError) => { 6421 console.error(`video catchCallback, error:${error}`); 6422}); 6423``` 6424 6425### play<sup>(deprecated)</sup> 6426 6427play(callback: AsyncCallback\<void>): void 6428 6429开始播放视频。通过回调函数获取返回值。 6430 6431> **说明：** 6432> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9)替代。 6433 6434**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6435 6436**参数：** 6437 6438| 参数名 | 类型 | 必填 | 说明 | 6439| -------- | -------------------- | ---- | ------------------------ | 6440| callback | AsyncCallback\<void> | 是 | 回调函数。当开始播放视频成功，err为undefined，否则为错误对象。 | 6441 6442**示例：** 6443 6444```ts 6445import { BusinessError } from '@kit.BasicServicesKit'; 6446 6447videoPlayer.play((err: BusinessError) => { 6448 if (err) { 6449 console.error('Failed to play!'); 6450 } else { 6451 console.info('Succeeded in playing!'); 6452 } 6453}); 6454``` 6455 6456### play<sup>(deprecated)</sup> 6457 6458play(): Promise\<void> 6459 6460开始播放视频。通过Promise获取返回值。 6461 6462> **说明：** 6463> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9-1)替代。 6464 6465**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6466 6467**返回值：** 6468 6469| 类型 | 说明 | 6470| -------------- | ----------------------------- | 6471| Promise\<void> | 开始播放视频的Promise返回值。 | 6472 6473**示例：** 6474 6475```ts 6476import { BusinessError } from '@kit.BasicServicesKit'; 6477 6478videoPlayer.play().then(() => { 6479 console.info('Succeeded in playing'); 6480}).catch((error: BusinessError) => { 6481 console.error(`video catchCallback, error:${error}`); 6482}); 6483``` 6484 6485### pause<sup>(deprecated)</sup> 6486 6487pause(callback: AsyncCallback\<void>): void 6488 6489通过回调方式暂停播放视频。通过回调函数获取返回值。 6490 6491> **说明：** 6492> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9)替代。 6493 6494**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6495 6496**参数：** 6497 6498| 参数名 | 类型 | 必填 | 说明 | 6499| -------- | -------------------- | ---- | ------------------------ | 6500| callback | AsyncCallback\<void> | 是 | 回调函数。当暂停播放视频成功，err为undefined，否则为错误对象。 | 6501 6502**示例：** 6503 6504```ts 6505import { BusinessError } from '@kit.BasicServicesKit'; 6506 6507videoPlayer.pause((err: BusinessError) => { 6508 if (err) { 6509 console.error('Failed to pause!'); 6510 } else { 6511 console.info('Succeeded in pausing!'); 6512 } 6513}); 6514``` 6515 6516### pause<sup>(deprecated)</sup> 6517 6518pause(): Promise\<void> 6519 6520暂停播放视频。通过Promise获取返回值。 6521 6522> **说明：** 6523> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9-1)替代。 6524 6525**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6526 6527**返回值：** 6528 6529| 类型 | 说明 | 6530| -------------- | ----------------------------- | 6531| Promise\<void> | 暂停播放视频的Promise返回值。 | 6532 6533**示例：** 6534 6535```ts 6536import { BusinessError } from '@kit.BasicServicesKit'; 6537 6538videoPlayer.pause().then(() => { 6539 console.info('Succeeded in pausing'); 6540}).catch((error: BusinessError) => { 6541 console.error(`video catchCallback, error:${error}`); 6542}); 6543``` 6544 6545### stop<sup>(deprecated)</sup> 6546 6547stop(callback: AsyncCallback\<void>): void 6548 6549通过回调方式停止播放视频。通过回调函数获取返回值。 6550 6551> **说明：** 6552> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9)替代。 6553 6554**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6555 6556**参数：** 6557 6558| 参数名 | 类型 | 必填 | 说明 | 6559| -------- | -------------------- | ---- | ------------------------ | 6560| callback | AsyncCallback\<void> | 是 | 回调函数。当停止播放视频成功，err为undefined，否则为错误对象。 | 6561 6562**示例：** 6563 6564```ts 6565import { BusinessError } from '@kit.BasicServicesKit'; 6566 6567videoPlayer.stop((err: BusinessError) => { 6568 if (err) { 6569 console.error('Failed to stop!'); 6570 } else { 6571 console.info('Succeeded in stopping!'); 6572 } 6573}); 6574``` 6575 6576### stop<sup>(deprecated)</sup> 6577 6578stop(): Promise\<void> 6579 6580停止播放视频。通过Promise获取返回值。 6581 6582> **说明：** 6583> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9-1)替代。 6584 6585**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6586 6587**返回值：** 6588 6589| 类型 | 说明 | 6590| -------------- | ----------------------------- | 6591| Promise\<void> | 停止播放视频的Promise返回值。 | 6592 6593**示例：** 6594 6595```ts 6596import { BusinessError } from '@kit.BasicServicesKit'; 6597 6598videoPlayer.stop().then(() => { 6599 console.info('Succeeded in stopping'); 6600}).catch((error: BusinessError) => { 6601 console.error(`video catchCallback, error:${error}`); 6602}); 6603``` 6604 6605### reset<sup>(deprecated)</sup> 6606 6607reset(callback: AsyncCallback\<void>): void 6608 6609重置播放视频。通过回调函数获取返回值。 6610 6611> **说明：** 6612> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9)替代。 6613 6614**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6615 6616**参数：** 6617 6618| 参数名 | 类型 | 必填 | 说明 | 6619| -------- | -------------------- | ---- | ------------------------ | 6620| callback | AsyncCallback\<void> | 是 | 回调函数。当重置播放视频成功，err为undefined，否则为错误对象。 | 6621 6622**示例：** 6623 6624```ts 6625import { BusinessError } from '@kit.BasicServicesKit'; 6626 6627videoPlayer.reset((err: BusinessError) => { 6628 if (err) { 6629 console.error('Failed to reset!'); 6630 } else { 6631 console.info('Succeeded in resetting!'); 6632 } 6633}); 6634``` 6635 6636### reset<sup>(deprecated)</sup> 6637 6638reset(): Promise\<void> 6639 6640重置播放视频。通过Promise获取返回值。 6641 6642> **说明：** 6643> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9-1)替代。 6644 6645**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6646 6647**返回值：** 6648 6649| 类型 | 说明 | 6650| -------------- | ----------------------------- | 6651| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6652 6653**示例：** 6654 6655```ts 6656import { BusinessError } from '@kit.BasicServicesKit'; 6657 6658videoPlayer.reset().then(() => { 6659 console.info('Succeeded in resetting'); 6660}).catch((error: BusinessError) => { 6661 console.error(`video catchCallback, error:${error}`); 6662}); 6663``` 6664 6665### seek<sup>(deprecated)</sup> 6666 6667seek(timeMs: number, callback: AsyncCallback\<number>): void 6668 6669跳转到指定播放位置，默认跳转到指定时间点的上一个关键帧。通过回调函数获取返回值。 6670 6671> **说明：** 6672> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6673 6674**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6675 6676**参数：** 6677 6678| 参数名 | 类型 | 必填 | 说明 | 6679| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 6680| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6681| callback | AsyncCallback\<number> | 是 | 回调函数。跳转到指定播放位置成功时，err为undefined，data为获取到的跳转到的播放位置，否则为错误对象。 | 6682 6683**示例：** 6684 6685```ts 6686import { BusinessError } from '@kit.BasicServicesKit'; 6687 6688let videoPlayer: media.VideoPlayer; 6689media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6690 if (video != null) { 6691 videoPlayer = video; 6692 console.info('Succeeded in creating VideoPlayer'); 6693 } else { 6694 console.error(`Failed to create VideoPlayer, error:${error}`); 6695 } 6696}); 6697 6698let seekTime: number = 5000; 6699videoPlayer.seek(seekTime, (err: BusinessError, result: number) => { 6700 if (err) { 6701 console.error('Failed to do seek!'); 6702 } else { 6703 console.info('Succeeded in doing seek!'); 6704 } 6705}); 6706``` 6707 6708### seek<sup>(deprecated)</sup> 6709 6710seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\<number>): void 6711 6712跳转到指定播放位置。通过回调函数获取返回值。 6713 6714> **说明：** 6715> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6716 6717**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6718 6719**参数：** 6720 6721| 参数名 | 类型 | 必填 | 说明 | 6722| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 6723| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6724| mode | [SeekMode](#seekmode8) | 是 | 跳转模式。 | 6725| callback | AsyncCallback\<number> | 是 | 回调函数。跳转到指定播放位置成功时，err为undefined，data为获取到的跳转到的播放位置，否则为错误对象。 | 6726 6727**示例：** 6728 6729```ts 6730import { BusinessError } from '@kit.BasicServicesKit'; 6731 6732let videoPlayer: media.VideoPlayer | null = null; 6733media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6734 if (video != null) { 6735 videoPlayer = video; 6736 console.info('Succeeded in creating VideoPlayer'); 6737 } else { 6738 console.error(`Failed to create VideoPlayer, error:${error}`); 6739 } 6740}); 6741let seekTime: number = 5000; 6742if (videoPlayer) { 6743 (videoPlayer as media.VideoPlayer).seek(seekTime, media.SeekMode.SEEK_NEXT_SYNC, (err: BusinessError, result: number) => { 6744 if (err) { 6745 console.error('Failed to do seek!'); 6746 } else { 6747 console.info('Succeeded in doing seek!'); 6748 } 6749 }); 6750} 6751``` 6752 6753### seek<sup>(deprecated)</sup> 6754 6755seek(timeMs: number, mode?:SeekMode): Promise\<number> 6756 6757跳转到指定播放位置，如果没有设置mode则跳转到指定时间点的上一个关键帧。通过Promise获取返回值。 6758 6759> **说明：** 6760> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6761 6762**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6763 6764**参数：** 6765 6766| 参数名 | 类型 | 必填 | 说明 | 6767| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 6768| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6769| mode | [SeekMode](#seekmode8) | 否 | 基于视频I帧的跳转模式，默认为SEEK_PREV_SYNC模式。 | 6770 6771**返回值：** 6772 6773| 类型 | 说明 | 6774| ---------------- | ------------------------------------------- | 6775| Promise\<number> | 跳转到指定播放位置的Promise返回值，单位ms。 | 6776 6777**示例：** 6778 6779```ts 6780import { BusinessError } from '@kit.BasicServicesKit'; 6781 6782let videoPlayer: media.VideoPlayer | null = null; 6783media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6784 if (video != null) { 6785 videoPlayer = video; 6786 console.info('Succeeded in creating VideoPlayer'); 6787 } else { 6788 console.error(`Failed to create VideoPlayer, error:${error}`); 6789 } 6790}); 6791let seekTime: number = 5000; 6792if (videoPlayer) { 6793 (videoPlayer as media.VideoPlayer).seek(seekTime).then((seekDoneTime: number) => { // seekDoneTime表示seek完成后的时间点。 6794 console.info('Succeeded in doing seek'); 6795 }).catch((error: BusinessError) => { 6796 console.error(`video catchCallback, error:${error}`); 6797 }); 6798 6799 (videoPlayer as media.VideoPlayer).seek(seekTime, media.SeekMode.SEEK_NEXT_SYNC).then((seekDoneTime: number) => { 6800 console.info('Succeeded in doing seek'); 6801 }).catch((error: BusinessError) => { 6802 console.error(`video catchCallback, error:${error}`); 6803 }); 6804} 6805``` 6806 6807### setVolume<sup>(deprecated)</sup> 6808 6809setVolume(vol: number, callback: AsyncCallback\<void>): void 6810 6811设置音量。通过回调函数获取返回值。 6812 6813> **说明：** 6814> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 6815 6816**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6817 6818**参数：** 6819 6820| 参数名 | 类型 | 必填 | 说明 | 6821| -------- | -------------------- | ---- | ------------------------------------------------------------ | 6822| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 6823| callback | AsyncCallback\<void> | 是 | 回调函数。当设置音量成功，err为undefined，否则为错误对象。 | 6824 6825**示例：** 6826 6827```ts 6828import { BusinessError } from '@kit.BasicServicesKit'; 6829 6830let vol: number = 0.5; 6831videoPlayer.setVolume(vol, (err: BusinessError) => { 6832 if (err) { 6833 console.error('Failed to set Volume!'); 6834 } else { 6835 console.info('Succeeded in setting Volume!'); 6836 } 6837}); 6838``` 6839 6840### setVolume<sup>(deprecated)</sup> 6841 6842setVolume(vol: number): Promise\<void> 6843 6844设置音量。通过Promise获取返回值。 6845 6846> **说明：** 6847> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 6848 6849**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6850 6851**参数：** 6852 6853| 参数名 | 类型 | 必填 | 说明 | 6854| ------ | ------ | ---- | ------------------------------------------------------------ | 6855| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 6856 6857**返回值：** 6858 6859| 类型 | 说明 | 6860| -------------- | ------------------------- | 6861| Promise\<void> | 设置音量的Promise返回值。 | 6862 6863**示例：** 6864 6865```ts 6866import { BusinessError } from '@kit.BasicServicesKit'; 6867 6868let vol: number = 0.5; 6869videoPlayer.setVolume(vol).then(() => { 6870 console.info('Succeeded in setting Volume'); 6871}).catch((error: BusinessError) => { 6872 console.error(`video catchCallback, error:${error}`); 6873}); 6874``` 6875 6876### release<sup>(deprecated)</sup> 6877 6878release(callback: AsyncCallback\<void>): void 6879 6880释放视频资源。通过回调函数获取返回值。 6881 6882> **说明：** 6883> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9)替代。 6884 6885**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6886 6887**参数：** 6888 6889| 参数名 | 类型 | 必填 | 说明 | 6890| -------- | -------------------- | ---- | ------------------------ | 6891| callback | AsyncCallback\<void> | 是 | 回调函数。当释放视频资源成功，err为undefined，否则为错误对象。 | 6892 6893**示例：** 6894 6895```ts 6896import { BusinessError } from '@kit.BasicServicesKit'; 6897 6898videoPlayer.release((err: BusinessError) => { 6899 if (err) { 6900 console.error('Failed to release!'); 6901 } else { 6902 console.info('Succeeded in releasing!'); 6903 } 6904}); 6905``` 6906 6907### release<sup>(deprecated)</sup> 6908 6909release(): Promise\<void> 6910 6911释放视频资源。通过Promise获取返回值。 6912 6913> **说明：** 6914> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9-1)替代。 6915 6916**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6917 6918**返回值：** 6919 6920| 类型 | 说明 | 6921| -------------- | ----------------------------- | 6922| Promise\<void> | 释放视频资源的Promise返回值。 | 6923 6924**示例：** 6925 6926```ts 6927import { BusinessError } from '@kit.BasicServicesKit'; 6928 6929videoPlayer.release().then(() => { 6930 console.info('Succeeded in releasing'); 6931}).catch((error: BusinessError) => { 6932 console.error(`video catchCallback, error:${error}`); 6933}); 6934``` 6935 6936### getTrackDescription<sup>(deprecated)</sup> 6937 6938getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 6939 6940获取视频轨道信息。通过回调函数获取返回值。 6941 6942> **说明：** 6943> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9)替代。 6944 6945**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6946 6947**参数：** 6948 6949| 参数名 | 类型 | 必填 | 说明 | 6950| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 6951| callback | AsyncCallback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 回调函数。获取视频轨道信息成功时，err为undefined，data为获取到的视频轨道信息MediaDescription数组，否则为错误对象。 | 6952 6953**示例：** 6954 6955```ts 6956import { BusinessError } from '@kit.BasicServicesKit'; 6957 6958videoPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 6959 if ((arrList) != null) { 6960 console.info('Succeeded in getting TrackDescription'); 6961 } else { 6962 console.error(`Failed to get TrackDescription, error:${error}`); 6963 } 6964}); 6965``` 6966 6967### getTrackDescription<sup>(deprecated)</sup> 6968 6969getTrackDescription(): Promise\<Array\<MediaDescription>> 6970 6971获取视频轨道信息。通过Promise获取返回值。 6972 6973> **说明：** 6974> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9-1)替代。 6975 6976**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6977 6978**返回值：** 6979 6980| 类型 | 说明 | 6981| ------------------------------------------------------ | ----------------------------------------------- | 6982| Promise<Array<[MediaDescription](#mediadescription8)>> | Promise对象，返回获取的视频轨道信息MediaDescription数组。 | 6983 6984**示例：** 6985 6986```ts 6987import { BusinessError } from '@kit.BasicServicesKit'; 6988 6989videoPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 6990 if (arrList != null) { 6991 console.info('Succeeded in getting TrackDescription'); 6992 } else { 6993 console.error('Failed to get TrackDescription'); 6994 } 6995}).catch((error: BusinessError) => { 6996 console.error(`video catchCallback, error:${error}`); 6997}); 6998``` 6999 7000### setSpeed<sup>(deprecated)</sup> 7001 7002setSpeed(speed: number, callback: AsyncCallback\<number>): void 7003 7004设置播放速度。通过回调函数获取返回值。 7005 7006> **说明：** 7007> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setSpeed](#setspeed9)替代。 7008 7009**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7010 7011**参数：** 7012 7013| 参数名 | 类型 | 必填 | 说明 | 7014| -------- | ---------------------- | ---- | ---------------------------------------------------------- | 7015| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 7016| callback | AsyncCallback\<number> | 是 | 回调函数。设置播放速度成功时，err为undefined，data为设置的播放速度，否则为错误对象。 | 7017 7018**示例：** 7019 7020```ts 7021import { BusinessError } from '@kit.BasicServicesKit'; 7022 7023let videoPlayer: media.VideoPlayer | null = null; 7024media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 7025 if (video != null) { 7026 videoPlayer = video; 7027 console.info('Succeeded in creating VideoPlayer'); 7028 } else { 7029 console.error(`Failed to create VideoPlayer, error:${error}`); 7030 } 7031}); 7032let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X; 7033if (videoPlayer) { 7034 (videoPlayer as media.VideoPlayer).setSpeed(speed, (err: BusinessError, result: number) => { 7035 if (err) { 7036 console.error('Failed to set Speed!'); 7037 } else { 7038 console.info('Succeeded in setting Speed!'); 7039 } 7040 }); 7041} 7042``` 7043 7044### setSpeed<sup>(deprecated)</sup> 7045 7046setSpeed(speed: number): Promise\<number> 7047 7048设置播放速度。通过Promise获取返回值。 7049 7050> **说明：** 7051> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setSpeed](#setspeed9)替代。 7052 7053**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7054 7055**参数：** 7056 7057| 参数名 | 类型 | 必填 | 说明 | 7058| ------ | ------ | ---- | ---------------------------------------------------------- | 7059| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 7060 7061**返回值：** 7062 7063| 类型 | 说明 | 7064| ---------------- | ------------------------------------------------------------ | 7065| Promise\<number> | Promise对象，返回设置的播放速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 7066 7067**示例：** 7068 7069```ts 7070import { BusinessError } from '@kit.BasicServicesKit'; 7071 7072let videoPlayer: media.VideoPlayer | null = null; 7073media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 7074 if (video != null) { 7075 videoPlayer = video; 7076 console.info('Succeeded in creating VideoPlayer'); 7077 } else { 7078 console.error(`Failed to create VideoPlayer, error:${error}`); 7079 } 7080}); 7081let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X; 7082if (videoPlayer) { 7083 (videoPlayer as media.VideoPlayer).setSpeed(speed).then((result: number) => { 7084 console.info('Succeeded in setting Speed'); 7085 }).catch((error: BusinessError) => { 7086 console.error(`Failed to set Speed, error:${error}`);//todo:: error. 7087 }); 7088} 7089``` 7090 7091### on('playbackCompleted')<sup>(deprecated)</sup> 7092 7093on(type: 'playbackCompleted', callback: Callback\<void>): void 7094 7095开始监听视频播放完成事件。 7096 7097> **说明：** 7098> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('stateChange')](#onstatechange9)替代。 7099 7100**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7101 7102**参数：** 7103 7104| 参数名 | 类型 | 必填 | 说明 | 7105| -------- | -------- | ---- | ----------------------------------------------------------- | 7106| type | string | 是 | 视频播放完成事件回调类型，支持的事件：'playbackCompleted'。 | 7107| callback | Callback\<void> | 是 | 视频播放完成事件回调方法。 | 7108 7109**示例：** 7110 7111```ts 7112videoPlayer.on('playbackCompleted', () => { 7113 console.info('playbackCompleted called!'); 7114}); 7115``` 7116 7117### on('bufferingUpdate')<sup>(deprecated)</sup> 7118 7119on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void 7120 7121开始监听视频缓存更新事件。仅网络播放支持该订阅事件。 7122 7123> **说明：** 7124> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('bufferingUpdate')](#onbufferingupdate9)替代。 7125 7126**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7127 7128**参数：** 7129 7130| 参数名 | 类型 | 必填 | 说明 | 7131| -------- | -------- | ---- | ------------------------------------------------------------ | 7132| type | string | 是 | 视频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 7133| callback | function | 是 | 视频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)value值固定为0。 | 7134 7135**示例：** 7136 7137```ts 7138videoPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 7139 console.info('video bufferingInfo type: ' + infoType); 7140 console.info('video bufferingInfo value: ' + value); 7141}); 7142``` 7143 7144### on('startRenderFrame')<sup>(deprecated)</sup> 7145 7146on(type: 'startRenderFrame', callback: Callback\<void>): void 7147 7148开始监听视频播放首帧送显上报事件。 7149 7150> **说明：** 7151> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('startRenderFrame')](#onstartrenderframe9)替代。 7152 7153**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7154 7155**参数：** 7156 7157| 参数名 | 类型 | 必填 | 说明 | 7158| -------- | --------------- | ---- | ------------------------------------------------------------ | 7159| type | string | 是 | 视频播放首帧送显上报事件回调类型，支持的事件：'startRenderFrame'。 | 7160| callback | Callback\<void> | 是 | 视频播放首帧送显上报事件回调方法。 | 7161 7162**示例：** 7163 7164```ts 7165videoPlayer.on('startRenderFrame', () => { 7166 console.info('startRenderFrame called!'); 7167}); 7168``` 7169 7170### on('videoSizeChanged')<sup>(deprecated)</sup> 7171 7172on(type: 'videoSizeChanged', callback: (width: number, height: number) => void): void 7173 7174开始监听视频播放宽高变化事件。 7175 7176> **说明：** 7177> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('videoSizeChange')](#onvideosizechange9)替代。 7178 7179**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7180 7181**参数：** 7182 7183| 参数名 | 类型 | 必填 | 说明 | 7184| -------- | -------- | ---- | ------------------------------------------------------------ | 7185| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChanged'。 | 7186| callback | function | 是 | 视频播放宽高变化事件回调方法，width表示宽，height表示高。 | 7187 7188**示例：** 7189 7190```ts 7191videoPlayer.on('videoSizeChanged', (width: number, height: number) => { 7192 console.info('video width is: ' + width); 7193 console.info('video height is: ' + height); 7194}); 7195``` 7196### on('audioInterrupt')<sup>(deprecated)</sup> 7197 7198on(type: 'audioInterrupt', callback: (info: audio.InterruptEvent) => void): void 7199 7200监听音频焦点变化事件，参考[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)。 7201 7202> **说明：** 7203> 从API version 9开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('audioInterrupt')](#onaudiointerrupt9)替代。 7204 7205**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7206 7207**参数：** 7208 7209| 参数名 | 类型 | 必填 | 说明 | 7210| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 7211| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 7212| callback | function | 是 | 音频焦点变化事件回调方法。 | 7213 7214**示例：** 7215 7216```ts 7217import { audio } from '@kit.AudioKit'; 7218 7219videoPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 7220 console.info('audioInterrupt called,and InterruptEvent info is:' + info) 7221}) 7222``` 7223 7224### on('error')<sup>(deprecated)</sup> 7225 7226on(type: 'error', callback: ErrorCallback): void 7227 7228开始监听视频播放错误事件，当上报error错误事件后，用户需处理error事件，退出播放操作。 7229 7230> **说明：** 7231> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('error')](#onerror9)替代。 7232 7233**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7234 7235**参数：** 7236 7237| 参数名 | 类型 | 必填 | 说明 | 7238| -------- | ------------- | ---- | ------------------------------------------------------------ | 7239| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：视频播放中发生错误，触发该事件。 | 7240| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 播放错误事件回调方法。 | 7241 7242**示例：** 7243 7244```ts 7245import { BusinessError } from '@kit.BasicServicesKit'; 7246 7247videoPlayer.on('error', (error: BusinessError) => { // 设置'error'事件回调。 7248 console.error(`video error called, error: ${error}`); 7249}); 7250videoPlayer.url = 'fd://error'; //设置错误的播放地址，触发'error'事件。 7251``` 7252 7253## VideoPlayState<sup>(deprecated)</sup> 7254 7255type VideoPlayState = 'idle' | 'prepared' | 'playing' | 'paused' | 'stopped' | 'error' 7256 7257视频播放的状态机，可通过state属性获取当前状态。 7258 7259> **说明：** 7260> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayerState](#avplayerstate9)替代。 7261 7262**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 7263 7264| 类型 | 说明 | 7265| -------- | -------------- | 7266| 'idle' | 视频播放空闲。 | 7267| 'prepared' | 视频播放准备。 | 7268| 'playing' | 视频正在播放。 | 7269| 'paused' | 视频暂停播放。 | 7270| 'stopped' | 视频播放停止。 | 7271| 'error' | 错误状态。 | 7272 7273## AudioRecorder<sup>(deprecated)</sup> 7274 7275> **说明：** 7276> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder](#avrecorder9)替代。 7277 7278音频录制管理类，用于录制音频媒体。在调用AudioRecorder的方法前，需要先通过[createAudioRecorder()](#mediacreateaudiorecorderdeprecated) 构建一个AudioRecorder实例。 7279 7280### prepare<sup>(deprecated)</sup> 7281 7282prepare(config: AudioRecorderConfig): void 7283 7284录音准备。 7285 7286> **说明：** 7287> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.prepare](#prepare9-2)替代。 7288 7289**需要权限：** ohos.permission.MICROPHONE 7290 7291**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7292 7293**参数：** 7294 7295| 参数名 | 类型 | 必填 | 说明 | 7296| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ | 7297| config | [AudioRecorderConfig](#audiorecorderconfigdeprecated) | 是 | 配置录音的相关参数，包括音频输出URI、编码格式、采样率、声道数、输出格式等。 | 7298 7299**错误码：** 7300 7301以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7302 7303| 错误码ID | 错误信息 | 7304| -------- | --------------------- | 7305| 201 | permission denied | 7306 7307**示例：** 7308 7309```ts 7310let audioRecorderConfig: media.AudioRecorderConfig = { 7311 audioEncoder : media.AudioEncoder.AAC_LC, 7312 audioEncodeBitRate : 22050, 7313 audioSampleRate : 22050, 7314 numberOfChannels : 2, 7315 format : media.AudioOutputFormat.AAC_ADTS, 7316 uri : 'fd://1', // 文件需先由调用者创建，并给予适当的权限。 7317 location : { latitude : 30, longitude : 130}, 7318} 7319audioRecorder.on('prepare', () => { //设置'prepare'事件回调。 7320 console.info('prepare called'); 7321}); 7322audioRecorder.prepare(audioRecorderConfig); 7323``` 7324 7325### start<sup>(deprecated)</sup> 7326 7327start(): void 7328 7329开始录制，需在'prepare'事件成功触发后，才能调用start方法。 7330 7331> **说明：** 7332> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.start](#start9)替代。 7333 7334**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7335 7336**示例：** 7337 7338```ts 7339audioRecorder.on('start', () => { //设置'start'事件回调。 7340 console.info('audio recorder start called'); 7341}); 7342audioRecorder.start(); 7343``` 7344 7345### pause<sup>(deprecated)</sup> 7346 7347pause():void 7348 7349暂停录制，需要在'start'事件成功触发后，才能调用pause方法。 7350 7351> **说明：** 7352> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.pause](#pause9-2)替代。 7353 7354**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7355 7356**示例：** 7357 7358```ts 7359audioRecorder.on('pause', () => { //设置'pause'事件回调。 7360 console.info('audio recorder pause called'); 7361}); 7362audioRecorder.pause(); 7363``` 7364 7365### resume<sup>(deprecated)</sup> 7366 7367resume():void 7368 7369恢复录制，需要在'pause'事件成功触发后，才能调用resume方法。 7370 7371> **说明：** 7372> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.resume](#resume9)替代。 7373 7374**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7375 7376**示例：** 7377 7378```ts 7379audioRecorder.on('resume', () => { //设置'resume'事件回调。 7380 console.info('audio recorder resume called'); 7381}); 7382audioRecorder.resume(); 7383``` 7384 7385### stop<sup>(deprecated)</sup> 7386 7387stop(): void 7388 7389停止录音。 7390 7391> **说明：** 7392> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.stop](#stop9-2)替代。 7393 7394**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7395 7396**示例：** 7397 7398```ts 7399audioRecorder.on('stop', () => { //设置'stop'事件回调。 7400 console.info('audio recorder stop called'); 7401}); 7402audioRecorder.stop(); 7403``` 7404 7405### release<sup>(deprecated)</sup> 7406 7407release(): void 7408 7409释放录音资源。 7410 7411> **说明：** 7412> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.release](#release9-2)替代。 7413 7414**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7415 7416**示例：** 7417 7418```ts 7419audioRecorder.on('release', () => { //设置'release'事件回调。 7420 console.info('audio recorder release called'); 7421}); 7422audioRecorder.release(); 7423audioRecorder = undefined; 7424``` 7425 7426### reset<sup>(deprecated)</sup> 7427 7428reset(): void 7429 7430重置录音。 7431 7432进行重置录音之前，需要先调用stop()停止录音。重置录音之后，需要调用prepare()设置录音参数项，才能再次进行录音。 7433 7434> **说明：** 7435> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.reset](#reset9-2)替代。 7436 7437**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7438 7439**示例：** 7440 7441```ts 7442audioRecorder.on('reset', () => { //设置'reset'事件回调。 7443 console.info('audio recorder reset called'); 7444}); 7445audioRecorder.reset(); 7446``` 7447 7448### on('prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset')<sup>(deprecated)</sup> 7449 7450on(type: 'prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset', callback: () => void): void 7451 7452开始订阅音频录制事件。 7453 7454> **说明：** 7455> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.on('stateChange')](#onstatechange9-1)替代。 7456 7457**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7458 7459**参数：** 7460 7461| 参数名 | 类型 | 必填 | 说明 | 7462| -------- | -------- | ---- | ------------------------------------------------------------ | 7463| 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调用，音频重置为初始状态，触发该事件。 | 7464| callback | ()=>void | 是 | 录制事件回调方法。 | 7465 7466**示例：** 7467 7468```ts 7469import { BusinessError } from '@kit.BasicServicesKit'; 7470 7471let audioRecorder: media.AudioRecorder = media.createAudioRecorder(); // 创建一个音频录制实例。 7472let audioRecorderConfig: media.AudioRecorderConfig = { 7473 audioEncoder : media.AudioEncoder.AAC_LC, 7474 audioEncodeBitRate : 22050, 7475 audioSampleRate : 22050, 7476 numberOfChannels : 2, 7477 format : media.AudioOutputFormat.AAC_ADTS, 7478 uri : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限。 7479 location : { latitude : 30, longitude : 130} 7480} 7481audioRecorder.on('error', (error: BusinessError) => { // 设置'error'事件回调。 7482 console.error(`audio error called, error: ${error}`); 7483}); 7484audioRecorder.on('prepare', () => { // 设置'prepare'事件回调。 7485 console.info('prepare called'); 7486 audioRecorder.start(); // 开始录制，并触发'start'事件回调。 7487}); 7488audioRecorder.on('start', () => { // 设置'start'事件回调。 7489 console.info('audio recorder start called'); 7490}); 7491audioRecorder.on('pause', () => { // 设置'pause'事件回调。 7492 console.info('audio recorder pause called'); 7493}); 7494audioRecorder.on('resume', () => { // 设置'resume'事件回调。 7495 console.info('audio recorder resume called'); 7496}); 7497audioRecorder.on('stop', () => { // 设置'stop'事件回调。 7498 console.info('audio recorder stop called'); 7499}); 7500audioRecorder.on('release', () => { // 设置'release'事件回调。 7501 console.info('audio recorder release called'); 7502}); 7503audioRecorder.on('reset', () => { // 设置'reset'事件回调。 7504 console.info('audio recorder reset called'); 7505}); 7506audioRecorder.prepare(audioRecorderConfig) // 设置录制参数 ，并触发'prepare'事件回调。 7507``` 7508 7509### on('error')<sup>(deprecated)</sup> 7510 7511on(type: 'error', callback: ErrorCallback): void 7512 7513开始订阅音频录制错误事件，当上报error错误事件后，用户需处理error事件，退出录制操作。 7514 7515> **说明：** 7516> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.on('error')](#onerror9-1)替代。 7517 7518**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7519 7520**参数：** 7521 7522| 参数名 | 类型 | 必填 | 说明 | 7523| -------- | ------------- | ---- | ------------------------------------------------------------ | 7524| type | string | 是 | 录制错误事件回调类型'error'。<br/>- 'error'：音频录制过程中发生错误，触发该事件。 | 7525| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录制错误事件回调方法。 | 7526 7527**示例：** 7528 7529```ts 7530import { BusinessError } from '@kit.BasicServicesKit'; 7531 7532let audioRecorderConfig: media.AudioRecorderConfig = { 7533 audioEncoder : media.AudioEncoder.AAC_LC, 7534 audioEncodeBitRate : 22050, 7535 audioSampleRate : 22050, 7536 numberOfChannels : 2, 7537 format : media.AudioOutputFormat.AAC_ADTS, 7538 uri : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限。 7539 location : { latitude : 30, longitude : 130} 7540} 7541audioRecorder.on('error', (error: BusinessError) => { // 设置'error'事件回调。 7542 console.error(`audio error called, error: ${error}`); 7543}); 7544audioRecorder.prepare(audioRecorderConfig); // prepare不设置参数，触发'error'事件。 7545``` 7546 7547## AudioRecorderConfig<sup>(deprecated)</sup> 7548 7549> **说明：** 7550> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorderConfig](#avrecorderconfig9)替代。 7551 7552表示音频的录音配置。 7553 7554**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7555 7556| 名称 | 类型 | 必填 | 说明 | 7557| ----------------------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 7558| audioEncoder | [AudioEncoder](#audioencoderdeprecated) | 否 | 音频编码格式，默认设置为AAC_LC。<br/>**说明：** 从API version 8开始废弃，建议使用audioEncoderMime替代。 | 7559| audioEncodeBitRate | number | 否 | 音频编码比特率，默认值为48000。 | 7560| audioSampleRate | number | 否 | 音频采集采样率，默认值为48000。<br>可变比特率模式，码率仅作参考。 | 7561| numberOfChannels | number | 否 | 音频采集声道数，默认值为2。 | 7562| format | [AudioOutputFormat](#audiooutputformatdeprecated) | 否 | 音频输出封装格式，默认设置为MPEG_4。<br/>**说明：** 从API version 8开始废弃，建议使用fileFormat替代。 | 7563| location | [Location](#location) | 否 | 音频采集的地理位置。 | 7564| uri | string | 是 | 音频输出URI：fd://xx (fd number)<br/> <br/>文件需要由调用者创建，并赋予适当的权限。 | 7565| audioEncoderMime<sup>8+</sup> | [CodecMimeType](#codecmimetype8) | 否 | 容器编码格式。 | 7566| fileFormat<sup>8+</sup> | [ContainerFormatType](#containerformattype8) | 否 | 音频编码格式。 | 7567 7568## AudioEncoder<sup>(deprecated)</sup> 7569 7570> **说明：** 7571> 从API version 6开始支持，从API version 8开始废弃，建议使用[CodecMimeType](#codecmimetype8)替代。 7572 7573表示音频编码格式的枚举。 7574 7575**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7576 7577| 名称 | 值 | 说明 | 7578| ------- | ---- | ------------------------------------------------------------ | 7579| DEFAULT | 0 | 默认编码格式。<br/>仅做接口定义，暂不支持使用。 | 7580| AMR_NB | 1 | AMR-NB(Adaptive Multi Rate-Narrow Band Speech Codec) 编码格式。<br/>仅做接口定义，暂不支持使用。 | 7581| AMR_WB | 2 | AMR-WB(Adaptive Multi Rate-Wide Band Speech Codec) 编码格式。<br/>仅做接口定义，暂不支持使用。 | 7582| AAC_LC | 3 | AAC-LC（Advanced Audio Coding Low Complexity）编码格式。 | 7583| HE_AAC | 4 | HE_AAC（High-Efficiency Advanced Audio Coding）编码格式。<br/>仅做接口定义，暂不支持使用。 | 7584 7585## AudioOutputFormat<sup>(deprecated)</sup> 7586 7587> **说明：** 7588> 从API version 6开始支持，从API version 8 开始废弃，建议使用[ContainerFormatType](#containerformattype8)替代。 7589 7590表示音频封装格式的枚举。 7591 7592**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7593 7594| 名称 | 值 | 说明 | 7595| -------- | ---- | ------------------------------------------------------------ | 7596| DEFAULT | 0 | 默认封装格式。<br/>仅做接口定义，暂不支持使用。 | 7597| MPEG_4 | 2 | 封装为MPEG-4格式。 | 7598| AMR_NB | 3 | 封装为AMR_NB格式。<br/>仅做接口定义，暂不支持使用。 | 7599| AMR_WB | 4 | 封装为AMR_WB格式。<br/>仅做接口定义，暂不支持使用。 | 7600| AAC_ADTS | 6 | 封装为ADTS（Audio Data Transport Stream）格式，是AAC音频的传输流格式。 | 7601 7602 7603## media.createAVImageGenerator<sup>12+</sup> 7604 7605createAVImageGenerator(callback: AsyncCallback\<AVImageGenerator>): void 7606 7607创建AVImageGenerator实例，通过回调函数获取返回值。 7608 7609**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7610 7611**参数：** 7612 7613| 参数名 | 类型 | 必填 | 说明 | 7614| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 7615| callback | AsyncCallback\<[AVImageGenerator](#avimagegenerator12)> | 是 | 回调函数。异步返回AVImageGenerator实例，失败时返回null。可用于获取视频缩略图。 | 7616 7617**错误码：** 7618 7619以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7620 7621| 错误码ID | 错误信息 | 7622| -------- | ------------------------------ | 7623| 5400101 | No memory. Returned by callback. | 7624 7625**示例：** 7626 7627```ts 7628import { BusinessError } from '@kit.BasicServicesKit'; 7629 7630let avImageGenerator: media.AVImageGenerator; 7631media.createAVImageGenerator((error: BusinessError, generator: media.AVImageGenerator) => { 7632 if (generator != null) { 7633 avImageGenerator = generator; 7634 console.info('Succeeded in creating AVImageGenerator'); 7635 } else { 7636 console.error(`Failed to creat AVImageGenerator, error message:${error.message}`); 7637 } 7638}); 7639``` 7640 7641## media.createAVImageGenerator<sup>12+</sup> 7642 7643createAVImageGenerator(): Promise\<AVImageGenerator> 7644 7645创建AVImageGenerator对象，通过Promise获取返回值。 7646 7647**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7648 7649**返回值：** 7650 7651| 类型 | 说明 | 7652| ------------------------------- | ------------------------------------------------------------ | 7653| Promise\<[AVImageGenerator](#avimagegenerator12)> | Promise对象。异步返回AVImageGenerator实例，失败时返回null。可用于获取视频缩略图。 | 7654 7655**错误码：** 7656 7657以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7658 7659| 错误码ID | 错误信息 | 7660| -------- | ----------------------------- | 7661| 5400101 | No memory. Returned by promise. | 7662 7663**示例：** 7664 7665```ts 7666import { BusinessError } from '@kit.BasicServicesKit'; 7667 7668let avImageGenerator: media.AVImageGenerator; 7669media.createAVImageGenerator().then((generator: media.AVImageGenerator) => { 7670 if (generator != null) { 7671 avImageGenerator = generator; 7672 console.info('Succeeded in creating AVImageGenerator'); 7673 } else { 7674 console.error('Failed to creat AVImageGenerator'); 7675 } 7676}).catch((error: BusinessError) => { 7677 console.error(`Failed to creat AVImageGenerator, error message:${error.message}`); 7678}); 7679``` 7680 7681## AVImageGenerator<sup>12+</sup> 7682 7683视频缩略图获取类，用于从视频资源中获取缩略图。在调用AVImageGenerator的方法前，需要先通过[createAVImageGenerator()](#mediacreateavimagegenerator12)构建一个AVImageGenerator实例。 7684 7685获取视频缩略图的demo可参考：[获取视频缩略图开发指导](../../media/media/avimagegenerator.md)。 7686 7687### 属性 7688 7689**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7690 7691| 名称 | 类型 | 可读 | 可写 | 说明 | 7692| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 7693| 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。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频缩略图数据获取异常。 | 7694 7695### fetchFrameByTime<sup>12+</sup> 7696 7697fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams, callback: AsyncCallback\<image.PixelMap>): void 7698 7699异步方式获取视频缩略图。通过注册回调函数获取返回值。 7700 7701**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7702 7703**参数：** 7704 7705| 参数名 | 类型 | 必填 | 说明 | 7706| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7707| timeUs | number | 是 | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 | 7708| options | [AVImageQueryOptions](#avimagequeryoptions12) | 是 | 需要获取的缩略图时间点与视频帧的对应关系。 | 7709| param | [PixelMapParams](#pixelmapparams12) | 是 | 需要获取的缩略图的格式参数。 | 7710| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | 回调函数。获取缩略图成功时，err为undefined，data为PixelMap实例，否则为错误对象。 | 7711 7712**错误码：** 7713 7714以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7715 7716| 错误码ID | 错误信息 | 7717| -------- | ------------------------------------------ | 7718| 5400102 | Operation not allowed. Returned by callback. | 7719| 5400106 | Unsupported format. Returned by callback. | 7720 7721**示例：** 7722 7723```ts 7724import { BusinessError } from '@kit.BasicServicesKit'; 7725import { image } from '@kit.ImageKit'; 7726 7727let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7728let pixel_map : image.PixelMap | undefined = undefined; 7729 7730// 初始化入参。 7731let timeUs: number = 0 7732 7733let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC 7734 7735let param: media.PixelMapParams = { 7736 width : 300, 7737 height : 300, 7738} 7739 7740// 获取缩略图。 7741media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7742 if(generator != null){ 7743 avImageGenerator = generator; 7744 console.info(`Succeeded in creating AVImageGenerator`); 7745 avImageGenerator.fetchFrameByTime(timeUs, queryOption, param, (error: BusinessError, pixelMap) => { 7746 if (error) { 7747 console.error(`Failed to fetch FrameByTime, err = ${JSON.stringify(error)}`) 7748 return 7749 } 7750 pixel_map = pixelMap; 7751 }); 7752 } else { 7753 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7754 }; 7755}); 7756``` 7757 7758### fetchFrameByTime<sup>12+</sup> 7759 7760fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams): Promise<image.PixelMap> 7761 7762异步方式获取视频缩略图。通过Promise获取返回值。 7763 7764**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7765 7766**参数：** 7767 7768| 参数名 | 类型 | 必填 | 说明 | 7769| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7770| timeUs | number | 是 | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 | 7771| options | [AVImageQueryOptions](#avimagequeryoptions12) | 是 | 需要获取的缩略图时间点与视频帧的对应关系。 | 7772| param | [PixelMapParams](#pixelmapparams12) | 是 | 需要获取的缩略图的格式参数。 | 7773 7774**返回值：** 7775 7776| 类型 | 说明 | 7777| -------------- | ---------------------------------------- | 7778| Promise\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise对象，返回视频缩略图对象。 | 7779 7780**错误码：** 7781 7782以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7783 7784| 错误码ID | 错误信息 | 7785| -------- | ----------------------------------------- | 7786| 5400102 | Operation not allowed. Returned by promise. | 7787| 5400106 | Unsupported format. Returned by promise. | 7788 7789**示例：** 7790 7791```ts 7792import { BusinessError } from '@kit.BasicServicesKit'; 7793import { image } from '@kit.ImageKit'; 7794 7795let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7796let pixel_map : image.PixelMap | undefined = undefined; 7797 7798// 初始化入参。 7799let timeUs: number = 0 7800 7801let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC 7802 7803let param: media.PixelMapParams = { 7804 width : 300, 7805 height : 300, 7806} 7807 7808// 获取缩略图。 7809media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7810 if(generator != null){ 7811 avImageGenerator = generator; 7812 console.info(`Succeeded in creating AVImageGenerator`); 7813 avImageGenerator.fetchFrameByTime(timeUs, queryOption, param).then((pixelMap: image.PixelMap) => { 7814 pixel_map = pixelMap; 7815 }).catch((error: BusinessError) => { 7816 console.error(`Failed to fetch FrameByTime, error message:${error.message}`); 7817 }); 7818 } else { 7819 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7820 }; 7821}); 7822``` 7823 7824### release<sup>12+</sup> 7825 7826release(callback: AsyncCallback\<void>): void 7827 7828异步方式释放资源。通过注册回调函数获取返回值。 7829 7830**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7831 7832**参数：** 7833 7834| 参数名 | 类型 | 必填 | 说明 | 7835| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7836| callback | AsyncCallback\<void> | 是 | 回调函数。当释放资源成功，err为undefined，否则为错误对象。 | 7837 7838**错误码：** 7839 7840以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7841 7842| 错误码ID | 错误信息 | 7843| -------- | ------------------------------------------ | 7844| 5400102 | Operation not allowed. Returned by callback. | 7845 7846**示例：** 7847 7848```ts 7849import { BusinessError } from '@kit.BasicServicesKit'; 7850 7851let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7852 7853//释放资源。 7854media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7855 if(generator != null){ 7856 avImageGenerator = generator; 7857 console.info(`Succeeded in creating AVImageGenerator`); 7858 avImageGenerator.release((error: BusinessError) => { 7859 if (error) { 7860 console.error(`Failed to release, err = ${JSON.stringify(error)}`); 7861 return; 7862 } 7863 console.info(`Succeeded in releasing`); 7864 }); 7865 } else { 7866 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7867 }; 7868}); 7869``` 7870 7871### release<sup>12+</sup> 7872 7873release(): Promise\<void> 7874 7875异步方式释放资源。通过Promise获取返回值。 7876 7877**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7878 7879**返回值：** 7880 7881| 类型 | 说明 | 7882| -------------- | ---------------------------------------- | 7883| Promise\<void> | 异步方式释放资源release方法的Promise返回值。 | 7884 7885**错误码：** 7886 7887以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7888 7889| 错误码ID | 错误信息 | 7890| -------- | ----------------------------------------- | 7891| 5400102 | Operation not allowed. Returned by promise. | 7892 7893**示例：** 7894 7895```ts 7896import { BusinessError } from '@kit.BasicServicesKit'; 7897 7898let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7899 7900//释放资源 7901media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7902 if(generator != null){ 7903 avImageGenerator = generator; 7904 console.info(`Succeeded in creating AVImageGenerator`); 7905 avImageGenerator.release().then(() => { 7906 console.info(`Succeeded in releasing.`); 7907 }).catch((error: BusinessError) => { 7908 console.error(`Failed to release, error message:${error.message}`); 7909 }); 7910 } else { 7911 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7912 }; 7913}); 7914``` 7915 7916## AVImageQueryOptions<sup>12+</sup> 7917 7918需要获取的缩略图时间点与视频帧的对应关系。 7919 7920在获取视频缩略图时，传入的时间点与实际取得的视频帧所在时间点不一定相等，需要指定传入的时间点与实际取得的视频帧的时间关系。 7921 7922**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7923 7924| 名称 | 值 | 说明 | 7925| ------------------------ | --------------- | ------------------------------------------------------------ | 7926| AV_IMAGE_QUERY_NEXT_SYNC | 0 | 表示选取传入时间点或之后的关键帧。 | 7927| AV_IMAGE_QUERY_PREVIOUS_SYNC | 1 | 表示选取传入时间点或之前的关键帧。 | 7928| AV_IMAGE_QUERY_CLOSEST_SYNC | 2 | 表示选取离传入时间点最近的关键帧。 | 7929| AV_IMAGE_QUERY_CLOSEST | 3 | 表示选取离传入时间点最近的帧，该帧不一定是关键帧。 | 7930 7931## PixelMapParams<sup>12+</sup> 7932 7933获取视频缩略图时，输出缩略图的格式参数。 7934 7935**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7936 7937| 名称 | 类型 | 可读 | 可写 | 说明 | 7938|--------|--------|------|------|---------------------------------------------------------------------------------| 7939| width | number | 是 | 是 | 输出的缩略图宽度。应保证大于0且不大于原始视频宽度。否则返回的缩略图不会进行缩放。 | 7940| height | number | 是 | 是 | 输出的缩略图高度。应保证大于0且不大于原始视频高度。否则返回的缩略图不会进行缩放。 | 7941 7942## media.createMediaSourceWithUrl<sup>12+</sup> 7943 7944createMediaSourceWithUrl(url: string, headers?: Record\<string, string>): MediaSource 7945 7946创建流媒体预下载媒体来源实例方法。 7947 7948**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 7949 7950**系统能力：** SystemCapability.Multimedia.Media.Core 7951 7952**参数：** 7953 7954| 参数名 | 类型 | 必填 | 说明 | 7955| -------- | -------- | ---- | -------------------- | 7956| url | string | 是 | - 流媒体预下载媒体来源url，支持的流媒体格式：HLS、HTTP-FLV、Dash、Https。<br> - 本地m3u8的fd路径。 | 7957| headers | Record\<string, string> | 否 | 支持流媒体预下载HttpHeader自定义。 | 7958 7959**返回值：** 7960 7961| 类型 | 说明 | 7962| -------------- | ------------------------------------------ | 7963| [MediaSource](#mediasource12) | MediaSource返回值。 | 7964 7965**错误码：** 7966 7967以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7968 7969| 错误码ID | 错误信息 | 7970| -------- | ----------------------------------------- | 7971| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 7972| 5400101 | No memory. | 7973 7974**示例1：** 7975 7976```ts 7977let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 7978let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 7979``` 7980 7981**示例2：** 7982 7983<!--code_no_check--> 7984```ts 7985import { common } from '@kit.AbilityKit'; 7986import { resourceManager } from '@kit.LocalizationKit'; 7987 7988private context: Context | undefined; 7989constructor(context: Context) { 7990 this.context = context; // this.getUIContext().getHostContext(); 7991} 7992let mgr = this.context.resourceManager; 7993let fileDescriptor = await mgr.getRawFd("xxx.m3u8"); 7994 7995let fd:string = fileDescriptor.fd.toString(); 7996let offset:string = fileDescriptor.offset.toString(); 7997let length:string = fileDescriptor.length.toString(); 7998let fdUrl:string = "fd://" + fd + "?offset=" + offset + "&size=" + length; 7999 8000let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 8001let mediaSource : media.MediaSource = media.createMediaSourceWithUrl(fdUrl, headers); 8002 8003let mimeType : media.AVMimeTypes = media.AVMimeTypes.APPLICATION_M3U8; 8004mediaSource.setMimeType(mimeType); 8005 8006``` 8007 8008## MediaSource<sup>12+</sup> 8009 8010媒体数据信息。来源自[createMediaSourceWithUrl](#mediacreatemediasourcewithurl12)。 8011 8012**系统能力：** SystemCapability.Multimedia.Media.Core 8013 8014### setMimeType<sup>12+</sup> 8015 8016setMimeType(mimeType: AVMimeTypes): void 8017 8018设置媒体MIME类型，以帮助播放器处理扩展的媒体源。 8019 8020**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 8021 8022**系统能力：** SystemCapability.Multimedia.Media.Core 8023 8024**参数：** 8025 8026| 参数名 | 类型 | 必填 | 说明 | 8027| -------- | -------- | ---- | -------------------- | 8028| mimeType | [AVMimeTypes](#mediasource12) | 是 | 媒体MIME类型。 | 8029 8030### setMediaResourceLoaderDelegate<sup>18+</sup> 8031 8032setMediaResourceLoaderDelegate(resourceLoader: MediaSourceLoader): void 8033 8034设置MediaSourceLoader，帮助播放器请求媒体数据。 8035 8036**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8037 8038**系统能力：** SystemCapability.Multimedia.Media.Core 8039 8040**参数：** 8041 8042| 参数名 | 类型 | 必填 | 说明 | 8043| -------- | -------- | ---- | -------------------- | 8044| resourceLoader | [MediaSourceLoader](#mediasourceloader18) | 是 | 应用实现的媒体数据获取接口，方便播放器获取数据。 | 8045 8046**示例：** 8047 8048```ts 8049import { BusinessError } from '@kit.BasicServicesKit'; 8050 8051let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 8052let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 8053 8054// 应用按需实现。 8055let resourceLoader: media.MediaSourceLoader = { 8056 open: SourceOpenCallback, 8057 read: SourceReadCallback, 8058 close: SourceCloseCallback 8059}; 8060 8061mediaSource.setMediaResourceLoaderDelegate(resourceLoader); 8062``` 8063 8064## SourceOpenCallback<sup>18+</sup> 8065 8066type SourceOpenCallback = (request: MediaSourceLoadingRequest) => number 8067 8068由应用实现此回调函数，应用需处理传入的资源打开请求，并返回所打开资源对应的唯一句柄。 8069> 8070>**注意：** 客户端在处理完请求后应立刻返回。 8071> 8072 8073**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8074 8075**系统能力：** SystemCapability.Multimedia.Media.Core 8076 8077**参数：** 8078 8079| 参数名 | 类型 | 必填 | 说明 | 8080| -------- | -------- | ---- | -------------------- | 8081| request | [MediaSourceLoadingRequest](#mediasourceloadingrequest18) | 是 | 打开请求参数，包含请求资源的具体信息和数据推送方式。 | 8082 8083**返回值：** 8084 8085| 类型 | 说明 | 8086| -------- | -------------------- | 8087| number | 当前资源打开请求的句柄。大于0表示请求成功，小于或等于0表示请求失败。<br/> - request对象对应句柄唯一。| 8088 8089**示例：** 8090 8091```ts 8092import HashMap from '@ohos.util.HashMap'; 8093 8094let uuid: number = 1; 8095let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8096 8097let sourceOpenCallback: media.SourceOpenCallback = (request: media.MediaSourceLoadingRequest) => { 8098 console.log(`Opening resource: ${request.url}`); 8099 // 成功打开资源，返回唯一的句柄, 保证uuid和request对应。 8100 uuid += 1; 8101 requests.set(uuid, request); 8102 return uuid; 8103} 8104``` 8105 8106## SourceReadCallback<sup>18+</sup> 8107 8108type SourceReadCallback = (uuid: number, requestedOffset: number, requestedLength: number) => void 8109 8110由应用实现此回调函数，应用需记录读取请求，并在数据充足时通过对应的MediaSourceLoadingRequest对象的[respondData](#responddata18)方法推送数据。 8111> 8112>**注意：** 客户端在处理完请求后应立刻返回。 8113> 8114 8115**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8116 8117**系统能力：** SystemCapability.Multimedia.Media.Core 8118 8119**参数：** 8120 8121| 参数名 | 类型 | 必填 | 说明 | 8122| -------- | -------- | ---- | -------------------- | 8123| uuid | number | 是 | 资源句柄的标识。 | 8124| requestedOffset | number | 是 | 当前媒体数据相对于资源起始位置的偏移量。 | 8125| requestedLength | number | 是 | 当前请求的长度。值为-1时，表示到达资源末尾，此时推送完成后需通过[finishLoading](#finishloading18)方法通知播放器推送结束。 | 8126 8127**示例：** 8128 8129```ts 8130let sourceReadCallback: media.SourceReadCallback = (uuid: number, requestedOffset: number, requestedLength: number) => { 8131 console.log(`Reading resource with handle ${uuid}, offset: ${requestedOffset}, length: ${requestedLength}`); 8132 // 判断uuid是否合法、存储read请求，不要在read请求阻塞去推送数据和头信息。 8133} 8134``` 8135 8136## SourceCloseCallback<sup>18+</sup> 8137 8138type SourceCloseCallback = (uuid: number) => void 8139 8140由应用实现此回调函数，应用应释放相关资源。 8141> 8142>**注意：** 客户端在处理完请求后应立刻返回。 8143> 8144 8145**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8146 8147**系统能力：** SystemCapability.Multimedia.Media.Core 8148 8149**参数：** 8150 8151| 参数名 | 类型 | 必填 | 说明 | 8152| -------- | -------- | ---- | -------------------- | 8153| uuid | number | 是 | 资源句柄的标识。 | 8154 8155**示例：** 8156 8157```ts 8158import HashMap from '@ohos.util.HashMap'; 8159 8160let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8161 8162let sourceCloseCallback: media.SourceCloseCallback = (uuid: number) => { 8163 console.log(`Closing resource with handle ${uuid}`); 8164 // 清除当前uuid相关资源。 8165 requests.remove(uuid); 8166} 8167``` 8168 8169## MediaSourceLoader<sup>18+</sup> 8170 8171用于定义媒体数据加载器，需要应用程序对其进行实现。 8172 8173**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8174 8175**系统能力：** SystemCapability.Multimedia.Media.Core 8176 8177| 名称 | 类型 | 必填 | 说明 | 8178| -------- | -------- | ---- | -------------------- | 8179| open | [SourceOpenCallback](#sourceopencallback18) | 是 | 由应用程序实现的回调函数，用于处理资源打开请求。 | 8180| read | [SourceReadCallback](#sourcereadcallback18) | 是 | 由应用程序实现的回调函数，用于处理资源读取请求。 | 8181| close | [SourceCloseCallback](#sourceclosecallback18) | 是 | 由应用程序实现的回调函数，用于处理资源关闭请求。 | 8182 8183**示例：** 8184 8185```ts 8186import HashMap from '@ohos.util.HashMap'; 8187 8188let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 8189let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 8190let uuid: number = 1; 8191let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8192let mediaSourceLoader: media.MediaSourceLoader = { 8193 open: (request: media.MediaSourceLoadingRequest) => { 8194 console.log(`Opening resource: ${request.url}`); 8195 // 成功打开资源，返回唯一的句柄, 保证uuid和request对应。 8196 uuid += 1; 8197 requests.set(uuid, request); 8198 return uuid; 8199 }, 8200 read: (uuid: number, requestedOffset: number, requestedLength: number) => { 8201 console.log(`Reading resource with handle ${uuid}, offset: ${requestedOffset}, length: ${requestedLength}`); 8202 // 判断uuid是否合法、存储read请求，不要在read请求阻塞去推送数据和头信息。 8203 }, 8204 close: (uuid: number) => { 8205 console.log(`Closing resource with handle ${uuid}`); 8206 // 清除当前uuid相关资源。 8207 requests.remove(uuid); 8208 } 8209}; 8210 8211mediaSource.setMediaResourceLoaderDelegate(mediaSourceLoader); 8212let playStrategy : media.PlaybackStrategy = { 8213 preferredBufferDuration: 20, 8214}; 8215let player = await media.createAVPlayer(); 8216player.setMediaSource(mediaSource, playStrategy); 8217``` 8218 8219## MediaSourceLoadingRequest<sup>18+</sup> 8220 8221用于定义加载请求的对象。应用程序通过该对象来获取请求的资源位置，通过该对象和播放器进行数据交互。 8222 8223**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8224 8225### 属性 8226 8227**系统能力：** SystemCapability.Multimedia.Media.Core 8228 8229| 名称 | 类型 | 只读 | 可选 | 说明 | 8230| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 8231| url<sup>18+</sup> | string | 否 | 否 | 资源url，需要应用程序打开的资源路径。 | 8232| header<sup>18+</sup> | Record<string, string> | 否 | 是 | 网络请求标头，如果存在需要应用在下载数据是将头信息设置到http请求中。 | 8233 8234### respondData<sup>18+</sup> 8235 8236respondData(uuid: number, offset: number, buffer: ArrayBuffer): number 8237 8238用于应用程序向播放器发送数据。 8239 8240**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8241 8242**系统能力：** SystemCapability.Multimedia.Media.Core 8243 8244**参数：** 8245 8246| 参数名 | 类型 | 必填 | 说明 | 8247| -------- | -------- | ---- | -------------------- | 8248| uuid | number | 是 | 资源句柄的标识。 | 8249| offset | number | 是 | 当前媒体数据相对于资源起始位置的偏移量。 | 8250| buffer | ArrayBuffer | 是 | 响应播放器的媒体数据。<br/>**注意：** 不要传输无关数据，会影响正常数据解析和播放。 | 8251 8252**返回值：** 8253 8254| 类型 | 说明 | 8255| -------------- | ----------------------------------- | 8256| number | 当前服务端接受的字节数。<br>- 返回值小于0表示操作失败。<br>- 返回值为-2时，表示播放器不再需要当前数据，客户端应停止当前读取过程。<br>- 返回值为-3时，表示播放器的缓冲区已满，客户端应等待下一次读取。 | 8257 8258**示例：** 8259 8260```ts 8261let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8262let uuid = 1; 8263 8264let request = requests.get(uuid); 8265let num = request.respondData(uuid, offset, buf); 8266``` 8267 8268### respondHeader<sup>18+</sup> 8269 8270respondHeader(uuid: number, header?: Record<string, string>, redirectUrl?: string): void 8271 8272用于应用程序向播放器发送响应头信息，应在第一次调用[respondData](#responddata18)方法之前调用。 8273 8274**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8275 8276**系统能力：** SystemCapability.Multimedia.Media.Core 8277 8278**参数：** 8279 8280| 参数名 | 类型 | 必填 | 说明 | 8281| -------- | -------- | ---- | -------------------- | 8282| uuid | number | 是 | 资源句柄的标识。 | 8283| header | Record<string, string> | 否 | HTTP响应中的头部信息。应用可将头部信息字段与底层支持解析字段取交集传递或直接传入对应的所有头部信息。<br> - 底层播放需要解析的字段包括Transfer-Encoding、Location、Content-Type、Content-Range、Content-Encode、Accept-Ranges、content-length。 | 8284| redirectUrl | string | 否 | 如果存在，为HTTP响应中的重定向URL。 | 8285 8286**示例：** 8287 8288```ts 8289let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8290let uuid = 1; 8291 8292// 应用根据情况填充。 8293let header:Record<string, string> = { 8294 'Transfer-Encoding':'xxx', 8295 'Location' : 'xxx', 8296 'Content-Type' : 'xxx', 8297 'Content-Range' : 'xxx', 8298 'Content-Encode' : 'xxx', 8299 'Accept-Ranges' : 'xxx', 8300 'content-length' : 'xxx' 8301}; 8302let request = requests.get(uuid); 8303request.respondHeader(uuid, header); 8304``` 8305 8306### finishLoading<sup>18+</sup> 8307 8308finishLoading(uuid: number, state: LoadingRequestError): void 8309 8310应用程序用于通知播放器当前请求状态的接口。针对服务侧请求的单个资源，推送完全部资源后需要发送LOADING_ERROR_SUCCESS状态告知该资源推送结束。 8311 8312**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8313 8314**系统能力：** SystemCapability.Multimedia.Media.Core 8315 8316**参数：** 8317 8318| 参数名 | 类型 | 必填 | 说明 | 8319| -------- | -------- | ---- | -------------------- | 8320| uuid | number | 是 | 资源句柄的标识。 | 8321| state | [LoadingRequestError](#loadingrequesterror18) | 是 | 请求的状态。 | 8322 8323**示例：** 8324 8325```ts 8326let requests: HashMap<number, media.MediaSourceLoadingRequest> = new HashMap(); 8327let uuid = 1; 8328 8329let request = requests.get(uuid); 8330let loadingError = media.LoadingRequestError.LOADING_ERROR_SUCCESS; 8331request.finishLoading(uuid, loadingError); 8332``` 8333 8334## LoadingRequestError<sup>18+</sup> 8335 8336枚举，数据加载过程中状态变化的原因。 8337 8338**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 8339 8340**系统能力：** SystemCapability.Multimedia.Media.Core 8341 8342| 名称 | 值 | 说明 | 8343| -------------------- | ---- | ------------------------------ | 8344| LOADING_ERROR_SUCCESS | 0 | 由客户端返回，表示已经推送到资源末尾。 | 8345| LOADING_ERROR_NOT_READY | 1 | 由客户端返回，表示资源尚未准备好可供访问。| 8346| LOADING_ERROR_NO_RESOURCE | 2 | 由客户端返回，表示请求的资源URL不存在。 | 8347| LOADING_ERROR_INVAID_HANDLE | 3 | 由客户端返回，表示请求的资源句柄uuid无效。 | 8348| LOADING_ERROR_ACCESS_DENIED | 4 | 由客户端返回，表示客户端没有权限请求该资源。 | 8349| LOADING_ERROR_ACCESS_TIMEOUT | 5 | 由客户端返回，表示访问资源过程超时。 | 8350| LOADING_ERROR_AUTHORIZE_FAILED | 6 | 由客户端返回，表示授权失败。 | 8351 8352## AVMimeTypes<sup>12+</sup> 8353 8354媒体MIME类型，通过[setMimeType](#setmimetype12)设置。 8355 8356**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 8357 8358**系统能力：** SystemCapability.Multimedia.Media.Core 8359 8360 8361| 名称 | 值 | 说明 | 8362| ---------- | ---- | ------------------------------------------------------------ | 8363| APPLICATION_M3U8 | application/m3u8 | 表示m3u8本地文件。 | 8364 8365 8366## PlaybackStrategy<sup>12+</sup> 8367 8368播放策略。 8369 8370**系统能力：** SystemCapability.Multimedia.Media.Core 8371 8372| 名称 | 类型 | 必填 | 说明 | 8373| -------- | -------- | ---- | -------------------- | 8374| preferredWidth| number | 否 | 播放策略首选宽度，设置范围为大于0的整数，如1080，单位为像素（px）。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 8375| preferredHeight | number | 否 | 播放策略首选高度，设置范围为大于0的整数，如1920，单位为像素（px）。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 8376| preferredBufferDuration | number | 否 | 播放策略首选缓冲持续时间，单位s，取值范围1-20。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 8377| preferredHdr | boolean | 否 | 播放策略true是hdr，false非hdr，默认非hdr。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 8378| enableSuperResolution<sup>18+</sup> | boolean | 否 | 表示是否使能超分功能。true表示使能超分，false表示不使能超分，默认为false。<br>若不使能超分，则后续不能调用超分相关接口。若使能超分，则超分功能默认开启，默认目标分辨率为1920x1080，单位为像素。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 8379| showFirstFrameOnPrepare<sup>17+</sup> | boolean | 否 | 播放策略true是Prepare之后显示视频起播首帧，false是Prepare之后不显示视频起播首帧，默认不显示。<br>**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 | 8380| mutedMediaType | [MediaType](#mediatype8) | 否 | 静音播放的媒体类型，仅支持设置 MediaType.MEDIA_TYPE_AUD。 | 8381| preferredAudioLanguage<sup>13+</sup> | string | 否 | 播放策略首选音轨语言。dash场景下应用可按需设置。非dash场景暂不支持，建议缺省。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 8382| preferredSubtitleLanguage<sup>13+</sup> | string | 否 | 播放策略首选字幕语言。dash场景下应用可按需设置。非dash场景暂不支持，建议缺省。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 8383| preferredBufferDurationForPlaying<sup>18+</sup> | number | 否 | 播放策略首选起播缓冲水线。当起播缓冲时间超过该值，开始播放。单位s，取值范围0-20。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 8384| thresholdForAutoQuickPlay<sup>18+</sup> | number | 否 | 智能追帧水线，单位为s，取值应不小于2s，且需大于起播缓冲水线，默认设置为5s。<br>播放策略可以通过设置智能追帧水线来保证直播的实时性。flv直播场景下应用可按需设置，非flv直播场景暂不支持。网络状态的变化可能会导致播放器在某段时间内积压大量数据。播放器会定期检查当前播放时间与缓存中最新的帧时间戳之间的差值，当这个差值过大时，播放器将以1.2倍速开始追帧；当差值小于起播缓冲水线时，则停止追帧并恢复到正常播放速度。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 | 8385 8386## AVScreenCaptureRecordPreset<sup>12+</sup> 8387 8388进行屏幕录制时的编码、封装格式参数的枚举。 8389 8390**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8391 8392| 名称 | 值 | 说明 | 8393| --------------------------------- | ---- | -------------------------------------------- | 8394| SCREEN_RECORD_PRESET_H264_AAC_MP4 | 0 | 使用视频H264编码，音频AAC编码，MP4封装格式。 | 8395| SCREEN_RECORD_PRESET_H265_AAC_MP4 | 1 | 使用视频H265编码，音频AAC编码，MP4封装格式。 | 8396 8397## AVScreenCaptureStateCode<sup>12+</sup> 8398 8399屏幕录制的状态回调。 8400 8401**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8402 8403| 名称 | 值 | 说明 | 8404| ---------------------------------------- | ---- | ------------------------ | 8405| SCREENCAPTURE_STATE_STARTED | 0 | 录屏已开始。 | 8406| SCREENCAPTURE_STATE_CANCELED | 1 | 录屏被取消。 | 8407| SCREENCAPTURE_STATE_STOPPED_BY_USER | 2 | 录屏被用户手动停止。 | 8408| SCREENCAPTURE_STATE_INTERRUPTED_BY_OTHER | 3 | 录屏被其他录屏打断。 | 8409| SCREENCAPTURE_STATE_STOPPED_BY_CALL | 4 | 录屏被来电打断。 | 8410| SCREENCAPTURE_STATE_MIC_UNAVAILABLE | 5 | 录屏无法使用麦克风收音。 | 8411| SCREENCAPTURE_STATE_MIC_MUTED_BY_USER | 6 | 麦克风被用户关闭。 | 8412| SCREENCAPTURE_STATE_MIC_UNMUTED_BY_USER | 7 | 麦克风被用户打开。 | 8413| SCREENCAPTURE_STATE_ENTER_PRIVATE_SCENE | 8 | 录屏进入隐私页面。 | 8414| SCREENCAPTURE_STATE_EXIT_PRIVATE_SCENE | 9 | 录屏退出隐私页面。 | 8415| SCREENCAPTURE_STATE_STOPPED_BY_USER_SWITCHES | 10 | 系统用户切换，录屏中断。 | 8416 8417## AVScreenCaptureFillMode<sup>18+</sup> 8418 8419进行屏幕录制时视频填充模式的枚举。 8420 8421**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8422 8423| 名称 | 值 | 说明 | 8424| --------------------------------- | ---- | -------------------------------------------- | 8425| PRESERVE_ASPECT_RATIO | 0 | 保持与原始图像相同的宽高比例，即与物理屏幕宽高比例一致。 | 8426| SCALE_TO_FILL | 1 | 进行图像拉伸填充，适配设置的宽度和高度。 | 8427 8428 8429## AVScreenCaptureRecordConfig<sup>12+</sup> 8430 8431表示录屏参数配置。 8432 8433**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8434 8435| 名称 | 类型 | 必填 | 说明 | 8436| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 8437| fd | number | 是 | 录制输出的文件fd。 | 8438| frameWidth | number | 否 | 录屏的视频宽度，默认屏幕宽度，根据不同屏幕默认值不同，单位px。 | 8439| frameHeight | number | 否 | 录屏的视频高度，默认屏幕高度，根据不同屏幕默认值不同，单位px。 | 8440| videoBitrate | number | 否 | 录屏的视频比特率，默认10000000。 | 8441| audioSampleRate | number | 否 | 录屏的音频采样率，内录的系统音和外录的麦克风都是用此采样率，默认48000，仅支持设置48000或16000。 | 8442| audioChannelCount | number | 否 | 录屏的音频通道数，内录的系统音和外录的麦克风都是用此通道数，默认2声道，仅支持设置1或2声道。 | 8443| audioBitrate | number | 否 | 录屏的音频比特率，内录的系统音和外录的麦克风都是用此比特率，默认96000。 | 8444| preset | [AVScreenCaptureRecordPreset](#avscreencapturerecordpreset12) | 否 | 录屏使用的编码和封装格式，默认SCREEN_RECORD_PRESET_H264_AAC_MP4格式。 | 8445| displayId<sup>15+</sup> | number | 否 | 指定录屏使用的屏幕，默认主屏幕。 | 8446| fillMode<sup>18+</sup> | [AVScreenCaptureFillMode](#avscreencapturefillmode18)| 否 | 录屏时视频流的填充模式。 | 8447 8448## AVScreenCaptureRecorder<sup>12+</sup> 8449 8450屏幕录制管理类，用于进行屏幕录制。在调用AVScreenCaptureRecorder的方法前，需要先通过[createAVScreenCaptureRecorder()](#mediacreateavscreencapturerecorder12)创建一个AVScreenCaptureRecorder实例。 8451 8452### init<sup>12+</sup> 8453 8454init(config: AVScreenCaptureRecordConfig): Promise\<void> 8455 8456异步方式进行录屏初始化，设置录屏参数。通过Promise获取返回值。 8457 8458**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8459 8460**参数：** 8461 8462| 参数名 | 类型 | 必填 | 说明 | 8463| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 8464| config | [AVScreenCaptureRecordConfig](#avscreencapturerecordconfig12) | 是 | 配置屏幕录制的相关参数。 | 8465 8466**返回值：** 8467 8468| 类型 | 说明 | 8469| -------------- | ----------------------------------- | 8470| Promise\<void> | 异步录屏初始化方法的Promise返回值。 | 8471 8472**错误码：** 8473 8474| 错误码ID | 错误信息 | 8475| -------- | ---------------------------------------------- | 8476| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 8477| 5400103 | IO error. Return by promise. | 8478| 5400105 | Service died. Return by promise. | 8479 8480**示例：** 8481 8482```ts 8483import { BusinessError } from '@kit.BasicServicesKit'; 8484 8485let avCaptureConfig: media.AVScreenCaptureRecordConfig = { 8486 fd: 0, // 文件需要先有调用者创建，赋予写权限，将文件fd传给此参数。 8487 frameWidth: 640, 8488 frameHeight: 480 8489 // 补充其他参数。 8490} 8491 8492avScreenCaptureRecorder.init(avCaptureConfig).then(() => { 8493 console.info('Succeeded in initing avScreenCaptureRecorder'); 8494}).catch((err: BusinessError) => { 8495 console.info('Failed to init avScreenCaptureRecorder, error: ' + err.message); 8496}) 8497``` 8498 8499### startRecording<sup>12+</sup> 8500 8501startRecording(): Promise\<void> 8502 8503异步方式开始录屏。通过Promise获取返回值。 8504 8505**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8506 8507**返回值：** 8508 8509| 类型 | 说明 | 8510| -------------- | -------------------------------- | 8511| Promise\<void> | 异步开始录屏方法的Promise返回值. | 8512 8513**错误码：** 8514 8515| 错误码ID | 错误信息 | 8516| -------- | -------------------------------- | 8517| 5400103 | IO error. Return by promise. | 8518| 5400105 | Service died. Return by promise. | 8519 8520**示例：** 8521 8522```ts 8523import { BusinessError } from '@kit.BasicServicesKit'; 8524 8525avScreenCaptureRecorder.startRecording().then(() => { 8526 console.info('Succeeded in starting avScreenCaptureRecorder'); 8527}).catch((err: BusinessError) => { 8528 console.info('Failed to start avScreenCaptureRecorder, error: ' + err.message); 8529}) 8530``` 8531 8532### stopRecording<sup>12+</sup> 8533 8534stopRecording(): Promise\<void> 8535 8536异步方式结束录屏。通过Promise获取返回值。 8537 8538**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8539 8540**返回值：** 8541 8542| 类型 | 说明 | 8543| -------------- | --------------------------------- | 8544| Promise\<void> | 异步结束录屏方法的Promise返回值。 | 8545 8546**错误码：** 8547 8548| 错误码ID | 错误信息 | 8549| -------- | -------------------------------- | 8550| 5400103 | IO error. Return by promise. | 8551| 5400105 | Service died. Return by promise. | 8552 8553**示例：** 8554 8555```ts 8556import { BusinessError } from '@kit.BasicServicesKit'; 8557 8558avScreenCaptureRecorder.stopRecording().then(() => { 8559 console.info('Succeeded in stopping avScreenCaptureRecorder'); 8560}).catch((err: BusinessError) => { 8561 console.info('Failed to stop avScreenCaptureRecorder, error: ' + err.message); 8562}) 8563``` 8564 8565### skipPrivacyMode<sup>12+</sup> 8566 8567skipPrivacyMode(windowIDs: Array\<number>): Promise\<void> 8568 8569录屏时，应用可对本应用的隐私窗口做安全豁免。通过Promise获取返回值。 8570如录屏时，用户在本应用进行输入密码等操作，应用不会进行黑屏处理。 8571 8572**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8573 8574**参数：** 8575 8576| 参数名 | 类型 | 必填 | 说明 | 8577| ------ | ------- | ---- | --------------------------------------------------------- | 8578| windowIDs | Array\<number> | 是 | 需要豁免隐私的窗口列表，包括主窗口id和子窗口id，窗口属性获取方法可以参考[窗口API引用](../apis-arkui/js-apis-window.md#getwindowproperties9)。 | 8579 8580**返回值：** 8581 8582| 类型 | 说明 | 8583| -------------- | -------------------------------- | 8584| Promise\<void> | 豁免隐私窗口的Promise返回值. | 8585 8586**错误码：** 8587 8588| 错误码ID | 错误信息 | 8589| -------- | -------------------------------- | 8590| 5400103 | IO error. Return by promise. | 8591| 5400105 | Service died. Return by promise. | 8592 8593**示例：** 8594 8595```ts 8596import { BusinessError } from '@kit.BasicServicesKit'; 8597 8598let windowIDs = []; 8599avScreenCaptureRecorder.skipPrivacyMode(windowIDs).then(() => { 8600 console.info('Succeeded in skipping privacy mode'); 8601}).catch((err: BusinessError) => { 8602 console.info('Failed to skip privacy mode, error: ' + err.message); 8603}) 8604``` 8605 8606### setMicEnabled<sup>12+</sup> 8607 8608setMicEnabled(enable: boolean): Promise\<void> 8609 8610异步方式设置麦克风开关。通过Promise获取返回值。 8611 8612**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8613 8614**参数：** 8615 8616| 参数名 | 类型 | 必填 | 说明 | 8617| ------ | ------- | ---- | --------------------------------------------------------- | 8618| enable | boolean | 是 | 麦克风开关控制，true代表麦克风打开，false代表麦克风关闭。 | 8619 8620**返回值：** 8621 8622| 类型 | 说明 | 8623| -------------- | --------------------------------------- | 8624| Promise\<void> | 异步设置麦克风开关方法的Promise返回值。 | 8625 8626**错误码：** 8627 8628| 错误码ID | 错误信息 | 8629| -------- | -------------------------------- | 8630| 5400103 | IO error. Return by promise. | 8631| 5400105 | Service died. Return by promise. | 8632 8633**示例：** 8634 8635```ts 8636import { BusinessError } from '@kit.BasicServicesKit'; 8637 8638avScreenCaptureRecorder.setMicEnabled(true).then(() => { 8639 console.info('Succeeded in setMicEnabled avScreenCaptureRecorder'); 8640}).catch((err: BusinessError) => { 8641 console.info('Failed to setMicEnabled avScreenCaptureRecorder, error: ' + err.message); 8642}) 8643``` 8644 8645### release<sup>12+</sup> 8646 8647release(): Promise\<void> 8648 8649异步方式释放录屏。通过Promise获取返回值。 8650 8651**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8652 8653**返回值：** 8654 8655| 类型 | 说明 | 8656| -------------- | --------------------------------- | 8657| Promise\<void> | 异步释放录屏方法的Promise返回值。 | 8658 8659**错误码：** 8660 8661| 错误码ID | 错误信息 | 8662| -------- | -------------------------------- | 8663| 5400103 | IO error. Return by promise. | 8664| 5400105 | Service died. Return by promise. | 8665 8666**示例：** 8667 8668```ts 8669import { BusinessError } from '@kit.BasicServicesKit'; 8670 8671avScreenCaptureRecorder.release().then(() => { 8672 console.info('Succeeded in releasing avScreenCaptureRecorder'); 8673}).catch((err: BusinessError) => { 8674 console.info('Faile to release avScreenCaptureRecorder, error: ' + err.message); 8675}) 8676``` 8677 8678### on('stateChange')<sup>12+</sup> 8679 8680on(type: 'stateChange', callback: Callback\<AVScreenCaptureStateCode>): void 8681 8682订阅录屏状态切换的事件，当状态发生的时候，会通过订阅的回调通知用户。用户只能订阅一个状态切换的回调方法，重复订阅时，以最后一次订阅的回调接口为准。 8683 8684**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8685 8686**参数：** 8687 8688| 参数名 | 类型 | 必填 | 说明 | 8689| -------- | -------- | ---- | ------------------------------------------------------------ | 8690| type | string | 是 | 状态切换事件回调类型，支持的事件：'stateChange'。 | 8691| callback | function | 是 | 状态切换事件回调方法，[AVScreenCaptureStateCode](#avscreencapturestatecode12)表示切换到的状态。 | 8692 8693**示例：** 8694 8695```ts 8696avScreenCaptureRecorder.on('stateChange', (state: media.AVScreenCaptureStateCode) => { 8697 console.info('avScreenCaptureRecorder stateChange to ' + state); 8698}) 8699``` 8700 8701### on('error')<sup>12+</sup> 8702 8703on(type: 'error', callback: ErrorCallback): void 8704 8705订阅AVScreenCaptureRecorder的错误事件，用户可以根据应用自身逻辑对错误事件进行处理。用户只能订阅一个错误事件的回调方法，重复订阅时，以最后一次订阅的回调接口为准。 8706 8707**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8708 8709**参数：** 8710 8711| 参数名 | 类型 | 必填 | 说明 | 8712| -------- | ------------- | ---- | --------------------------------------- | 8713| type | string | 是 | 错误事件回调类型，支持的事件：'error'。 | 8714| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录屏错误事件回调方法。 | 8715 8716**错误码：** 8717 8718| 错误码ID | 错误信息 | 8719| -------- | -------------------------------- | 8720| 201 | permission denied. | 8721| 5400103 | IO error. Return by ErrorCallback. | 8722| 5400105 | Service died. Return by ErrorCallback. | 8723 8724**示例：** 8725 8726```ts 8727avScreenCaptureRecorder.on('error', (err: BusinessError) => { 8728 console.error('avScreenCaptureRecorder error:' + err.message); 8729}) 8730``` 8731 8732### off('stateChange')<sup>12+</sup> 8733 8734 off(type: 'stateChange', callback?: Callback\<AVScreenCaptureStateCode>): void 8735 8736取消订阅状态切换回调事件。用户可以指定填入状态切换的回调方法来取消订阅。 8737 8738**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8739 8740**参数：** 8741 8742| 参数名 | 类型 | 必填 | 说明 | 8743| -------- | -------- | ---- | ------------------------------------------------------------ | 8744| type | string | 是 | 状态切换事件回调类型，支持的事件：'stateChange'。 | 8745| callback | function | 否 | 状态切换事件回调方法，[AVScreenCaptureStateCode](#avscreencapturestatecode12)表示切换到的状态，不填此参数则会取消最后一次订阅事件。 | 8746 8747**示例：** 8748 8749```ts 8750avScreenCaptureRecorder.off('stateChange'); 8751``` 8752 8753### off('error')<sup>12+</sup> 8754 8755off(type: 'error', callback?: ErrorCallback): void 8756 8757取消订阅错误回调事件。用户可以指定填入错误回调方法来取消订阅。 8758 8759**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8760 8761**参数：** 8762 8763| 参数名 | 类型 | 必填 | 说明 | 8764| -------- | -------- | ---- | ---------------------------------------------------------- | 8765| type | string | 是 | 状态切换事件回调类型，支持的事件：'error'。 | 8766| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 录屏错误事件回调方法，不填此参数则会取消最后一次订阅事件。 | 8767 8768**示例：** 8769 8770```ts 8771avScreenCaptureRecorder.off('error'); 8772```
