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> - 可创建的音视频录制实例不能超过2个。 129> - 由于设备共用音频通路，一个设备仅能有一个实例进行音频录制。创建第二个实例录制音频时，将会因为音频通路冲突导致创建失败。 130 131**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 132 133**参数：** 134 135| 参数名 | 类型 | 必填 | 说明 | 136| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 137| callback | AsyncCallback\<[AVRecorder](#avrecorder9)> | 是 | 回调函数。异步返回AVRecorder实例，失败时返回null。可用于录制音视频媒体。 | 138 139**错误码：** 140 141以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 142 143| 错误码ID | 错误信息 | 144| -------- | ------------------------------ | 145| 5400101 | No memory. Return by callback. | 146 147**示例：** 148 149```ts 150import { BusinessError } from '@kit.BasicServicesKit'; 151let avRecorder: media.AVRecorder; 152 153media.createAVRecorder((error: BusinessError, recorder: media.AVRecorder) => { 154 if (recorder != null) { 155 avRecorder = recorder; 156 console.info('Succeeded in creating AVRecorder'); 157 } else { 158 console.error(`Failed to create AVRecorder, error message:${error.message}`); 159 } 160}); 161``` 162 163## media.createAVRecorder<sup>9+</sup> 164 165createAVRecorder(): Promise\<AVRecorder> 166 167异步方式创建音视频录制实例。通过Promise获取返回值。 168 169> **说明：** 170> 171> - 可创建的音视频录制实例不能超过2个。 172> - 由于设备共用音频通路，一个设备仅能有一个实例进行音频录制。创建第二个实例录制音频时，将会因为音频通路冲突导致创建失败。 173 174**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 175 176**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 177 178**返回值：** 179 180| 类型 | 说明 | 181| ------------------------------------ | ------------------------------------------------------------ | 182| Promise\<[AVRecorder](#avrecorder9)> | Promise对象。异步返回AVRecorder实例，失败时返回null。可用于录制音视频媒体。 | 183 184**错误码：** 185 186以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 187 188| 错误码ID | 错误信息 | 189| -------- | ----------------------------- | 190| 5400101 | No memory. Return by promise. | 191 192**示例：** 193 194```ts 195import { BusinessError } from '@kit.BasicServicesKit'; 196 197let avRecorder: media.AVRecorder; 198media.createAVRecorder().then((recorder: media.AVRecorder) => { 199 if (recorder != null) { 200 avRecorder = recorder; 201 console.info('Succeeded in creating AVRecorder'); 202 } else { 203 console.error('Failed to create AVRecorder'); 204 } 205}).catch((error: BusinessError) => { 206 console.error(`Failed to create AVRecorder, error message:${error.message}`); 207}); 208``` 209 210## media.createAVTranscoder<sup>12+</sup> 211 212createAVTranscoder(): Promise\<AVTranscoder> 213 214异步方式创建视频转码实例，通过Promise获取返回值。 215 216> **说明：** 217 218> 可创建的视频转码实例不能超过2个。 219 220**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 221 222**返回值：** 223 224| 类型 | 说明 | 225| ------------------------------- | ------------------------------------------------------------ | 226| Promise\<[AVTranscoder](#avtranscoder12)> | Promise对象。异步返回AVTranscoder实例，失败时返回null。可用于视频转码。 | 227 228**错误码：** 229 230以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 231 232| 错误码ID | 错误信息 | 233| -------- | ----------------------------- | 234| 5400101 | No memory. Return by promise. | 235 236**示例：** 237 238```ts 239import { BusinessError } from '@kit.BasicServicesKit'; 240 241let avTranscoder: media.AVTranscoder; 242media.createAVTranscoder().then((transcoder: media.AVTranscoder) => { 243 if (transcoder != null) { 244 avTranscoder = transcoder; 245 console.info('Succeeded in creating AVTranscoder'); 246 } else { 247 console.error('Failed to create AVTranscoder'); 248 } 249}).catch((error: BusinessError) => { 250 console.error(`Failed to create AVTranscoder, error message:${error.message}`); 251}); 252``` 253 254## media.createAVMetadataExtractor<sup>11+</sup> 255 256createAVMetadataExtractor(callback: AsyncCallback\<AVMetadataExtractor>): void 257 258异步方式创建AVMetadataExtractor实例，通过注册回调函数获取返回值。 259 260**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 261 262**参数：** 263 264| 参数名 | 类型 | 必填 | 说明 | 265| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 266| callback | AsyncCallback\<[AVMetadataExtractor](#avmetadataextractor11)> | 是 | 回调函数。当创建AVMetadataExtractor实例成功，err为undefined，data为获取到的AVMetadataExtractor实例，否则为错误对象。 | 267 268**错误码：** 269 270以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 271 272| 错误码ID | 错误信息 | 273| -------- | ------------------------------ | 274| 5400101 | No memory. Returned by callback. | 275 276**示例：** 277 278```ts 279import { BusinessError } from '@kit.BasicServicesKit'; 280 281let avMetadataExtractor: media.AVMetadataExtractor; 282media.createAVMetadataExtractor((error: BusinessError, extractor: media.AVMetadataExtractor) => { 283 if (extractor != null) { 284 avMetadataExtractor = extractor; 285 console.info('Succeeded in creating AVMetadataExtractor'); 286 } else { 287 console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`); 288 } 289}); 290``` 291 292## media.createAVMetadataExtractor<sup>11+</sup> 293 294createAVMetadataExtractor(): Promise\<AVMetadataExtractor> 295 296异步方式创建AVMetadataExtractor实例，通过Promise获取返回值。 297 298**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 299 300**错误码：** 301 302以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 303 304| 错误码ID | 错误信息 | 305| -------- | ------------------------------ | 306| 5400101 | No memory. Returned by promise. | 307 308**示例：** 309 310```ts 311import { BusinessError } from '@kit.BasicServicesKit'; 312 313let avMetadataExtractor: media.AVMetadataExtractor; 314media.createAVMetadataExtractor().then((extractor: media.AVMetadataExtractor) => { 315 if (extractor != null) { 316 avMetadataExtractor = extractor; 317 console.info('Succeeded in creating AVMetadataExtractor'); 318 } else { 319 console.error(`Failed to create AVMetadataExtractor`); 320 } 321}).catch((error: BusinessError) => { 322 console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`); 323}); 324``` 325 326## media.createSoundPool<sup>10+</sup> 327 328createSoundPool(maxStreams: number, audioRenderInfo: audio.AudioRendererInfo, callback: AsyncCallback\<SoundPool>): void 329 330创建音频池实例，使用callback方式异步获取返回值。 331 332**系统能力：** SystemCapability.Multimedia.Media.SoundPool 333 334**参数：** 335 336| 参数名 | 类型 | 必填 | 说明 | 337| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 338| maxStreams | number | 是 | soundPool实例的最大播放的流数 | 339| 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播放短音时为混音模式，不会打断其他音频播放。 | 340| callback | AsyncCallback<[SoundPool](js-apis-inner-multimedia-soundPool.md)> | 是 | 回调函数。异步返回SoundPool实例，失败时返回null。用于音频池实例的加载播放功能。 | 341 342**错误码：** 343 344以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 345 346| 错误码ID | 错误信息 | 347| -------- | ------------------------------ | 348| 5400101 | No memory. Return by callback. | 349 350**示例：** 351 352```js 353import { audio } from '@kit.AudioKit'; 354 355let soundPool: media.SoundPool; 356let audioRendererInfo: audio.AudioRendererInfo = { 357 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 358 rendererFlags : 0 359} 360 361media.createSoundPool(5, audioRendererInfo, (error, soundPool_: media.SoundPool) => { 362 if (error) { 363 console.error(`Failed to createSoundPool`) 364 return; 365 } else { 366 soundPool = soundPool_; 367 console.info(`Succeeded in createSoundPool`) 368 } 369}); 370``` 371 372## media.createSoundPool<sup>10+</sup> 373 374createSoundPool(maxStreams: number, audioRenderInfo: audio.AudioRendererInfo): Promise\<SoundPool> 375 376创建音频池实例，通过Promise获取返回值。 377 378**系统能力：** SystemCapability.Multimedia.Media.SoundPool 379 380**参数：** 381 382| 参数名 | 类型 | 必填 | 说明 | 383| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 384| maxStreams | number | 是 | soundPool实例的最大播放的流数 | 385| audioRenderInfo | [audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8) | 是 | 音频播放参数信息 | 386 387**返回值：** 388 389| 类型 | 说明 | 390| ----------------------------------------- | ------------------------------------------------------------ | 391| Promise<[SoundPool](js-apis-inner-multimedia-soundPool.md)> | Promise对象。异步返回SoundPool实例，失败时返回null。用于音频池实例的加载播放功能。 | 392 393**错误码：** 394 395以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 396 397| 错误码ID | 错误信息 | 398| -------- | ----------------------------- | 399| 5400101 | No memory. Return by promise. | 400 401**示例：** 402 403```js 404import { audio } from '@kit.AudioKit'; 405import { BusinessError } from '@kit.BasicServicesKit'; 406 407let soundPool: media.SoundPool; 408let audioRendererInfo: audio.AudioRendererInfo = { 409 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 410 rendererFlags : 0 411} 412 413media.createSoundPool(5, audioRendererInfo).then((soundpool_: media.SoundPool) => { 414 if (soundpool_ != null) { 415 soundPool = soundpool_; 416 console.info('Succceeded in creating SoundPool'); 417 } else { 418 console.error('Failed to create SoundPool'); 419 } 420}, (error: BusinessError) => { 421 console.error(`soundpool catchCallback, error message:${error.message}`); 422}); 423``` 424 425## media.createAVScreenCaptureRecorder<sup>12+</sup> 426 427createAVScreenCaptureRecorder(): Promise\<AVScreenCaptureRecorder> 428 429创建屏幕录制实例，通过Promise获取返回值。 430 431**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 432 433**返回值：** 434 435| 类型 | 说明 | 436| ------------------------------------------------------------ | ------------------------------------------------------------ | 437| Promise\<[AVScreenCaptureRecorder](#avscreencapturerecorder12)> | Promise对象。异步返回AVScreenCaptureRecorder实例，失败时返回null。可用于进行屏幕录制。 | 438 439**错误码：** 440 441| 错误码ID | 错误信息 | 442| -------- | ------------------------------ | 443| 5400101 | No memory. Return by promise. | 444 445**示例：** 446 447```ts 448import { BusinessError } from '@kit.BasicServicesKit'; 449 450let avScreenCaptureRecorder: media.AVScreenCaptureRecorder; 451media.createAVScreenCaptureRecorder().then((captureRecorder: media.AVScreenCaptureRecorder) => { 452 if (captureRecorder != null) { 453 avScreenCaptureRecorder = captureRecorder; 454 console.info('Succeeded in createAVScreenCaptureRecorder'); 455 } else { 456 console.error('Failed to createAVScreenCaptureRecorder'); 457 } 458}).catch((error: BusinessError) => { 459 console.error(`createAVScreenCaptureRecorder catchCallback, error message:${error.message}`); 460}); 461``` 462 463## AVErrorCode<sup>9+</sup> 464 465[媒体错误码](errorcode-media.md)类型枚举 466 467**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 468 469**系统能力：** SystemCapability.Multimedia.Media.Core 470 471| 名称 | 值 | 说明 | 472| :------------------------------------ | ------- | ------------------------------------ | 473| AVERR_OK | 0 | 表示操作成功。 | 474| AVERR_NO_PERMISSION | 201 | 表示无权限执行此操作。 | 475| AVERR_INVALID_PARAMETER | 401 | 表示传入入参无效。 | 476| AVERR_UNSUPPORT_CAPABILITY | 801 | 表示当前版本不支持该API能力。 | 477| AVERR_NO_MEMORY | 5400101 | 表示系统内存不足或服务数量达到上限。 | 478| AVERR_OPERATE_NOT_PERMIT | 5400102 | 表示当前状态不允许或无权执行此操作。 | 479| AVERR_IO | 5400103 | 表示数据流异常信息。 | 480| AVERR_TIMEOUT | 5400104 | 表示系统或网络响应超时。 | 481| AVERR_SERVICE_DIED | 5400105 | 表示服务进程死亡。 | 482| AVERR_UNSUPPORT_FORMAT | 5400106 | 表示不支持当前媒体资源的格式。 | 483| AVERR_AUDIO_INTERRUPTED<sup>11+</sup> | 5400107 | 表示音频焦点被抢占 | 484 485## MediaType<sup>8+</sup> 486 487媒体类型枚举。 488 489**系统能力：** SystemCapability.Multimedia.Media.Core 490 491| 名称 | 值 | 说明 | 492| -------------- | --------------------- | ------------------- | 493| MEDIA_TYPE_AUD | 0 | 表示音频。 <br> **原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 | 494| MEDIA_TYPE_VID | 1 | 表示视频。 <br> **原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 | 495| MEDIA_TYPE_SUBTITLE<sup>12+</sup> | 2 | 表示字幕。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 496 497## CodecMimeType<sup>8+</sup> 498 499Codec MIME类型枚举。 500 501**系统能力：** SystemCapability.Multimedia.Media.Core 502 503| 名称 | 值 | 说明 | 504| ------------ | --------------------- | ------------------------ | 505| VIDEO_H263 | 'video/h263' | 表示视频/h263类型。 | 506| VIDEO_AVC | 'video/avc' | 表示视频/avc类型。 | 507| VIDEO_MPEG2 | 'video/mpeg2' | 表示视频/mpeg2类型。 | 508| VIDEO_MPEG4 | 'video/mp4v-es' | 表示视频/mpeg4类型。 | 509| VIDEO_VP8 | 'video/x-vnd.on2.vp8' | 表示视频/vp8类型。 | 510| VIDEO_HEVC<sup>11+</sup> | 'video/hevc' | 表示视频/H265类型。| 511| AUDIO_AAC | 'audio/mp4a-latm' | 表示音频/mp4a-latm类型。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 512| AUDIO_VORBIS | 'audio/vorbis' | 表示音频/vorbis类型。 | 513| AUDIO_FLAC | 'audio/flac' | 表示音频/flac类型。 | 514| AUDIO_MP3<sup>12+</sup> | 'audio/mpeg' | 表示音频/mpeg类型。 | 515| AUDIO_G711MU<sup>12+</sup> | 'audio/g711mu' | 表示音频/G711-mulaw类型。 | 516 517## MediaDescriptionKey<sup>8+</sup> 518 519媒体信息描述枚举。 520 521**系统能力：** SystemCapability.Multimedia.Media.Core 522 523| 名称 | 值 | 说明 | 524| ------------------------ | --------------- | ------------------------------------------------------------ | 525| MD_KEY_TRACK_INDEX | 'track_index' | 表示轨道序号，其对应键值类型为number。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 526| MD_KEY_TRACK_TYPE | 'track_type' | 表示轨道类型，其对应键值类型为number，参考[MediaType](#mediatype8)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 527| MD_KEY_CODEC_MIME | 'codec_mime' | 表示codec_mime类型，其对应键值类型为string。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 528| MD_KEY_DURATION | 'duration' | 表示媒体时长，其对应键值类型为number，单位为毫秒（ms）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 529| MD_KEY_BITRATE | 'bitrate' | 表示比特率，其对应键值类型为number，单位为比特率（bps）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 530| MD_KEY_WIDTH | 'width' | 表示视频宽度，其对应键值类型为number，单位为像素（px）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 531| MD_KEY_HEIGHT | 'height' | 表示视频高度，其对应键值类型为number，单位为像素（px）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 532| MD_KEY_FRAME_RATE | 'frame_rate' | 表示视频帧率，其对应键值类型为number，单位为每100秒的帧数。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 533| MD_KEY_AUD_CHANNEL_COUNT | 'channel_count' | 表示声道数，其对应键值类型为number。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 534| MD_KEY_AUD_SAMPLE_RATE | 'sample_rate' | 表示采样率，其对应键值类型为number，单位为赫兹（Hz）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 535| MD_KEY_AUD_SAMPLE_DEPTH<sup>12+</sup> | 'sample_depth' | 表示位深，其对应键值类型为number，单位为位（bit）。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 536| MD_KEY_TRACK_NAME<sup>12+</sup> | 'track_name' | 表示track名称，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 537| MD_KEY_HDR_TYPE<sup>12+</sup> | 'hdr_type' | 表示视频轨类型，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 538 539## PlaybackInfoKey<sup>12+</sup> 540 541播放信息描述枚举。 542 543**系统能力：** SystemCapability.Multimedia.Media.Core 544 545| 名称 | 值 | 说明 | 546| ------------------------ | --------------- | ------------------------------------------------------------ | 547| SERVER_IP_ADDRESS | 'server_ip_address' | 表示服务器IP地址，其对应键值类型为string。 | 548| AVG_DOWNLOAD_RATE | 'average_download_rate'| 表示平均下载速率，其对应键值类型为number，单位为比特率（bps）。 | 549| DOWNLOAD_RATE | 'download_rate' | 表示1s的下载速率，其对应键值类型为number，单位为比特率（bps）。| 550| IS_DOWNLOADING | 'is_downloading' | 表示下载状态，1表示在下载状态，0表示非下载状态（下载完成），其对应键值类型为number。| 551| BUFFER_DURATION | 'buffer_duration' | 表示缓存数据的可播放时长，其对应键值类型为number，单位为秒（s）。| 552 553## BufferingInfoType<sup>8+</sup> 554 555缓存事件类型枚举。 556 557**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 558 559**系统能力：** SystemCapability.Multimedia.Media.Core 560 561| 名称 | 值 | 说明 | 562| ----------------- | ---- | -------------------------------- | 563| BUFFERING_START | 1 | 表示开始缓存。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 564| BUFFERING_END | 2 | 表示结束缓存。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 565| BUFFERING_PERCENT | 3 | 表示缓存百分比。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 566| CACHED_DURATION | 4 | 表示缓存时长，单位为毫秒（ms）。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 567 568## StateChangeReason<sup>9+</sup> 569 570表示播放或录制实例状态机切换原因的枚举，伴随state一起上报。 571 572**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 573 574**系统能力：** SystemCapability.Multimedia.Media.Core 575 576| 名称 | 值 | 说明 | 577| ---------- | ---- | ------------------------------------------------------------ | 578| USER | 1 | 表示用户行为造成的状态切换，由用户或客户端主动调用接口产生。 | 579| BACKGROUND | 2 | 表示后台系统行为造成的状态切换，比如应用未注册播控中心权限，退到后台时被系统强制暂停或停止。 | 580 581## AVPlayer<sup>9+</sup> 582 583播放管理类，用于管理和播放媒体资源。在调用AVPlayer的方法前，需要先通过[createAVPlayer()](#mediacreateavplayer9)构建一个AVPlayer实例。 584 585Audio/Video播放demo可参考：[音频播放开发指导](../../media/media/using-avplayer-for-playback.md)、[视频播放开发指导](../../media/media/video-playback.md)。 586 587> **说明：** 588> 589> 在使用AVPlayer实例的方法时，建议开发者注册相关回调，主动获取当前状态变化。 590> - [on('stateChange')](#onstatechange9)：监听播放状态机AVPlayerState切换。 591> - [on('error')](#onerror9)：监听错误事件。 592 593### 属性 594 595**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 596 597| 名称 | 类型 | 只读 | 可选 | 说明 | 598| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 599| 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开始，该接口支持在原子化服务中使用。 | 600| 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开始，该接口支持在原子化服务中使用。 | 601| 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开始，该接口支持在原子化服务中使用。 | 602| 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开始，该接口支持在原子化服务中使用。 | 603| loop<sup>9+</sup> | boolean | 否 | 否 | 视频循环播放属性，默认'false'，设置为'true'表示循环播放，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。<br/>直播场景不支持loop设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 604| videoScaleType<sup>9+</sup> | [VideoScaleType](#videoscaletype9) | 否 | 是 | 视频缩放模式，默认VIDEO_SCALE_TYPE_FIT，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 605| 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开始，该接口支持在原子化服务中使用。| 606| 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开始，该接口支持在原子化服务中使用。| 607| 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开始，该接口支持在原子化服务中使用。| 608| state<sup>9+</sup> | [AVPlayerState](#avplayerstate9) | 是 | 否 | 音视频播放的状态，全状态有效，可查询参数。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 609| currentTime<sup>9+</sup> | number | 是 | 否 | 视频的当前播放位置，单位为毫秒（ms），可查询参数。<br/>返回为(-1)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 610| duration<sup>9+</sup> | number | 是 | 否 | 视频时长，单位为毫秒（ms），可查询参数。<br/>返回为(-1)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 611| width<sup>9+</sup> | number | 是 | 否 | 视频宽，单位为像素（px），可查询参数。<br/>返回为(0)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 612| height<sup>9+</sup> | number | 是 | 否 | 视频高，单位为像素（px），可查询参数。<br/>返回为(0)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 613 614### on('stateChange')<sup>9+</sup> 615 616on(type: 'stateChange', callback: OnAVPlayerStateChangeHandle): void 617 618监听播放状态机AVPlayerState切换的事件。 619 620**原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 621 622**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 623 624**参数：** 625 626| 参数名 | 类型 | 必填 | 说明 | 627| -------- | -------- | ---- | ------------------------------------------------------------ | 628| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 629| callback | [OnAVPlayerStateChangeHandle](#onavplayerstatechangehandle12) | 是 | 状态机切换事件回调方法。 | 630 631**示例：** 632 633```ts 634avPlayer.on('stateChange', async (state: string, reason: media.StateChangeReason) => { 635 switch (state) { 636 case 'idle': 637 console.info('state idle called'); 638 break; 639 case 'initialized': 640 console.info('initialized prepared called'); 641 break; 642 case 'prepared': 643 console.info('state prepared called'); 644 break; 645 case 'playing': 646 console.info('state playing called'); 647 break; 648 case 'paused': 649 console.info('state paused called'); 650 break; 651 case 'completed': 652 console.info('state completed called'); 653 break; 654 case 'stopped': 655 console.info('state stopped called'); 656 break; 657 case 'released': 658 console.info('state released called'); 659 break; 660 case 'error': 661 console.info('state error called'); 662 break; 663 default: 664 console.info('unknown state :' + state); 665 break; 666 } 667}) 668``` 669 670### off('stateChange')<sup>9+</sup> 671 672off(type: 'stateChange', callback?: OnAVPlayerStateChangeHandle): void 673 674取消监听播放状态机[AVPlayerState](#avplayerstate9)切换的事件。 675 676**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 677 678**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 679 680**参数：** 681 682| 参数名 | 类型 | 必填 | 说明 | 683| ------ | ------ | ---- | ----------------------------------------------------- | 684| type | string | 是 | 状态机切换事件回调类型，取消注册的事件：'stateChange' | 685| callback | [OnAVPlayerStateChangeHandle](#onavplayerstatechangehandle12) | 否 | 状态机切换事件回调方法。<br/>从API version 12开始支持此参数。 | 686 687**示例：** 688 689```ts 690avPlayer.off('stateChange') 691``` 692 693### on('error')<sup>9+</sup> 694 695on(type: 'error', callback: ErrorCallback): void 696 697监听[AVPlayer](#avplayer9)的错误事件，该事件仅用于错误提示，不需要用户停止播控动作。如果此时[AVPlayerState](#avplayerstate9)也切至error状态，用户需要通过[reset()](#reset9)或者[release()](#release9)退出播放操作。 698 699**原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 700 701**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 702 703**参数：** 704 705| 参数名 | 类型 | 必填 | 说明 | 706| -------- | -------- | ---- | ------------------------------------------------------------ | 707| type | string | 是 | 错误事件回调类型，支持的事件：'error'，用户操作和系统都会触发此事件。 | 708| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 错误事件回调方法，使用播放器的过程中发生错误，会提供错误码ID和错误信息。 | 709 710**错误码：** 711 712以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 713 714| 错误码ID | 错误信息 | 715| -------- | --------------------- | 716| 201 | Permission denied | 717| 401 | The parameter check failed. | 718| 801 | Capability not supported. | 719| 5400101 | No memory. | 720| 5400102 | Operation not allowed.| 721| 5400103 | I/O error | 722| 5400104 | Time out | 723| 5400105 | Service died. | 724| 5400106 | Unsupported format. | 725 726**示例：** 727 728```ts 729import { BusinessError } from '@kit.BasicServicesKit'; 730 731avPlayer.on('error', (error: BusinessError) => { 732 console.info('error happened,and error message is :' + error.message) 733 console.info('error happened,and error code is :' + error.code) 734}) 735``` 736 737### off('error')<sup>9+</sup> 738 739off(type: 'error', callback?: ErrorCallback): void 740 741取消监听播放的错误事件。 742 743**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 744 745**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 746 747**参数：** 748 749| 参数名 | 类型 | 必填 | 说明 | 750| ------ | ------ | ---- | ----------------------------------------- | 751| type | string | 是 | 错误事件回调类型，取消注册的事件：'error' | 752| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 错误事件回调方法，使用播放器的过程中发生错误，会提供错误码ID和错误信息。<br/>从API version 12开始支持此参数。 | 753 754**示例：** 755 756```ts 757avPlayer.off('error') 758``` 759 760### setMediaSource<sup>12+</sup> 761 762setMediaSource(src:MediaSource, strategy?: PlaybackStrategy): Promise\<void> 763 764流媒体预下载资源设置，下载url对应的流媒体数据，并暂存在内存中。[视频播放开发指导](../../media/media/video-playback.md)。通过Promise获取返回值。 765 766**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 767 768**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 769 770**参数：** 771 772| 参数名 | 类型 | 必填 | 说明 | 773| -------- | -------- | ---- | -------------------- | 774| src | [MediaSource](#mediasource12) | 是 | 流媒体预下载媒体来源。 | 775| strategy | [PlaybackStrategy](#playbackstrategy12) | 否 | 流媒体预下载播放策略。 | 776 777**返回值：** 778 779| 类型 | 说明 | 780| -------------- | ------------------------------------------ | 781| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 782 783**错误码：** 784 785以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 786 787| 错误码ID | 错误信息 | 788| -------- | ----------------------------------------- | 789| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 790| 5400102 | Operation not allowed. Return by promise. | 791 792**示例：** 793 794```ts 795import { media } from '@kit.MediaKit'; 796 797let player = await media.createAVPlayer(); 798let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 799let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 800let playStrategy : media.PlaybackStrategy = {preferredWidth: 1, preferredHeight: 2, preferredBufferDuration: 3, preferredHdr: false}; 801player.setMediaSource(mediaSource, playStrategy); 802``` 803 804### setPlaybackStrategy<sup>12+</sup> 805 806setPlaybackStrategy(strategy: PlaybackStrategy): Promise\<void> 807 808设置播放策略，只能在initialized状态下调用。 809 810**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 811 812**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 813 814**参数：** 815 816| 参数名 | 类型 | 必填 | 说明 | 817| -------- | -------- | ---- | -------------------- | 818| strategy | [PlaybackStrategy](#playbackstrategy12) | 是 | 播放策略。 | 819 820**返回值：** 821 822| 类型 | 说明 | 823| -------------- | ------------------------------------ | 824| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 825 826**错误码：** 827 828以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 829 830| 错误码ID | 错误信息 | 831| -------- | ----------------------------------------- | 832| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. | 833| 5400102 | Operation not allowed. Return by promise. | 834 835**示例：** 836 837```ts 838import { media } from '@kit.MediaKit'; 839import { common } from '@kit.AbilityKit'; 840 841let player = await media.createAVPlayer(); 842let context = getContext(this) as common.UIAbilityContext 843let fileDescriptor = await context.resourceManager.getRawFd('xxx.mp4') 844player.fdSrc = fileDescriptor 845let playStrategy : media.PlaybackStrategy = {preferredWidth: 1, preferredHeight: 2, preferredBufferDuration: 3, 846 preferredHdr: false, mutedMediaType: media.MediaType.MEDIA_TYPE_AUD}; 847player.setPlaybackStrategy(playStrategy); 848``` 849 850### prepare<sup>9+</sup> 851 852prepare(callback: AsyncCallback\<void>): void 853 854准备播放音频/视频，需在[stateChange](#onstatechange9)事件成功触发至initialized状态后，才能调用。使用callback方式异步获取返回值。 855 856**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 857 858**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 859 860**参数：** 861 862| 参数名 | 类型 | 必填 | 说明 | 863| -------- | -------- | ---- | -------------------- | 864| callback | AsyncCallback\<void> | 是 | 准备播放的回调方法。 | 865 866**错误码：** 867 868以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 869 870| 错误码ID | 错误信息 | 871| -------- | ------------------------------------------ | 872| 5400102 | Operation not allowed. Return by callback. | 873| 5400106 | Unsupported format. Return by callback. | 874 875**示例：** 876 877```ts 878import { BusinessError } from '@kit.BasicServicesKit'; 879 880avPlayer.prepare((err: BusinessError) => { 881 if (err) { 882 console.error('Failed to prepare,error message is :' + err.message) 883 } else { 884 console.info('Succeeded in preparing'); 885 } 886}) 887``` 888 889### prepare<sup>9+</sup> 890 891prepare(): Promise\<void> 892 893准备播放音频/视频，需在[stateChange](#onstatechange9)事件成功触发至initialized状态后，才能调用。通过Promise获取返回值。 894 895**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 896 897**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 898 899**返回值：** 900 901| 类型 | 说明 | 902| -------------- | ------------------------- | 903| Promise\<void> | 准备播放的Promise返回值。 | 904 905**错误码：** 906 907以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 908 909| 错误码ID | 错误信息 | 910| -------- | ----------------------------------------- | 911| 5400102 | Operation not allowed. Return by promise. | 912| 5400106 | Unsupported format. Return by promise. | 913 914**示例：** 915 916```ts 917import { BusinessError } from '@kit.BasicServicesKit'; 918 919avPlayer.prepare().then(() => { 920 console.info('Succeeded in preparing'); 921}, (err: BusinessError) => { 922 console.error('Failed to prepare,error message is :' + err.message) 923}) 924``` 925 926### setMediaMuted<sup>12+</sup> 927 928setMediaMuted(mediaType: MediaType, muted: boolean ): Promise\<void> 929 930设置音频静音/取消音频静音。只能在prepared/playing/paused/completed状态下调用。仅支持设置mediaType为音频格式。 931 932**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 933 934**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 935 936**参数：** 937 938| 参数名 | 类型 | 必填 | 说明 | 939| -------- | -------- | ---- | -------------------- | 940| mediaType | [MediaType](#mediatype8) | 是 | 播放策略。 | 941| muted | boolean | 是 | 是否静音播放。 | 942 943**返回值：** 944 945| 类型 | 说明 | 946| -------------- | ------------------------- | 947| Promise\<void> | 准备播放的Promise返回值。 | 948 949**错误码：** 950 951以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 952 953| 错误码ID | 错误信息 | 954| -------- | ----------------------------------------- | 955| 401 | The parameter check failed. Return by promise. | 956| 5400102 | Operation not allowed. Return by promise. | 957 958**示例：** 959 960```ts 961import { BusinessError } from '@kit.BasicServicesKit'; 962 963avPlayer.prepare().then(() => { 964 console.info('Succeeded in preparing'); 965 avPlayer.setMediaMuted(media.MediaType.MEDIA_TYPE_AUD, true) 966}, (err: BusinessError) => { 967 console.error('Failed to prepare,error message is :' + err.message) 968}) 969``` 970 971### play<sup>9+</sup> 972 973play(callback: AsyncCallback\<void>): void 974 975开始播放音视频资源，只能在prepared/paused/completed状态调用。使用callback方式异步获取返回值。 976 977**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 978 979**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 980 981**参数：** 982 983| 参数名 | 类型 | 必填 | 说明 | 984| -------- | -------- | ---- | -------------------- | 985| callback | AsyncCallback\<void> | 是 | 开始播放的回调方法。 | 986 987**错误码：** 988 989以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 990 991| 错误码ID | 错误信息 | 992| -------- | ------------------------------------------ | 993| 5400102 | Operation not allowed. Return by callback. | 994 995**示例：** 996 997```ts 998import { BusinessError } from '@kit.BasicServicesKit'; 999 1000avPlayer.play((err: BusinessError) => { 1001 if (err) { 1002 console.error('Failed to play,error message is :' + err.message) 1003 } else { 1004 console.info('Succeeded in playing'); 1005 } 1006}) 1007``` 1008 1009### play<sup>9+</sup> 1010 1011play(): Promise\<void> 1012 1013开始播放音视频资源，只能在prepared/paused/completed状态调用。通过Promise获取返回值。 1014 1015**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1016 1017**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1018 1019**返回值：** 1020 1021| 类型 | 说明 | 1022| -------------- | ------------------------- | 1023| Promise\<void> | 开始播放的Promise返回值。 | 1024 1025**错误码：** 1026 1027以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1028 1029| 错误码ID | 错误信息 | 1030| -------- | ----------------------------------------- | 1031| 5400102 | Operation not allowed. Return by promise. | 1032 1033**示例：** 1034 1035```ts 1036import { BusinessError } from '@kit.BasicServicesKit'; 1037 1038avPlayer.play().then(() => { 1039 console.info('Succeeded in playing'); 1040}, (err: BusinessError) => { 1041 console.error('Failed to play,error message is :' + err.message) 1042}) 1043``` 1044 1045### pause<sup>9+</sup> 1046 1047pause(callback: AsyncCallback\<void>): void 1048 1049暂停播放音视频资源，只能在playing状态调用。使用callback方式异步获取返回值。 1050 1051**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1052 1053**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1054 1055**参数：** 1056 1057| 参数名 | 类型 | 必填 | 说明 | 1058| -------- | -------- | ---- | -------------------- | 1059| callback | AsyncCallback\<void> | 是 | 暂停播放的回调方法。 | 1060 1061**错误码：** 1062 1063以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1064 1065| 错误码ID | 错误信息 | 1066| -------- | ------------------------------------------ | 1067| 5400102 | Operation not allowed. Return by callback. | 1068 1069**示例：** 1070 1071```ts 1072import { BusinessError } from '@kit.BasicServicesKit'; 1073 1074avPlayer.pause((err: BusinessError) => { 1075 if (err) { 1076 console.error('Failed to pause,error message is :' + err.message) 1077 } else { 1078 console.info('Succeeded in pausing'); 1079 } 1080}) 1081``` 1082 1083### pause<sup>9+</sup> 1084 1085pause(): Promise\<void> 1086 1087暂停播放音视频资源，只能在playing状态调用。通过Promise获取返回值。 1088 1089**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1090 1091**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1092 1093**返回值：** 1094 1095| 类型 | 说明 | 1096| -------------- | ------------------------- | 1097| Promise\<void> | 暂停播放的Promise返回值。 | 1098 1099**错误码：** 1100 1101以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1102 1103| 错误码ID | 错误信息 | 1104| -------- | ----------------------------------------- | 1105| 5400102 | Operation not allowed. Return by promise. | 1106 1107**示例：** 1108 1109```ts 1110import { BusinessError } from '@kit.BasicServicesKit'; 1111 1112avPlayer.pause().then(() => { 1113 console.info('Succeeded in pausing'); 1114}, (err: BusinessError) => { 1115 console.error('Failed to pause,error message is :' + err.message) 1116}) 1117``` 1118 1119### stop<sup>9+</sup> 1120 1121stop(callback: AsyncCallback\<void>): void 1122 1123停止播放音视频资源，只能在prepared/playing/paused/completed状态调用。使用callback方式异步获取返回值。 1124 1125**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1126 1127**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1128 1129**参数：** 1130 1131| 参数名 | 类型 | 必填 | 说明 | 1132| -------- | -------- | ---- | -------------------- | 1133| callback | AsyncCallback\<void> | 是 | 停止播放的回调方法。 | 1134 1135**错误码：** 1136 1137以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1138 1139| 错误码ID | 错误信息 | 1140| -------- | ------------------------------------------ | 1141| 5400102 | Operation not allowed. Return by callback. | 1142 1143**示例：** 1144 1145```ts 1146import { BusinessError } from '@kit.BasicServicesKit'; 1147 1148avPlayer.stop((err: BusinessError) => { 1149 if (err) { 1150 console.error('Failed to stop,error message is :' + err.message) 1151 } else { 1152 console.info('Succeeded in stopping'); 1153 } 1154}) 1155``` 1156 1157### stop<sup>9+</sup> 1158 1159stop(): Promise\<void> 1160 1161停止播放音视频资源，只能在prepared/playing/paused/completed状态调用。通过Promise获取返回值。 1162 1163**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1164 1165**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1166 1167**返回值：** 1168 1169| 类型 | 说明 | 1170| -------------- | ------------------------- | 1171| Promise\<void> | 停止播放的Promise返回值。 | 1172 1173**错误码：** 1174 1175以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1176 1177| 错误码ID | 错误信息 | 1178| -------- | ----------------------------------------- | 1179| 5400102 | Operation not allowed. Return by promise. | 1180 1181**示例：** 1182 1183```ts 1184import { BusinessError } from '@kit.BasicServicesKit'; 1185 1186avPlayer.stop().then(() => { 1187 console.info('Succeeded in stopping'); 1188}, (err: BusinessError) => { 1189 console.error('Failed to stop,error message is :' + err.message) 1190}) 1191``` 1192 1193### reset<sup>9+</sup> 1194 1195reset(callback: AsyncCallback\<void>): void 1196 1197重置播放，只能在initialized/prepared/playing/paused/completed/stopped/error状态调用。使用callback方式异步获取返回值。 1198 1199**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1200 1201**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1202 1203**参数：** 1204 1205| 参数名 | 类型 | 必填 | 说明 | 1206| -------- | -------- | ---- | -------------------- | 1207| callback | AsyncCallback\<void> | 是 | 重置播放的回调方法。 | 1208 1209**错误码：** 1210 1211以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1212 1213| 错误码ID | 错误信息 | 1214| -------- | ------------------------------------------ | 1215| 5400102 | Operation not allowed. Return by callback. | 1216 1217**示例：** 1218 1219```ts 1220import { BusinessError } from '@kit.BasicServicesKit'; 1221 1222avPlayer.reset((err: BusinessError) => { 1223 if (err) { 1224 console.error('Failed to reset,error message is :' + err.message) 1225 } else { 1226 console.info('Succeeded in resetting'); 1227 } 1228}) 1229``` 1230 1231### reset<sup>9+</sup> 1232 1233reset(): Promise\<void> 1234 1235重置播放，只能在initialized/prepared/playing/paused/completed/stopped/error状态调用。通过Promise获取返回值。 1236 1237**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1238 1239**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1240 1241**返回值：** 1242 1243| 类型 | 说明 | 1244| -------------- | ------------------------- | 1245| Promise\<void> | 重置播放的Promise返回值。 | 1246 1247**错误码：** 1248 1249以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1250 1251| 错误码ID | 错误信息 | 1252| -------- | ----------------------------------------- | 1253| 5400102 | Operation not allowed. Return by promise. | 1254 1255**示例：** 1256 1257```ts 1258import { BusinessError } from '@kit.BasicServicesKit'; 1259 1260avPlayer.reset().then(() => { 1261 console.info('Succeeded in resetting'); 1262}, (err: BusinessError) => { 1263 console.error('Failed to reset,error message is :' + err.message) 1264}) 1265``` 1266 1267### release<sup>9+</sup> 1268 1269release(callback: AsyncCallback\<void>): void 1270 1271销毁播放资源，除released状态外，均可以调用。使用callback方式异步获取返回值。 1272 1273**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1274 1275**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1276 1277**参数：** 1278 1279| 参数名 | 类型 | 必填 | 说明 | 1280| -------- | -------- | ---- | -------------------- | 1281| callback | AsyncCallback\<void> | 是 | 销毁播放的回调方法。 | 1282 1283**错误码：** 1284 1285以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1286 1287| 错误码ID | 错误信息 | 1288| -------- | ------------------------------------------ | 1289| 5400102 | Operation not allowed. Return by callback. | 1290 1291**示例：** 1292 1293```ts 1294import { BusinessError } from '@kit.BasicServicesKit'; 1295 1296avPlayer.release((err: BusinessError) => { 1297 if (err) { 1298 console.error('Failed to release,error message is :' + err.message) 1299 } else { 1300 console.info('Succeeded in releasing'); 1301 } 1302}) 1303``` 1304 1305### release<sup>9+</sup> 1306 1307release(): Promise\<void> 1308 1309销毁播放资源，除released状态，都可以调用。通过Promise获取返回值。 1310 1311**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1312 1313**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1314 1315**返回值：** 1316 1317| 类型 | 说明 | 1318| -------------- | ------------------------- | 1319| Promise\<void> | 销毁播放的Promise返回值。 | 1320 1321**错误码：** 1322 1323以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1324 1325| 错误码ID | 错误信息 | 1326| -------- | ----------------------------------------- | 1327| 5400102 | Operation not allowed. Return by promise. | 1328 1329**示例：** 1330 1331```ts 1332import { BusinessError } from '@kit.BasicServicesKit'; 1333 1334avPlayer.release().then(() => { 1335 console.info('Succeeded in releasing'); 1336}, (err: BusinessError) => { 1337 console.error('Failed to release,error message is :' + err.message) 1338}) 1339``` 1340 1341### getTrackDescription<sup>9+</sup> 1342 1343getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 1344 1345获取音视频轨道信息，可以在prepared/playing/paused状态调用。获取所有音视轨道信息，应在数据加载回调后调用。使用callback方式异步获取返回值。 1346 1347**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1348 1349**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1350 1351**参数：** 1352 1353| 参数名 | 类型 | 必填 | 说明 | 1354| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1355| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是 | 回调函数，当获取音频轨道信息成功，err为undefined，data为获取到的MediaDescription数组；否则为错误对象。| 1356 1357**错误码：** 1358 1359以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1360 1361| 错误码ID | 错误信息 | 1362| -------- | ------------------------------------------ | 1363| 5400102 | Operation not allowed. Return by callback. | 1364 1365**示例：** 1366 1367```ts 1368import { BusinessError } from '@kit.BasicServicesKit'; 1369 1370avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1371 if ((arrList) != null) { 1372 console.info('Succeeded in doing getTrackDescription'); 1373 } else { 1374 console.error(`Failed to do getTrackDescription, error:${error}`); 1375 } 1376}); 1377``` 1378 1379### getTrackDescription<sup>9+</sup> 1380 1381getTrackDescription(): Promise\<Array\<MediaDescription>> 1382 1383获取音视频轨道信息，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1384 1385**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1386 1387**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1388 1389**返回值：** 1390 1391| 类型 | 说明 | 1392| ------------------------------------------------------ | ------------------------------------------------- | 1393| Promise<Array<[MediaDescription](#mediadescription8)>> | Promise对象，返回音视频轨道信息MediaDescription数组。 | 1394 1395**错误码：** 1396 1397以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1398 1399| 错误码ID | 错误信息 | 1400| -------- | ----------------------------------------- | 1401| 5400102 | Operation not allowed. Return by promise. | 1402 1403**示例：** 1404 1405```ts 1406import { BusinessError } from '@kit.BasicServicesKit'; 1407 1408avPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 1409 console.info('Succeeded in getting TrackDescription'); 1410}).catch((error: BusinessError) => { 1411 console.error(`Failed to get TrackDescription, error:${error}`); 1412}); 1413``` 1414 1415### getSelectedTracks<sup>12+</sup> 1416 1417getSelectedTracks(): Promise\<Array\<number>> 1418 1419获取已选择的音视频轨道索引，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1420 1421**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1422 1423**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1424 1425**返回值：** 1426 1427| 类型 | 说明 | 1428| ------------------------------------------------------ | ------------------------------------------------- | 1429| Promise<Array<[number]>> | Promise对象，返回已选择音视频轨道索引数组。 | 1430 1431**错误码：** 1432 1433以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1434 1435| 错误码ID | 错误信息 | 1436| -------- | ----------------------------------------- | 1437| 5400102 | Operation not allowed. | 1438 1439**示例：** 1440 1441```ts 1442import { BusinessError } from '@kit.BasicServicesKit'; 1443 1444avPlayer.getSelectedTracks().then((arrList: Array<number>) => { 1445 console.info('Succeeded in getting SelectedTracks'); 1446}).catch((error: BusinessError) => { 1447 console.error(`Failed to get SelectedTracks, error:${error}`); 1448}); 1449``` 1450 1451### getPlaybackInfo<sup>12+</sup> 1452 1453getPlaybackInfo(): Promise\<PlaybackInfo> 1454 1455获取播放过程信息，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1456 1457**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1458 1459**返回值：** 1460 1461| 类型 | 说明 | 1462| ------------------------------------------------------ | ------------------------------------------------- | 1463| Promise<[PlaybackInfo](#playbackinfo12)> | Promise对象，返回播放器信息PlaybackInfo。 | 1464 1465**示例：** 1466 1467```ts 1468import { BusinessError } from '@kit.BasicServicesKit'; 1469import { media } from '@kit.MediaKit'; 1470 1471let avPlayer: media.AVPlayer | undefined = undefined; 1472let playbackInfo: media.PlaybackInfo | undefined = undefined; 1473media.createAVPlayer(async (err: BusinessError, player: media.AVPlayer) => { 1474 if (player != null) { 1475 avPlayer = player; 1476 console.info(`Succeeded in creating AVPlayer`); 1477 if (avPlayer) { 1478 try { 1479 playbackInfo = await avPlayer.getPlaybackInfo(); 1480 console.info(`AVPlayer getPlaybackInfo = ${JSON.stringify(playbackInfo)}`); // 打印整个PlaybackInfo的值 1481 } catch (error) { 1482 console.error(`error = ${error}`); 1483 } 1484 } 1485 } else { 1486 console.error(`Failed to create AVPlayer, error message:${err.message}`); 1487 } 1488}); 1489``` 1490 1491### selectTrack<sup>12+</sup> 1492 1493selectTrack(index: number, mode?: SwitchMode): Promise\<void> 1494 1495使用AVPlayer播放多音视频轨资源时，选择指定轨道播放，通过Promise获取返回值。 1496 1497**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1498 1499**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1500 1501**参数：** 1502 1503| 参数名 | 类型 | 必填 | 说明 | 1504| -------- | -------- | ---- | -------------------- | 1505| index | number | 是 | 多音视频资源的轨道索引，可通过[getTrackDescription](#gettrackdescription9-1)接口获取当前资源的所有轨道信息[MediaDescription](#mediadescription8)。 | 1506| mode | [SwitchMode](#switchmode12) | 否 | 切换视频轨道模式，默认为SMOOTH模式，**仅在DASH协议网络流视频轨切换时生效**，其他场景当前暂不支持。 | 1507 1508**返回值：** 1509 1510| 类型 | 说明 | 1511| -------------- | ------------------------- | 1512| Promise\<void> | 选择轨道完成的Promise返回值。 | 1513 1514**错误码：** 1515 1516以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1517 1518| 错误码ID | 错误信息 | 1519| -------- | ----------------------------------------- | 1520| 401 | The parameter check failed. Return by promise. | 1521| 5400102 | Operation not allowed. Return by promise. | 1522 1523**示例：** 1524 1525```ts 1526import { BusinessError } from '@kit.BasicServicesKit'; 1527import { media } from '@kit.MediaKit'; 1528 1529let avPlayer: media.AVPlayer = await media.createAVPlayer(); 1530let audioTrackIndex: Object = 0; 1531avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1532 if (arrList != null) { 1533 for (let i = 0; i < arrList.length; i++) { 1534 if (i != 0) { 1535 // 获取音频轨道列表 1536 audioTrackIndex = arrList[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 1537 } 1538 } 1539 } else { 1540 console.error(`Failed to get TrackDescription, error:${error}`); 1541 } 1542}); 1543 1544// 选择其中一个音频轨道 1545avPlayer.selectTrack(parseInt(audioTrackIndex.toString())); 1546``` 1547 1548### deselectTrack<sup>12+</sup> 1549 1550deselectTrack(index: number): Promise\<void> 1551 1552使用AVPlayer播放多音轨视频时取消指定音视频轨道播放，通过Promise获取返回值。 1553 1554**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1555 1556**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1557 1558**参数：** 1559 1560| 参数名 | 类型 | 必填 | 说明 | 1561| -------- | -------- | ---- | -------------------- | 1562| index | number | 是 | 多音视频资源的轨道索引，来自[getTrackDescription](#gettrackdescription9-1)接口所获取的轨道信息[MediaDescription](#mediadescription8)。 | 1563 1564**返回值：** 1565 1566| 类型 | 说明 | 1567| -------------- | ------------------------- | 1568| Promise\<void> | 取消选择曲目完成的Promise返回值。 | 1569 1570**错误码：** 1571 1572以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1573 1574| 错误码ID | 错误信息 | 1575| -------- | ----------------------------------------- | 1576| 401 | The parameter check failed. Return by promise. | 1577| 5400102 | Operation not allowed. Return by promise. | 1578 1579**示例：** 1580 1581```ts 1582import { BusinessError } from '@kit.BasicServicesKit'; 1583import { media } from '@kit.MediaKit'; 1584 1585let avPlayer: media.AVPlayer = await media.createAVPlayer(); 1586let audioTrackIndex: Object = 0; 1587avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1588 if (arrList != null) { 1589 for (let i = 0; i < arrList.length; i++) { 1590 if (i != 0) { 1591 // 获取音频轨道列表 1592 audioTrackIndex = arrList[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 1593 } 1594 } 1595 } else { 1596 console.error(`Failed to get TrackDescription, error:${error}`); 1597 } 1598}); 1599 1600// 选择其中一个音频轨道 1601avPlayer.selectTrack(parseInt(audioTrackIndex.toString())); 1602// 取消选择上次选中的音频轨道，并恢复到默认音频轨道。 1603avPlayer.deselectTrack(parseInt(audioTrackIndex.toString())); 1604``` 1605 1606### setDecryptionConfig<sup>11+</sup> 1607 1608setDecryptionConfig(mediaKeySession: drm.MediaKeySession, secureVideoPath: boolean): void 1609 1610设置解密配置。当收到[mediaKeySystemInfoUpdate事件](#onmediakeysysteminfoupdate11)时，需根据事件上报的信息创建相关配置并设置解密配置，否则无法播放。 1611 1612**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1613 1614**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1615 1616**参数：** 1617 1618| 参数名 | 类型 | 必填 | 说明 | 1619| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1620| mediaKeySession | [drm.MediaKeySession](../apis-drm-kit/js-apis-drm.md#mediakeysession) | 是 | 解密会话 | 1621| secureVideoPath | boolean | 是 | 安全视频通路，true表示选择安全视频通路，false表示选择非安全视频通路 | 1622 1623**错误码：** 1624 1625以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1626 1627| 错误码ID | 错误信息 | 1628| -------- | ----------------------------------------- | 1629| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1630 1631**示例：** 1632 1633关于drm模块的示例具体可见[js-apis-drm.md](../apis-drm-kit/js-apis-drm.md)。 1634```ts 1635import { drm } from '@kit.DrmKit'; 1636 1637// 创建MediaKeySystem系统 1638let keySystem:drm.MediaKeySystem = drm.createMediaKeySystem('com.clearplay.drm'); 1639// 创建MediaKeySession解密会话 1640let keySession:drm.MediaKeySession = keySystem.createMediaKeySession(drm.ContentProtectionLevel.CONTENT_PROTECTION_LEVEL_SW_CRYPTO); 1641// 生成许可证请求、设置许可证响应等 1642// 安全视频通路标志 1643let secureVideoPath:boolean = false; 1644// 设置解密配置 1645avPlayer.setDecryptionConfig(keySession, secureVideoPath); 1646``` 1647 1648### getMediaKeySystemInfos<sup>11+</sup> 1649 1650getMediaKeySystemInfos(): Array\<drm.MediaKeySystemInfo> 1651 1652获取当前播放的媒体资源的MediaKeySystemInfo。需要在[mediaKeySystemInfoUpdate事件](#onmediakeysysteminfoupdate11)触发成功后才能调用。 1653 1654**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1655 1656**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1657 1658**返回值：** 1659 1660| 类型 | 说明 | 1661| ------------------------------------------------------ | ------------------------------------------------- | 1662| Array<[drm.MediaKeySystemInfo](../apis-drm-kit/js-apis-drm.md#mediakeysysteminfo)> | MediaKeySystemInfo数组，MediaKeySystemInfo具有uuid和pssh两个属性。 | 1663 1664**示例：** 1665 1666```ts 1667import { drm } from '@kit.DrmKit'; 1668 1669const infos = avPlayer.getMediaKeySystemInfos(); 1670console.info('GetMediaKeySystemInfos count: ' + infos.length); 1671for (let i = 0; i < infos.length; i++) { 1672 console.info('GetMediaKeySystemInfos uuid: ' + infos[i]["uuid"]); 1673 console.info('GetMediaKeySystemInfos pssh: ' + infos[i]["pssh"]); 1674} 1675``` 1676 1677### seek<sup>9+</sup> 1678 1679seek(timeMs: number, mode?:SeekMode): void 1680 1681跳转到指定播放位置，只能在prepared/playing/paused/completed状态调用，可以通过[seekDone事件](#onseekdone9)确认是否生效。 1682注：直播场景不支持seek。 1683 1684**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1685 1686**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1687 1688**参数：** 1689 1690| 参数名 | 类型 | 必填 | 说明 | 1691| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 1692| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, [duration](#属性)]。 | 1693| mode | [SeekMode](#seekmode8) | 否 | 基于视频I帧的跳转模式，默认为SEEK_PREV_SYNC模式，**仅在视频资源播放时设置**。 | 1694 1695**示例：** 1696 1697```ts 1698let seekTime: number = 1000 1699avPlayer.seek(seekTime, media.SeekMode.SEEK_PREV_SYNC) 1700``` 1701 1702### on('seekDone')<sup>9+</sup> 1703 1704on(type: 'seekDone', callback: Callback\<number>): void 1705 1706监听seek生效的事件。 1707 1708**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1709 1710**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1711 1712**参数：** 1713 1714| 参数名 | 类型 | 必填 | 说明 | 1715| -------- | -------- | ---- | ------------------------------------------------------------ | 1716| type | string | 是 | seek生效的事件回调类型，支持的事件：'seekDone'，每次调用seek后都会回调此事件。 | 1717| callback | Callback\<number> | 是 | 回调函数。seek生效的事件回调方法，只会上报用户请求的time位置。<br/>**视频播放：**[SeekMode](#seekmode8)会造成实际跳转位置与用户设置产生偏差，精准位置需要通过currentTime获取，事件回调的time仅代表完成用户某一次请求。 | 1718 1719**示例：** 1720 1721```ts 1722avPlayer.on('seekDone', (seekDoneTime:number) => { 1723 console.info('seekDone called,and seek time is:' + seekDoneTime) 1724}) 1725``` 1726 1727### off('seekDone')<sup>9+</sup> 1728 1729off(type: 'seekDone', callback?: Callback\<number>): void 1730 1731取消监听seek生效的事件。 1732 1733**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1734 1735**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1736 1737**参数：** 1738 1739| 参数名 | 类型 | 必填 | 说明 | 1740| ------ | ------ | ---- | ---------------------------------------------------- | 1741| type | string | 是 | seek生效的事件回调类型，取消注册的事件：'seekDone'。 | 1742| callback | Callback\<number> | 否 | 回调函数。seek生效的事件回调方法，只会上报用户请求的time位置。<br/>**视频播放：**[SeekMode](#seekmode8)会造成实际跳转位置与用户设置产生偏差，精准位置需要通过currentTime获取，事件回调的time仅代表完成用户某一次请求。<br/>从API version 12开始支持此参数。 | 1743 1744**示例：** 1745 1746```ts 1747avPlayer.off('seekDone') 1748``` 1749 1750### setSpeed<sup>9+</sup> 1751 1752setSpeed(speed: PlaybackSpeed): void 1753 1754设置倍速模式，只能在prepared/playing/paused/completed状态调用，可以通过[speedDone事件](#onspeeddone9)确认是否生效。 1755注：直播场景不支持setSpeed。 1756 1757**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1758 1759**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1760 1761**参数：** 1762 1763| 参数名 | 类型 | 必填 | 说明 | 1764| ------ | -------------------------------- | ---- | ------------------ | 1765| speed | [PlaybackSpeed](#playbackspeed8) | 是 | 指定播放倍速模式。 | 1766 1767**示例：** 1768 1769```ts 1770avPlayer.setSpeed(media.PlaybackSpeed.SPEED_FORWARD_2_00_X) 1771``` 1772 1773### on('speedDone')<sup>9+</sup> 1774 1775on(type: 'speedDone', callback: Callback\<number>): void 1776 1777监听setSpeed生效的事件 1778 1779**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1780 1781**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1782 1783**参数：** 1784 1785| 参数名 | 类型 | 必填 | 说明 | 1786| -------- | -------- | ---- | ------------------------------------------------------------ | 1787| type | string | 是 | setSpeed生效的事件回调类型，支持的事件：'speedDone'，每次调用setSpeed后都会回调此事件。 | 1788| callback | Callback\<number> | 是 | 回调函数。当setSpeed成功，上报生效的倍速模式，具体见[PlaybackSpeed](#playbackspeed8)。 | 1789 1790**示例：** 1791 1792```ts 1793avPlayer.on('speedDone', (speed:number) => { 1794 console.info('speedDone called,and speed value is:' + speed) 1795}) 1796``` 1797 1798### off('speedDone')<sup>9+</sup> 1799 1800off(type: 'speedDone', callback?: Callback\<number>): void 1801 1802取消监听setSpeed生效的事件。 1803 1804**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1805 1806**参数：** 1807 1808| 参数名 | 类型 | 必填 | 说明 | 1809| ------ | ------ | ---- | --------------------------------------------------------- | 1810| type | string | 是 | setSpeed生效的事件回调类型，取消注册的事件：'speedDone'。 | 1811| callback | Callback\<number> | 否 | 回调函数。当setSpeed成功，上报生效的倍速模式，具体见[PlaybackSpeed](#playbackspeed8)。<br/>从API version 12开始支持此参数。 | 1812 1813**示例：** 1814 1815```ts 1816avPlayer.off('speedDone') 1817``` 1818 1819### setBitrate<sup>9+</sup> 1820 1821setBitrate(bitrate: number): void 1822 1823设置比特率，以播放所指定比特率的流媒体资源，当前仅对**HLS/DASH协议网络流**有效。默认情况下，AVPlayer会根据网络连接速度选择合适的比特率。只能在prepared/playing/paused/completed状态调用，可以通过[bitrateDone](#onbitratedone9)事件确认是否生效。 1824 1825**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1826 1827**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1828 1829**参数：** 1830 1831| 参数名 | 类型 | 必填 | 说明 | 1832| ------- | ------ | ---- | ------------------------------------------------------------ | 1833| bitrate | number | 是 | 指定比特率，须通过[availableBitrates](#onavailablebitrates9)事件获得当前HLS/DASH协议网络流可用的比特率列表，如果用户指定的比特率不在此列表中，则播放器将从可用比特率列表中选择最接近的比特率。如果通过availableBitrates事件获得的比特率列表长度为0，则不支持指定比特率，也不会产生bitrateDone回调。 | 1834 1835**示例：** 1836 1837```ts 1838let bitrate: number = 96000 1839avPlayer.setBitrate(bitrate) 1840``` 1841 1842### on('bitrateDone')<sup>9+</sup> 1843 1844on(type: 'bitrateDone', callback: Callback\<number>): void 1845 1846监听setBitrate生效的事件。 1847 1848**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1849 1850**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1851 1852**参数：** 1853 1854| 参数名 | 类型 | 必填 | 说明 | 1855| -------- | -------- | ---- | ------------------------------------------------------------ | 1856| type | string | 是 | setBitrate生效的事件回调类型，支持的事件：'bitrateDone'，每次调用setBitrate后都会回调此事件。 | 1857| callback | Callback\<number> | 是 | setBitrate生效的事件回调方法，上报生效的比特率。 | 1858 1859**示例：** 1860 1861```ts 1862avPlayer.on('bitrateDone', (bitrate:number) => { 1863 console.info('bitrateDone called,and bitrate value is:' + bitrate) 1864}) 1865``` 1866 1867### off('bitrateDone')<sup>9+</sup> 1868 1869off(type: 'bitrateDone', callback?: Callback\<number>): void 1870 1871取消监听setBitrate生效的事件。 1872 1873**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1874 1875**参数：** 1876 1877| 参数名 | 类型 | 必填 | 说明 | 1878| ------ | ------ | ---- | ------------------------------------------------------------ | 1879| type | string | 是 | setBitrate生效的事件回调类型，取消注册的事件：'bitrateDone'。 | 1880| callback | Callback\<number> | 否 | setBitrate生效的事件回调方法，上报生效的比特率。<br/>从API version 12开始支持此参数。 | 1881 1882**示例：** 1883 1884```ts 1885avPlayer.off('bitrateDone') 1886``` 1887 1888### on('availableBitrates')<sup>9+</sup> 1889 1890on(type: 'availableBitrates', callback: Callback\<Array\<number>>): void 1891 1892监听HLS/DASH协议网络流可用的比特率列表，只会在切换prepared状态后上报。 1893 1894**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1895 1896**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1897 1898**参数：** 1899 1900| 参数名 | 类型 | 必填 | 说明 | 1901| -------- | -------- | ---- | ------------------------------------------------------------ | 1902| type | string | 是 | HLS/DASH协议网络流可用比特率上报事件回调类型，支持的事件：'availableBitrates'，只会在prepared之后上报一次。 | 1903| callback | Callback\<Array\<number>> | 是 | HLS/DASH协议网络流可用比特率上报事件回调方法，使用数组存放支持的比特率。如果数组长度为0，则不支持指定比特率。 | 1904 1905**示例：** 1906 1907```ts 1908avPlayer.on('availableBitrates', (bitrates: Array<number>) => { 1909 console.info('availableBitrates called,and availableBitrates length is:' + bitrates.length) 1910}) 1911``` 1912 1913### off('availableBitrates')<sup>9+</sup> 1914 1915off(type: 'availableBitrates', callback?: Callback\<Array\<number>>): void 1916 1917取消监听HLS/DASH协议网络流可用的比特率列表，调用[prepare](#prepare9)后，上报此事件。 1918 1919**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1920 1921**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1922 1923**参数：** 1924 1925| 参数名 | 类型 | 必填 | 说明 | 1926| ------ | ------ | ---- | ------------------------------------------------------------ | 1927| type | string | 是 | HLS/DASH协议网络流可用比特率上报事件回调类型，取消注册的事件：'availableBitrates'。 | 1928| callback | Callback\<Array\<number>> | 否 | HLS/DASH协议网络流可用比特率上报事件回调方法，使用数组存放支持的比特率。如果数组长度为0，则不支持指定比特率。<br/>从API version 12开始支持此参数。 | 1929 1930**示例：** 1931 1932```ts 1933avPlayer.off('availableBitrates') 1934``` 1935 1936 1937### on('mediaKeySystemInfoUpdate')<sup>11+</sup> 1938 1939on(type: 'mediaKeySystemInfoUpdate', callback: Callback\<Array\<drm.MediaKeySystemInfo>>): void 1940 1941监听mediaKeySystemInfoUpdate事件。 1942 1943**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1944 1945**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1946 1947**参数：** 1948 1949| 参数名 | 类型 | 必填 | 说明 | 1950| -------- | -------- | ---- | ------------------------------------------------------------ | 1951| type | string | 是 | 版权保护信息更新上报事件回调类型，支持的事件：'mediaKeySystemInfoUpdate'，当播放内容的版权保护信息更新时上报事件。 | 1952| callback | Callback\<Array\<drm.[MediaKeySystemInfo](../apis-drm-kit/js-apis-drm.md#mediakeysysteminfo)>> | 是 | 版权保护信息更新上报事件回调方法，上报MediaKeySystemInfo数组。 | 1953 1954**示例：** 1955 1956```ts 1957import { drm } from '@kit.DrmKit'; 1958 1959avPlayer.on('mediaKeySystemInfoUpdate', (mediaKeySystemInfo: Array<drm.MediaKeySystemInfo>) => { 1960 for (let i = 0; i < mediaKeySystemInfo.length; i++) { 1961 console.info('mediaKeySystemInfoUpdate happened uuid: ' + mediaKeySystemInfo[i]["uuid"]); 1962 console.info('mediaKeySystemInfoUpdate happened pssh: ' + mediaKeySystemInfo[i]["pssh"]); 1963 } 1964}) 1965``` 1966 1967### off('mediaKeySystemInfoUpdate')<sup>11+</sup> 1968 1969off(type: 'mediaKeySystemInfoUpdate', callback?: Callback\<Array\<drm.MediaKeySystemInfo>>): void; 1970 1971取消监听mediaKeySystemInfoUpdate事件。 1972 1973**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1974 1975**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1976 1977**参数：** 1978 1979| 参数名 | 类型 | 必填 | 说明 | 1980| ------ | ------ | ---- | ------------------------------------------------------------ | 1981| type | string | 是 | 版权保护信息更新上报事件回调类型，取消注册的事件：'mediaKeySystemInfoUpdate'。 | 1982| callback | Callback\<Array\<drm.[MediaKeySystemInfo](../apis-drm-kit/js-apis-drm.md#mediakeysysteminfo)>> | 否 | 版权保护信息更新上报事件回调方法，上报版权保护信息数组。如填写该参数，则仅取消注册此回调方法，否则取消注册mediaKeySystemInfoUpdate事件的所有回调方法。 | 1983 1984**示例：** 1985 1986```ts 1987avPlayer.off('mediaKeySystemInfoUpdate') 1988``` 1989 1990### setVolume<sup>9+</sup> 1991 1992setVolume(volume: number): void 1993 1994设置媒体播放音量，只能在prepared/playing/paused/completed状态调用，可以通过[volumeChange事件](#onvolumechange9)确认是否生效。 1995 1996**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1997 1998**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1999 2000**参数：** 2001 2002| 参数名 | 类型 | 必填 | 说明 | 2003| ------ | ------ | ---- | ------------------------------------------------------------ | 2004| volume | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 2005 2006**示例：** 2007 2008```ts 2009let volume: number = 1.0 2010avPlayer.setVolume(volume) 2011``` 2012 2013### on('volumeChange')<sup>9+</sup> 2014 2015on(type: 'volumeChange', callback: Callback\<number>): void 2016 2017监听setVolume生效的事件。 2018 2019**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2020 2021**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2022 2023**参数：** 2024 2025| 参数名 | 类型 | 必填 | 说明 | 2026| -------- | -------- | ---- | ------------------------------------------------------------ | 2027| type | string | 是 | setVolume生效的事件回调类型，支持的事件：'volumeChange'，每次调用setVolume后都会回调此事件。 | 2028| callback | Callback\<number> | 是 | setVolume生效的事件回调方法，上报生效的媒体音量。 | 2029 2030**示例：** 2031 2032```ts 2033avPlayer.on('volumeChange', (vol: number) => { 2034 console.info('volumeChange called,and new volume is :' + vol) 2035}) 2036``` 2037 2038### off('volumeChange')<sup>9+</sup> 2039 2040off(type: 'volumeChange', callback?: Callback\<number>): void 2041 2042取消监听setVolume生效的事件。 2043 2044**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2045 2046**参数：** 2047 2048| 参数名 | 类型 | 必填 | 说明 | 2049| ------ | ------ | ---- | ------------------------------------------------------------ | 2050| type | string | 是 | setVolume生效的事件回调类型，取消注册的事件：'volumeChange'。 | 2051| callback | Callback\<number> | 否 | setVolume生效的事件回调方法，上报生效的媒体音量。<br/>从API version 12开始支持此参数。 | 2052 2053**示例：** 2054 2055```ts 2056avPlayer.off('volumeChange') 2057``` 2058 2059### on('endOfStream')<sup>9+</sup> 2060 2061on(type: 'endOfStream', callback: Callback\<void>): void 2062 2063监听资源播放至结尾的事件；如果用户设置[loop](#属性)=true，播放会跳转至开头重播；如果用户没有设置loop，会通过[stateChange](#onstatechange9)上报completed状态。 2064 2065**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2066 2067**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2068 2069**参数：** 2070 2071| 参数名 | 类型 | 必填 | 说明 | 2072| -------- | -------- | ---- | ------------------------------------------------------------ | 2073| type | string | 是 | 资源播放至结尾的事件回调类型，支持的事件：'endOfStream'，当播放至结尾时会上报此事件。 | 2074| callback | Callback\<void> | 是 | 资源播放至结尾的事件回调方法。 | 2075 2076**示例：** 2077 2078```ts 2079avPlayer.on('endOfStream', () => { 2080 console.info('endOfStream called') 2081}) 2082``` 2083 2084### off('endOfStream')<sup>9+</sup> 2085 2086off(type: 'endOfStream', callback?: Callback\<void>): void 2087 2088取消监听资源播放至结尾的事件。 2089 2090**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2091 2092**参数：** 2093 2094| 参数名 | 类型 | 必填 | 说明 | 2095| ------ | ------ | ---- | ------------------------------------------------------------ | 2096| type | string | 是 | 资源播放至结尾的事件回调类型，取消注册的事件：'endOfStream'。 | 2097| callback | Callback\<void> | 否 | 资源播放至结尾的事件回调方法。<br/>从API version 12开始支持此参数。 | 2098 2099**示例：** 2100 2101```ts 2102avPlayer.off('endOfStream') 2103``` 2104 2105### on('timeUpdate')<sup>9+</sup> 2106 2107on(type: 'timeUpdate', callback: Callback\<number>): void 2108 2109监听资源播放当前时间，单位为毫秒（ms），用于刷新进度条当前位置，默认间隔100ms时间上报，因用户操作(seek)产生的时间变化会立刻上报。 2110 2111注：直播场景不支持timeUpdate上报。 2112 2113**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2114 2115**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2116 2117**参数：** 2118 2119| 参数名 | 类型 | 必填 | 说明 | 2120| -------- | -------- | ---- | ---------------------------------------------- | 2121| type | string | 是 | 时间更新的回调类型，支持的事件：'timeUpdate'。 | 2122| callback | Callback\<number> | 是 | 回调函数。返回当前时间。 | 2123 2124**示例：** 2125 2126```ts 2127avPlayer.on('timeUpdate', (time:number) => { 2128 console.info('timeUpdate called,and new time is :' + time) 2129}) 2130``` 2131 2132### off('timeUpdate')<sup>9+</sup> 2133 2134off(type: 'timeUpdate', callback?: Callback\<number>): void 2135 2136取消监听资源播放当前时间。 2137 2138**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2139 2140**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2141 2142**参数：** 2143 2144| 参数名 | 类型 | 必填 | 说明 | 2145| ------ | ------ | ---- | -------------------------------------------------- | 2146| type | string | 是 | 时间更新的回调类型，取消注册的事件：'timeUpdate'。 | 2147| callback | Callback\<number> | 否 | 回调函数。返回当前时间。<br/>从API version 12开始支持此参数。 | 2148 2149**示例：** 2150 2151```ts 2152avPlayer.off('timeUpdate') 2153``` 2154 2155### on('durationUpdate')<sup>9+</sup> 2156 2157 2158on(type: 'durationUpdate', callback: Callback\<number>): void 2159 2160监听资源播放资源的时长，单位为毫秒（ms），用于刷新进度条长度，默认只在prepared上报一次，同时允许一些特殊码流刷新多次时长。 2161注：直播场景不支持durationUpdate上报。 2162 2163**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2164 2165**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2166 2167**参数：** 2168 2169| 参数名 | 类型 | 必填 | 说明 | 2170| -------- | -------- | ---- | -------------------------------------------------- | 2171| type | string | 是 | 时长更新的回调类型，支持的事件：'durationUpdate'。 | 2172| callback | Callback\<number> | 是 | 回调函数。返回资源时长。 | 2173 2174**示例：** 2175 2176```ts 2177avPlayer.on('durationUpdate', (duration: number) => { 2178 console.info('durationUpdate called,new duration is :' + duration) 2179}) 2180``` 2181 2182### off('durationUpdate')<sup>9+</sup> 2183 2184off(type: 'durationUpdate', callback?: Callback\<number>): void 2185 2186取消监听资源播放资源的时长。 2187 2188**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2189 2190**参数：** 2191 2192| 参数名 | 类型 | 必填 | 说明 | 2193| ------ | ------ | ---- | ------------------------------------------------------ | 2194| type | string | 是 | 时长更新的回调类型，取消注册的事件：'durationUpdate'。 | 2195| callback | Callback\<number> | 否 | 回调函数。返回资源时长。<br/>从API version 12开始支持此参数。 | 2196 2197**示例：** 2198 2199```ts 2200avPlayer.off('durationUpdate') 2201``` 2202 2203### on('bufferingUpdate')<sup>9+</sup> 2204 2205on(type: 'bufferingUpdate', callback: OnBufferingUpdateHandler): void 2206 2207订阅音视频缓存更新事件，仅网络播放支持该订阅事件。 2208 2209**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2210 2211**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2212 2213**参数：** 2214 2215| 参数名 | 类型 | 必填 | 说明 | 2216| -------- | -------- | ---- | ------------------------------------------------------------ | 2217| type | string | 是 | 播放缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 2218| callback | [OnBufferingUpdateHandler](#onbufferingupdatehandler12) | 是 | 播放缓存事件回调方法。 | 2219 2220**示例：** 2221 2222```ts 2223avPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 2224 console.info('bufferingUpdate called,and infoType value is:' + infoType + ', value is :' + value) 2225}) 2226``` 2227 2228### off('bufferingUpdate')<sup>9+</sup> 2229 2230off(type: 'bufferingUpdate', callback?: OnBufferingUpdateHandler): void 2231 2232取消监听音视频缓存更新事件。 2233 2234**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2235 2236**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2237 2238**参数：** 2239 2240| 参数名 | 类型 | 必填 | 说明 | 2241| ------ | ------ | ---- | --------------------------------------------------------- | 2242| type | string | 是 | 播放缓存事件回调类型，取消注册的事件：'bufferingUpdate'。 | 2243| callback | [OnBufferingUpdateHandler](#onbufferingupdatehandler12) | 否 | 播放缓存事件回调方法。 | 2244 2245**示例：** 2246 2247```ts 2248avPlayer.off('bufferingUpdate') 2249``` 2250 2251### on('startRenderFrame')<sup>9+</sup> 2252 2253on(type: 'startRenderFrame', callback: Callback\<void>): void 2254 2255订阅视频播放开始首帧渲染的更新事件，仅视频播放支持该订阅事件，该事件仅代表播放服务将第一帧画面送显示模块，实际效果依赖显示服务渲染性能。 2256 2257**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2258 2259**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2260 2261**参数：** 2262 2263| 参数名 | 类型 | 必填 | 说明 | 2264| -------- | -------- | ---- | ------------------------------------------------------------ | 2265| type | string | 是 | 视频播放开始首帧渲染事件回调类型，支持的事件：'startRenderFrame'。 | 2266| callback | Callback\<void> | 是 | 视频播放开始首帧渲染事件回调方法。 | 2267 2268**示例：** 2269 2270```ts 2271avPlayer.on('startRenderFrame', () => { 2272 console.info('startRenderFrame called') 2273}) 2274``` 2275 2276### off('startRenderFrame')<sup>9+</sup> 2277 2278off(type: 'startRenderFrame', callback?: Callback\<void>): void 2279 2280取消监听视频播放开始首帧渲染的更新事件。 2281 2282**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2283 2284**参数：** 2285 2286| 参数名 | 类型 | 必填 | 说明 | 2287| ------ | ------ | ---- | ------------------------------------------------------------ | 2288| type | string | 是 | 视频播放开始首帧渲染事件回调类型，取消注册的事件：'startRenderFrame'。 | 2289| callback | Callback\<void> | 否 | 视频播放开始首帧渲染事件回调方法。<br/>从API version 12开始支持此参数。 | 2290 2291**示例：** 2292 2293```ts 2294avPlayer.off('startRenderFrame') 2295``` 2296 2297### on('videoSizeChange')<sup>9+</sup> 2298 2299on(type: 'videoSizeChange', callback: OnVideoSizeChangeHandler): void 2300 2301监听视频播放宽高变化事件，仅视频播放支持该订阅事件，默认只在prepared状态上报一次，但HLS协议码流会在切换分辨率时上报。 2302 2303**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2304 2305**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2306 2307**参数：** 2308 2309| 参数名 | 类型 | 必填 | 说明 | 2310| -------- | -------- | ---- | ------------------------------------------------------------ | 2311| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChange'。 | 2312| callback | [OnVideoSizeChangeHandler](#onvideosizechangehandler12) | 是 | 视频播放宽高变化事件回调方法。 | 2313 2314**示例：** 2315 2316```ts 2317avPlayer.on('videoSizeChange', (width: number, height: number) => { 2318 console.info('videoSizeChange called,and width is:' + width + ', height is :' + height) 2319}) 2320``` 2321 2322### off('videoSizeChange')<sup>9+</sup> 2323 2324off(type: 'videoSizeChange', callback?: OnVideoSizeChangeHandler): void 2325 2326取消监听视频播放宽高变化事件。 2327 2328**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2329 2330**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2331 2332**参数：** 2333 2334| 参数名 | 类型 | 必填 | 说明 | 2335| ------ | ------ | ---- | ------------------------------------------------------------ | 2336| type | string | 是 | 视频播放宽高变化事件回调类型，取消注册的事件：'videoSizeChange'。 | 2337| callback | [OnVideoSizeChangeHandler](#onvideosizechangehandler12) | 否 | 视频播放宽高变化事件回调方法。<br/>从API version 12开始支持此参数。 | 2338 2339**示例：** 2340 2341```ts 2342avPlayer.off('videoSizeChange') 2343``` 2344 2345### on('audioInterrupt')<sup>9+</sup> 2346 2347on(type: 'audioInterrupt', callback: Callback\<audio.InterruptEvent>): void 2348 2349监听音频焦点变化事件，多个音视频资源同时播放时，会根据音频焦点模型[audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9)触发此事件。应用需根据不同焦点变化事件作相应处理。具体可参考[处理音频焦点事件](../../media/audio/audio-playback-concurrency.md)。 2350 2351**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2352 2353**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2354 2355**参数：** 2356 2357| 参数名 | 类型 | 必填 | 说明 | 2358| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 2359| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 2360| callback | Callback\<[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)> | 是 | 音频焦点变化事件回调方法。 | 2361 2362**示例：** 2363 2364```ts 2365import { audio } from '@kit.AudioKit'; 2366 2367avPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 2368 console.info('audioInterrupt called,and InterruptEvent info is:' + info) 2369}) 2370``` 2371 2372### off('audioInterrupt')<sup>9+</sup> 2373 2374off(type: 'audioInterrupt', callback?: Callback<audio.InterruptEvent>): void 2375 2376取消监听音频焦点变化事件。 2377 2378**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2379 2380**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2381 2382**参数：** 2383 2384| 参数名 | 类型 | 必填 | 说明 | 2385| ------ | ------ | ---- | ------------------------------------------------------------ | 2386| type | string | 是 | 音频焦点变化事件回调类型，取消注册的事件：'audioInterrupt'。 | 2387| callback | Callback\<[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)> | 否 | 音频焦点变化事件回调方法。<br/>从API version 12开始支持此参数。 | 2388 2389**示例：** 2390 2391```ts 2392avPlayer.off('audioInterrupt') 2393``` 2394 2395### on('audioOutputDeviceChangeWithInfo')<sup>11+</sup> 2396 2397on(type: 'audioOutputDeviceChangeWithInfo', callback: Callback\<audio.AudioStreamDeviceChangeInfo>): void 2398 2399订阅监听音频流输出设备变化及原因，使用callback方式返回结果。 2400 2401**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2402 2403**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2404 2405**参数：** 2406 2407| 参数名 | 类型 | 必填 | 说明 | 2408| :------- | :------------------------- | :--- | :------------------------------------------ | 2409| type | string | 是 | 事件回调类型，支持的事件为：'outputDeviceChangeWithInfo'。 | 2410| callback | Callback\<[audio.AudioStreamDeviceChangeInfo](../apis-audio-kit/js-apis-audio.md#audiostreamdevicechangeinfo11)> | 是 | 回调函数，返回当前音频流的输出设备描述信息及变化原因。 | 2411 2412**错误码：** 2413 2414| 错误码ID | 错误信息 | 2415| -------- | ------------------------------------------ | 2416| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2417 2418**示例：** 2419 2420```ts 2421import { audio } from '@kit.AudioKit'; 2422 2423avPlayer.on('audioOutputDeviceChangeWithInfo', (data: audio.AudioStreamDeviceChangeInfo) => { 2424 console.info(`${JSON.stringify(data)}`); 2425}); 2426``` 2427 2428### off('audioOutputDeviceChangeWithInfo')<sup>11+</sup> 2429 2430off(type: 'audioOutputDeviceChangeWithInfo', callback?: Callback\<audio.AudioStreamDeviceChangeInfo>): void 2431 2432取消订阅监听音频流输出设备变化及原因，使用callback方式返回结果。 2433 2434**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2435 2436**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2437 2438**参数：** 2439 2440| 参数名 | 类型 | 必填 | 说明 | 2441| :------- | :------------------------- | :--- | :------------------------------------------ | 2442| type | string | 是 | 事件回调类型，支持的事件为：'outputDeviceChange'。 | 2443| callback | Callback\<[audio.AudioStreamDeviceChangeInfo](../apis-audio-kit/js-apis-audio.md#audiostreamdevicechangeinfo11)> | 否 | 回调函数，返回当前音频流的输出设备描述信息及变化原因。 | 2444 2445**错误码：** 2446 2447| 错误码ID | 错误信息 | 2448| -------- | ------------------------------------------ | 2449| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2450 2451**示例：** 2452 2453```ts 2454avPlayer.off('audioOutputDeviceChangeWithInfo'); 2455``` 2456 2457### addSubtitleFromFd<sup>12+</sup> 2458 2459addSubtitleFromFd(fd: number, offset?: number, length?: number): Promise\<void> 2460 2461依据fd为视频添加外挂字幕，当前仅支持与视频资源同时设置（在avplayer设置fdSrc视频资源后设置外挂字幕）。使用Promise方式返回结果。 2462 2463**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2464 2465**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2466 2467**参数：** 2468 2469| 参数名 | 类型 | 必填 | 说明 | 2470| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 2471| fd | number | 是 | 资源句柄，通过[resourceManager.getRawFd](../apis-localization-kit/js-apis-resource-manager.md#getrawfd9)获取。 | 2472| offset | number | 否 | 资源偏移量，需要基于预置资源的信息输入，非法值会造成字幕频资源解析错误。 | 2473| length | number | 否 | 资源长度，默认值为文件中从偏移量开始的剩余字节，需要基于预置资源的信息输入，非法值会造成字幕频资源解析错误。 | 2474 2475**返回值：** 2476 2477| 类型 | 说明 | 2478| -------------- | ------------------------------------------ | 2479| Promise\<void> | 添加外挂字幕addSubtitleFromFd方法的Promise返回值。 | 2480 2481**错误码：** 2482 2483| 错误码ID | 错误信息 | 2484| -------- | ------------------------------------------ | 2485| 401 | The parameter check failed. Return by promise. | 2486| 5400102 | Operation not allowed. Return by promise. | 2487 2488**示例：** 2489 2490```ts 2491import { media } from '@kit.MediaKit' 2492import { common } from '@kit.AbilityKit' 2493 2494let context = getContext(this) as common.UIAbilityContext 2495let fileDescriptor = await context.resourceManager.getRawFd('xxx.srt') 2496 2497avPlayer.addSubtitleFromFd(fileDescriptor.fd, fileDescriptor.offset, fileDescriptor.length) 2498``` 2499 2500### addSubtitleFromUrl<sup>12+</sup> 2501 2502addSubtitleFromUrl(url: string): Promise\<void> 2503 2504依据url为视频添加外挂字幕，当前仅支持与视频资源同时设置（在avplayer设置fdSrc视频资源后设置外挂字幕）。使用Promise方式返回结果。 2505 2506**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2507 2508**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2509 2510**参数：** 2511 2512| 参数名 | 类型 | 必填 | 说明 | 2513| ------ | ------ | ---- | ------------------------------------------------------------ | 2514| url | string | 是 | 外挂字幕文件地址。 | 2515 2516**返回值：** 2517 2518| 类型 | 说明 | 2519| -------------- | ------------------------------------------ | 2520| Promise\<void> | 添加外挂字幕addSubtitleFromUrl方法的Promise返回值。 | 2521 2522**错误码：** 2523 2524| 错误码ID | 错误信息 | 2525| -------- | ------------------------------------------ | 2526| 401 | The parameter check failed. Return by promise. | 2527| 5400102 | Operation not allowed. Return by promise. | 2528 2529**示例：** 2530 2531```ts 2532import { media } from '@kit.MediaKit' 2533 2534let fdUrl:string = 'http://xxx.xxx.xxx/xx/index.srt' 2535 2536let avPlayer: media.AVPlayer = await media.createAVPlayer() 2537avPlayer.addSubtitleFromUrl(fdUrl) 2538``` 2539 2540### on('subtitleUpdate')<sup>12+</sup> 2541 2542on(type: 'subtitleUpdate', callback: Callback\<SubtitleInfo>): void 2543 2544订阅获取外挂字幕的事件，当有外挂字幕时，会通过订阅的回调方法通知用户。用户只能订阅一个外挂字幕事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2545 2546**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2547 2548**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2549 2550**参数：** 2551 2552| 参数名 | 类型 | 必填 | 说明 | 2553| -------- | -------- | ---- | ------------------------------------------------------------ | 2554| type | string | 是 | 事件回调类型，支持的事件为：'subtitleUpdate'。 | 2555| callback | function | 是 | 外挂字幕事件回调方法。 | 2556 2557**示例：** 2558 2559```ts 2560avPlayer.on('subtitleUpdate', async (info: media.SubtitleInfo) => { 2561 if (info) { 2562 let text = (!info.text) ? '' : info.text 2563 let startTime = (!info.startTime) ? 0 : info.startTime 2564 let duration = (!info.duration) ? 0 : info.duration 2565 console.info('subtitleUpdate info: text=' + text + ' startTime=' + startTime +' duration=' + duration) 2566 } else { 2567 console.info('subtitleUpdate info is null') 2568 } 2569}) 2570``` 2571 2572### off('subtitleUpdate')<sup>12+</sup> 2573 2574off(type: 'subtitleUpdate', callback?: Callback\<SubtitleInfo>): void 2575 2576取消订阅获取外挂字幕的事件。 2577 2578**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2579 2580**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2581 2582**参数：** 2583 2584| 参数名 | 类型 | 必填 | 说明 | 2585| -------- | -------- | ---- | ------------------------------------------------------------ | 2586| type | string | 是 | 事件回调类型，支持的事件为：'subtitleUpdate'。 | 2587| callback | function | 否 | 取消外挂字幕事件的回调方法。 | 2588 2589**示例：** 2590 2591```ts 2592avPlayer.off('subtitleUpdate') 2593``` 2594 2595### on('trackChange')<sup>12+</sup> 2596 2597on(type: 'trackChange', callback: OnTrackChangeHandler): void 2598 2599订阅获取轨道变更的事件，当播放的轨道变更时，会通过订阅的回调方法通知用户。用户只能订阅一个轨道变更事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2600 2601**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2602 2603**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2604 2605**参数：** 2606 2607| 参数名 | 类型 | 必填 | 说明 | 2608| -------- | -------- | ---- | ------------------------------------------------------------ | 2609| type | string | 是 | 事件回调类型，支持的事件为：'trackChange'。 | 2610| callback | [OnTrackChangeHandler](#ontrackchangehandler12) | 是 | 轨道变更事件回调方法。 | 2611 2612**示例：** 2613 2614```ts 2615avPlayer.on('trackChange', (index: number, isSelect: boolean) => { 2616 console.info('trackChange info: index=' + index + ' isSelect=' + isSelect) 2617}) 2618``` 2619 2620### off('trackChange')<sup>12+</sup> 2621 2622off(type: 'trackChange', callback?: OnTrackChangeHandler): void 2623 2624取消订阅获取轨道变更的事件。 2625 2626**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2627 2628**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2629 2630**参数：** 2631 2632| 参数名 | 类型 | 必填 | 说明 | 2633| -------- | -------- | ---- | ------------------------------------------------------------ | 2634| type | string | 是 | 事件回调类型，支持的事件为：'trackChange'。 | 2635| callback | [OnTrackChangeHandler](#ontrackchangehandler12) | 否 | 取消轨道变更事件的回调方法。 | 2636 2637**示例：** 2638 2639```ts 2640avPlayer.off('trackChange') 2641``` 2642 2643### on('trackInfoUpdate')<sup>12+</sup> 2644 2645on(type: 'trackInfoUpdate', callback: Callback\<Array\<MediaDescription>>): void 2646 2647订阅获取轨道信息更新的事件，当播放的轨道有更新时，会通过订阅的回调方法通知用户。用户只能订阅一个轨道变更事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2648 2649**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2650 2651**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2652 2653**参数：** 2654 2655| 参数名 | 类型 | 必填 | 说明 | 2656| -------- | -------- | ---- | ------------------------------------------------------------ | 2657| type | string | 是 | 事件回调类型，支持的事件为：'trackInfoUpdate'。 | 2658| callback | Callback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 轨道信息更新事件回调方法。 | 2659 2660**示例：** 2661 2662```ts 2663avPlayer.on('trackInfoUpdate', (info: Array<media.MediaDescription>) => { 2664 if (info) { 2665 for (let i = 0; i < info.length; i++) { 2666 let propertyIndex: Object = info[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 2667 let propertyType: Object = info[i][media.MediaDescriptionKey.MD_KEY_TRACK_TYPE]; 2668 console.info('track info: index=' + propertyIndex + ' tracktype=' + propertyType) 2669 } 2670 } else { 2671 console.info('track info is null') 2672 } 2673}) 2674``` 2675 2676### off('trackInfoUpdate')<sup>12+</sup> 2677 2678off(type: 'trackInfoUpdate', callback?: Callback\<Array\<MediaDescription>>): void 2679 2680取消订阅获取轨道变更的事件。 2681 2682**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2683 2684**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2685 2686**参数：** 2687 2688| 参数名 | 类型 | 必填 | 说明 | 2689| -------- | -------- | ---- | ------------------------------------------------------------ | 2690| type | string | 是 | 事件回调类型，支持的事件为：'trackInfoUpdate'。 | 2691| callback | Callback\<Array\<[MediaDescription](#mediadescription8)>> | 否 | 取消轨道信息更新事件的回调方法。 | 2692 2693**示例：** 2694 2695```ts 2696avPlayer.off('trackInfoUpdate') 2697``` 2698 2699### on('amplitudeUpdate')<sup>13+</sup> 2700 2701on(type: 'amplitudeUpdate', callback: Callback\<Array\<number>>): void 2702 2703订阅音频最大电平值，音频资源播放时定时上报。 2704 2705**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2706 2707**参数：** 2708 2709| 参数名 | 类型 | 必填 | 说明 | 2710| -------- | -------- | ---- | ------------------------------------------------------------ | 2711| type | string | 是 | 事件回调类型，支持的事件为：'amplitudeUpdate'。 | 2712| callback | Callback\<Array\<number>> | 是 | 音频最大电平值更新事件回调方法。 | 2713 2714**示例：** 2715 2716```ts 2717avPlayer.on('amplitudeUpdate', (value: Array<number>) => { 2718 console.info('amplitudeUpdate called,and amplitudeUpdate = ${value}') 2719}) 2720``` 2721 2722### off('amplitudeUpdate')<sup>13+</sup> 2723 2724off(type: 'amplitudeUpdate', callback?: Callback\<Array\<number>>): void 2725 2726取消订阅获取音频最大电平值事件。 2727 2728**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2729 2730**参数：** 2731 2732| 参数名 | 类型 | 必填 | 说明 | 2733| ------ | ------ | ---- | ------------------------------------------------------------ | 2734| type | string | 是 | 事件回调类型，支持的事件为：'amplitudeUpdate'。 | 2735| callback | Callback\<Array\<number>> | 否 | 取消音频最大电平值更新事件回调方法。 | 2736 2737**示例：** 2738 2739```ts 2740avPlayer.off('amplitudeUpdate') 2741``` 2742 2743## AVPlayerState<sup>9+</sup> 2744 2745type AVPlayerState = 'idle' | 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' | 'released' | 'error' 2746 2747[AVPlayer](#avplayer9)的状态机，可通过state属性主动获取当前状态，也可通过监听[stateChange](#onstatechange9)事件上报当前状态，状态机之间的切换规则，可参考[音频播放开发指导](../../media/media/using-avplayer-for-playback.md)。 2748 2749**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2750 2751**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2752 2753| 类型 | 说明 | 2754| :-----------------------------: | :----------------------------------------------------------- | 2755| '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属性会被重置，其他用户设置的属性将被保留。 | 2756| 'initialized' | 资源初始化，在Idle 状态设置 url<sup>9+</sup> 或 fdSrc<sup>9+</sup>属性，AVPlayer会进入initialized状态，此时可以配置窗口、音频等静态属性。 | 2757| 'prepared' | 已准备状态，在initialized状态调用[prepare()](#prepare9)方法，AVPlayer会进入prepared状态，此时播放引擎的资源已准备就绪。 | 2758| 'playing' | 正在播放状态，在prepared/paused/completed状态调用[play()](#play9)方法，AVPlayer会进入playing状态。 | 2759| 'paused' | 暂停状态，在playing状态调用pause方法，AVPlayer会进入paused状态。 | 2760| 'completed' | 播放至结尾状态，当媒体资源播放至结尾时，如果用户未设置循环播放（loop = true），AVPlayer会进入completed状态，此时调用[play()](#play9)会进入playing状态和重播，调用[stop()](#stop9)会进入stopped状态。 | 2761| 'stopped' | 停止状态，在prepared/playing/paused/completed状态调用[stop()](#stop9)方法，AVPlayer会进入stopped状态，此时播放引擎只会保留属性，但会释放内存资源，可以调用[prepare()](#prepare9)重新准备，也可以调用[reset()](#reset9)重置，或者调用[release()](#release9)彻底销毁。 | 2762| 'released' | 销毁状态，销毁与当前AVPlayer关联的播放引擎，无法再进行状态转换，调用[release()](#release9)方法后，会进入released状态，结束流程。 | 2763| '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：播放过程发现码流问题，导致容器、解码短暂异常，不影响连续播放和播控操作的，不需要客户端设计容错机制。 | 2764 2765## OnTrackChangeHandler<sup>12+</sup> 2766 2767type OnTrackChangeHandler = (index: number, isSelected: boolean) => void 2768 2769track变更事件回调方法。 2770 2771**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2772 2773**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2774 2775| 参数名 | 类型 | 必填 | 说明 | 2776| ------ | ------ | ------ | ---------------------------------------------------------- | 2777| index | number | 是 | 当前选中的track索引。 | 2778| isSelected | boolean | 是 | 当前索引的选中状态。 | 2779 2780## OnAVPlayerStateChangeHandle<sup>12+</sup> 2781 2782type OnAVPlayerStateChangeHandle = (state: AVPlayerState, reason: StateChangeReason) => void 2783 2784状态机切换事件回调方法。 2785 2786**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2787 2788**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2789 2790| 参数名 | 类型 | 必填 | 说明 | 2791| ------ | ------ | ------ | ---------------------------------------------------------- | 2792| state | [AVPlayerState](#avplayerstate9) | 是 | 当前播放状态。 | 2793| reason | [StateChangeReason](#statechangereason9) | 是 | 当前播放状态的切换原因。 | 2794 2795## OnBufferingUpdateHandler<sup>12+</sup> 2796 2797type OnBufferingUpdateHandler = (infoType: BufferingInfoType, value: number) => void 2798 2799播放缓存事件回调方法。 2800 2801**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2802 2803**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2804 2805| 参数名 | 类型 | 必填 | 说明 | 2806| ------ | ------ | ------ | ------------------------------------------------------------ | 2807| infoType | [BufferingInfoType](#bufferinginfotype8) | 是 | 缓存时间类型。 | 2808| value | number | 是 | value值固定为0。 | 2809 2810## OnVideoSizeChangeHandler<sup>12+</sup> 2811 2812type OnVideoSizeChangeHandler = (width: number, height: number) => void 2813 2814视频播放宽高变化事件回调方法。 2815 2816**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2817 2818**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2819 2820| 参数名 | 类型 | 必填 | 说明 | 2821| ------ | ------ | ------ | ------------------------------------------------------------ | 2822| width | number | 是 | 视频宽度。 | 2823| height | number | 是 | 视频高度。 | 2824 2825## AVFileDescriptor<sup>9+</sup> 2826 2827音视频文件资源描述，一种特殊资源的播放方式，使用场景：应用中的音频资源被连续存储在同一个文件中，需要根据偏移量和长度进行播放。 2828 2829**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2830 2831**系统能力：** SystemCapability.Multimedia.Media.Core 2832 2833| 名称 | 类型 | 必填 | 说明 | 2834| ------ | ------ | ---- | ------------------------------------------------------------ | 2835| 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)获取。 | 2836| offset | number | 否 | 资源偏移量，默认值为0，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 2837| length | number | 否 | 资源长度，默认值为文件中从偏移量开始的剩余字节，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 2838 2839## AVDataSrcDescriptor<sup>10+</sup> 2840 2841音视频文件资源描述，用于DataSource播放方式，使用场景：应用在未获取完整音视频资源时，允许用户创建播放实例并开始播放，达到提前播放的目的。 2842 2843**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2844 2845**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2846 2847| 名称 | 类型 | 必填 | 说明 | 2848| ------ | ------ | ---- | ------------------------------------------------------------ | 2849| fileSize | number | 是 | 待播放文件大小（字节），-1代表大小未知。如果fileSize设置为-1, 播放模式类似于直播，不能进行seek及setSpeed操作，不能设置loop属性，因此不能重新播放。 | 2850| 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类型，返回要填充数据的长度。 | 2851 2852## SubtitleInfo<sup>12+</sup> 2853 2854外挂字幕信息，使用场景：订阅外挂字幕事件，回调返回外挂字幕详细信息。 2855 2856**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2857 2858**系统能力：** SystemCapability.Multimedia.Media.Core 2859 2860| 名称 | 类型 | 必填 | 说明 | 2861| ------ | ------ | ---- | ------------------------------------------------------------ | 2862| text | string | 否 | 字幕文本信息。 | 2863| startTime | number | 否 | 显示当前字幕文本的开始时间（单位：毫秒）。 | 2864| duration | number | 否 | 显示当前字幕文本的持续时间（单位：毫秒）。 | 2865 2866## SeekMode<sup>8+</sup> 2867 2868视频播放的Seek模式枚举，可通过seek方法作为参数传递下去。 2869 2870**系统能力：** SystemCapability.Multimedia.Media.Core 2871 2872| 名称 | 值 | 说明 | 2873| -------------- | ---- | ------------------------------------------------------------ | 2874| SEEK_NEXT_SYNC | 0 | 表示跳转到指定时间点的下一个关键帧，建议向后快进的时候用这个枚举值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2875| SEEK_PREV_SYNC | 1 | 表示跳转到指定时间点的上一个关键帧，建议向前快进的时候用这个枚举值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2876| SEEK_CLOSEST<sup>12+</sup> | 2 | 表示跳转到距离指定时间点最近的帧，建议精准跳转进度的时候用这个枚举值。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2877 2878## SwitchMode<sup>12+</sup> 2879 2880视频播放的selectTrack模式枚举，可通过selectTrack方法作为参数传递下去，当前仅DASH协议视频轨支持该扩展参数。 2881 2882**系统能力：** SystemCapability.Multimedia.Media.Core 2883 2884| 名称 | 值 | 说明 | 2885| -------------- | ---- | ------------------------------------------------------------ | 2886| SMOOTH | 0 | 表示切换后视频平滑播放，该模式切换存在延迟，不会立即生效。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2887| SEGMENT | 1 | 表示切换后从当前分片开始位置播放，该模式立即切换，会有重复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2888| CLOSEST | 2 | 表示从距离当前播放时间点最近的帧开始播放，该模式立即切换，切换后会卡住3到5s，然后恢复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2889 2890## PlaybackSpeed<sup>8+</sup> 2891 2892视频播放的倍速枚举，可通过setSpeed方法作为参数传递下去。 2893 2894**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2895 2896**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 2897 2898| 名称 | 值 | 说明 | 2899| -------------------- | ---- | ------------------------------ | 2900| SPEED_FORWARD_0_75_X | 0 | 表示视频播放正常播速的0.75倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2901| SPEED_FORWARD_1_00_X | 1 | 表示视频播放正常播速。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2902| SPEED_FORWARD_1_25_X | 2 | 表示视频播放正常播速的1.25倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2903| SPEED_FORWARD_1_75_X | 3 | 表示视频播放正常播速的1.75倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2904| SPEED_FORWARD_2_00_X | 4 | 表示视频播放正常播速的2.00倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2905| SPEED_FORWARD_0_50_X<sup>12+</sup> | 5 | 表示视频播放正常播速的0.50倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2906| SPEED_FORWARD_1_50_X<sup>12+</sup> | 6 | 表示视频播放正常播速的1.50倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2907| SPEED_FORWARD_3_00_X<sup>13+</sup> | 7 | 表示视频播放正常播速的3.00倍。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 2908| SPEED_FORWARD_0_25_X<sup>12+</sup> | 8 | 表示视频播放正常播速的0.25倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2909| SPEED_FORWARD_0_125_X<sup>12+</sup> | 9 | 表示视频播放正常播速的0.125倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2910 2911## VideoScaleType<sup>9+</sup> 2912 2913枚举，视频缩放模式。 2914 2915**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2916 2917**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 2918 2919| 名称 | 值 | 说明 | 2920| ------------------------- | ---- | ------------------------------------------------ | 2921| VIDEO_SCALE_TYPE_FIT | 0 | 默认比例类型，视频拉伸至与窗口等大。 | 2922| VIDEO_SCALE_TYPE_FIT_CROP | 1 | 保持视频宽高比拉伸至填满窗口，内容可能会有裁剪。 | 2923 2924## MediaDescription<sup>8+</sup> 2925 2926通过key-value方式获取媒体信息。 2927 2928**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2929 2930**系统能力：** SystemCapability.Multimedia.Media.Core 2931 2932| 名称 | 类型 | 必填 | 说明 | 2933| ------------- | ------ | ---- | ------------------------------------------------------------ | 2934| [key: string] | Object | 是 | 该键值对支持的key取值范围，请参考[MediaDescriptionKey](#mediadescriptionkey8);每个key值的Object类型和范围，请参考[MediaDescriptionKey](#mediadescriptionkey8)对应Key值的说明 | 2935 2936**示例：** 2937 2938```ts 2939import { BusinessError } from '@kit.BasicServicesKit'; 2940import { media } from '@kit.MediaKit'; 2941 2942function printfItemDescription(obj: media.MediaDescription, key: string) { 2943 let property: Object = obj[key]; 2944 console.info('audio key is ' + key); // 通过key值获取对应的value。key值具体可见[MediaDescriptionKey] 2945 console.info('audio value is ' + property); //对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[MediaDescriptionKey] 2946} 2947 2948let avPlayer: media.AVPlayer | undefined = undefined; 2949media.createAVPlayer((err: BusinessError, player: media.AVPlayer) => { 2950 if(player != null) { 2951 avPlayer = player; 2952 console.info(`Succeeded in creating AVPlayer`); 2953 avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 2954 if (arrList != null) { 2955 for (let i = 0; i < arrList.length; i++) { 2956 printfItemDescription(arrList[i], media.MediaDescriptionKey.MD_KEY_TRACK_TYPE); //打印出每条轨道MD_KEY_TRACK_TYPE的值 2957 } 2958 } else { 2959 console.error(`Failed to get TrackDescription, error:${error}`); 2960 } 2961 }); 2962 } else { 2963 console.error(`Failed to create AVPlayer, error message:${err.message}`); 2964 } 2965}); 2966``` 2967 2968## PlaybackInfo<sup>12+</sup> 2969 2970通过key-value方式获取播放信息。 2971 2972**系统能力：** SystemCapability.Multimedia.Media.Core 2973 2974| 名称 | 类型 | 必填 | 说明 | 2975| ------------- | ------ | ---- | ------------------------------------------------------------ | 2976| [key: string] | Object | 是 | 该键值对支持的key取值范围，请参考[PlaybackInfoKey](#playbackinfokey12);每个key值的Object类型和范围，请参考[PlaybackInfoKey](#playbackinfokey12)对应Key值的说明。 | 2977 2978**示例：** 2979 2980```ts 2981import { BusinessError } from '@kit.BasicServicesKit'; 2982import { media } from '@kit.MediaKit'; 2983 2984function printfPlaybackInfo(obj: media.PlaybackInfo, key: string) { 2985 let property: Object = obj[key]; 2986 console.info('key is ' + key); // 通过key值获取对应的value。key值具体可见[PlaybackInfoKey] 2987 console.info('value is ' + property); //对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[PlaybackInfoKey] 2988} 2989 2990let avPlayer: media.AVPlayer | undefined = undefined; 2991let playbackInfo: media.PlaybackInfo | undefined = undefined; 2992media.createAVPlayer(async (err: BusinessError, player: media.AVPlayer) => { 2993 if (player != null) { 2994 avPlayer = player; 2995 console.info(`Succeeded in creating AVPlayer`); 2996 if (avPlayer) { 2997 try { 2998 playbackInfo = await avPlayer.getPlaybackInfo(); 2999 console.info(`AVPlayer getPlaybackInfo = ${JSON.stringify(playbackInfo)}`); // 打印整个PlaybackInfo的值 3000 printfPlaybackInfo(playbackInfo, media.PlaybackInfoKey.SERVER_IP_ADDRESS); // 打印ip的值 3001 } catch (error) { 3002 console.error(`error = ${error}`); 3003 } 3004 } 3005 } else { 3006 console.error(`Failed to create AVPlayer, error message:${err.message}`); 3007 } 3008}); 3009``` 3010 3011## AVRecorder<sup>9+</sup> 3012 3013音视频录制管理类，用于音视频媒体录制。在调用AVRecorder的方法前，需要先通过[createAVRecorder()](#mediacreateavrecorder9)构建一个AVRecorder实例。 3014 3015音视频录制demo可参考：[音频录制开发指导](../../media/media/using-avrecorder-for-recording.md)、[视频录制开发指导](../../media/media/video-recording.md)。 3016 3017> **说明：** 3018> 3019> 使用相机进行视频录制时，需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/js-apis-camera.md)。 3020 3021### 属性 3022 3023**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3024 3025| 名称 | 类型 | 只读 | 可选 | 说明 | 3026| ------- | ------------------------------------ | ---- | ---- | ------------------ | 3027| state9+ | [AVRecorderState](#avrecorderstate9) | 是 | 否 | 音视频录制的状态。<br>**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 3028 3029### prepare<sup>9+</sup> 3030 3031prepare(config: AVRecorderConfig, callback: AsyncCallback\<void>): void 3032 3033异步方式进行音视频录制的参数设置。通过注册回调函数获取返回值。 3034 3035**需要权限：** ohos.permission.MICROPHONE 3036 3037不涉及音频录制时，可以不需要获取ohos.permission.MICROPHONE权限。 3038 3039使用相机视频录制还需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/js-apis-camera.md)。 3040 3041**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3042 3043**参数：** 3044 3045| 参数名 | 类型 | 必填 | 说明 | 3046| -------- | -------------------------------------- | ---- | ------------------------------------- | 3047| config | [AVRecorderConfig](#avrecorderconfig9) | 是 | 配置音视频录制的相关参数。 | 3048| callback | AsyncCallback\<void> | 是 | 回调函数。当prepare方法成功，err为undefined，否则为错误对象。 | 3049 3050**错误码：** 3051 3052以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3053 3054| 错误码ID | 错误信息 | 3055| -------- | --------------------------------------- | 3056| 201 | Permission denied. Return by callback. | 3057| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3058| 5400102 | Operate not permit. Return by callback. | 3059| 5400105 | Service died. Return by callback. | 3060 3061**示例：** 3062 3063```ts 3064import { BusinessError } from '@kit.BasicServicesKit'; 3065 3066// 配置参数以实际硬件设备支持的范围为准 3067let avRecorderProfile: media.AVRecorderProfile = { 3068 audioBitrate : 48000, 3069 audioChannels : 2, 3070 audioCodec : media.CodecMimeType.AUDIO_AAC, 3071 audioSampleRate : 48000, 3072 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 3073 videoBitrate : 2000000, 3074 videoCodec : media.CodecMimeType.VIDEO_AVC, 3075 videoFrameWidth : 640, 3076 videoFrameHeight : 480, 3077 videoFrameRate : 30 3078} 3079let avRecorderConfig: media.AVRecorderConfig = { 3080 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 3081 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 3082 profile : avRecorderProfile, 3083 url : 'fd://', // 文件需先由调用者创建，赋予读写权限，将文件fd传给此参数，eg.fd://45 3084 rotation : 0, // 合理值0、90、180、270，非合理值prepare接口将报错 3085 location : { latitude : 30, longitude : 130 } 3086} 3087 3088avRecorder.prepare(avRecorderConfig, (err: BusinessError) => { 3089 if (err) { 3090 console.error('Failed to prepare and error is ' + err.message); 3091 } else { 3092 console.info('Succeeded in preparing'); 3093 } 3094}) 3095``` 3096 3097### prepare<sup>9+</sup> 3098 3099prepare(config: AVRecorderConfig): Promise\<void> 3100 3101异步方式进行音视频录制的参数设置。通过Promise获取返回值。 3102 3103**需要权限：** ohos.permission.MICROPHONE 3104 3105不涉及音频录制时，可以不需要获ohos.permission.MICROPHONE权限。 3106 3107使用相机视频录制还需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/js-apis-camera.md)。 3108 3109**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3110 3111**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3112 3113**参数：** 3114 3115| 参数名 | 类型 | 必填 | 说明 | 3116| ------ | -------------------------------------- | ---- | -------------------------- | 3117| config | [AVRecorderConfig](#avrecorderconfig9) | 是 | 配置音视频录制的相关参数。 | 3118 3119**返回值：** 3120 3121| 类型 | 说明 | 3122| -------------- | ------------------------------------------ | 3123| Promise\<void> | 异步音视频录制prepare方法的Promise返回值。 | 3124 3125**错误码：** 3126 3127以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3128 3129| 错误码ID | 错误信息 | 3130| -------- | -------------------------------------- | 3131| 201 | Permission denied. Return by promise. | 3132| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3133| 5400102 | Operate not permit. Return by promise. | 3134| 5400105 | Service died. Return by promise. | 3135 3136**示例：** 3137 3138```ts 3139import { BusinessError } from '@kit.BasicServicesKit'; 3140 3141// 配置参数以实际硬件设备支持的范围为准 3142let avRecorderProfile: media.AVRecorderProfile = { 3143 audioBitrate : 48000, 3144 audioChannels : 2, 3145 audioCodec : media.CodecMimeType.AUDIO_AAC, 3146 audioSampleRate : 48000, 3147 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 3148 videoBitrate : 2000000, 3149 videoCodec : media.CodecMimeType.VIDEO_AVC, 3150 videoFrameWidth : 640, 3151 videoFrameHeight : 480, 3152 videoFrameRate : 30 3153} 3154let avRecorderConfig: media.AVRecorderConfig = { 3155 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 3156 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 3157 profile : avRecorderProfile, 3158 url : 'fd://', // 文件需先由调用者创建，赋予读写权限，将文件fd传给此参数，eg.fd://45 3159 rotation : 0, // 合理值0、90、180、270，非合理值prepare接口报错 3160 location : { latitude : 30, longitude : 130 } 3161} 3162 3163avRecorder.prepare(avRecorderConfig).then(() => { 3164 console.info('Succeeded in preparing'); 3165}).catch((err: BusinessError) => { 3166 console.error('Failed to prepare and catch error is ' + err.message); 3167}); 3168``` 3169 3170### getInputSurface<sup>9+</sup> 3171 3172getInputSurface(callback: AsyncCallback\<string>): void 3173 3174异步方式获得录制需要的surface。通过注册回调函数获取返回值。此surface提供给调用者，调用者从此surface中获取surfaceBuffer，填入相应的视频数据。 3175 3176应当注意，填入的视频数据需要携带时间戳（单位ns）和buffersize。时间戳的起始时间请以系统启动时间为基准。 3177 3178需在[prepare()](#prepare9-2)事件成功触发后，才能调用getInputSurface()方法。 3179 3180**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3181 3182**参数：** 3183 3184| 参数名 | 类型 | 必填 | 说明 | 3185| -------- | ---------------------- | ---- | --------------------------- | 3186| callback | AsyncCallback\<string> | 是 | 回调函数。当获取surface成功，err为undefined，data为获取到的surfaceId，否则为错误对象。 | 3187 3188**错误码：** 3189 3190以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3191 3192| 错误码ID | 错误信息 | 3193| -------- | --------------------------------------- | 3194| 5400102 | Operate not permit. Return by callback. | 3195| 5400103 | IO error. Return by callback. | 3196| 5400105 | Service died. Return by callback. | 3197 3198**示例：** 3199 3200```ts 3201import { BusinessError } from '@kit.BasicServicesKit'; 3202let surfaceID: string; // 该surfaceID用于传递给相机接口创造videoOutput 3203 3204avRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 3205 if (err) { 3206 console.error('Failed to do getInputSurface and error is ' + err.message); 3207 } else { 3208 console.info('Succeeded in doing getInputSurface'); 3209 surfaceID = surfaceId; 3210 } 3211}); 3212 3213``` 3214 3215### getInputSurface<sup>9+</sup> 3216 3217getInputSurface(): Promise\<string> 3218 3219异步方式获得录制需要的surface。通过Promise获取返回值。此surface提供给调用者，调用者从此surface中获取surfaceBuffer，填入相应的视频数据。 3220 3221应当注意，填入的视频数据需要携带时间戳（单位ns）和buffersize。时间戳的起始时间请以系统启动时间为基准。 3222 3223需在[prepare()](#prepare9-3)事件成功触发后，才能调用getInputSurface方法。 3224 3225**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3226 3227**返回值：** 3228 3229| 类型 | 说明 | 3230| ---------------- | -------------------------------- | 3231| Promise\<string> | 异步获得surface的Promise返回值。 | 3232 3233**错误码：** 3234 3235以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3236 3237| 错误码ID | 错误信息 | 3238| -------- | -------------------------------------- | 3239| 5400102 | Operate not permit. Return by promise. | 3240| 5400103 | IO error. Return by promise. | 3241| 5400105 | Service died. Return by promise. | 3242 3243**示例：** 3244 3245```ts 3246import { BusinessError } from '@kit.BasicServicesKit'; 3247let surfaceID: string; // 该surfaceID用于传递给相机接口创造videoOutput 3248 3249avRecorder.getInputSurface().then((surfaceId: string) => { 3250 console.info('Succeeded in getting InputSurface'); 3251 surfaceID = surfaceId; 3252}).catch((err: BusinessError) => { 3253 console.error('Failed to get InputSurface and catch error is ' + err.message); 3254}); 3255``` 3256 3257### updateRotation<sup>12+</sup> 3258 3259updateRotation(rotation: number): Promise\<void> 3260 3261更新视频旋转角度。通过Promise获取返回值。 3262 3263当且仅当[prepare()](#prepare9-3)事件成功触发后，且在[start()](#start9)之前，才能调用updateRotation方法。 3264 3265**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3266 3267**参数：** 3268 3269| 参数名 | 类型 | 必填 | 说明 | 3270| -------- | -------------------- | ---- | --------------------------- | 3271| rotation | number | 是 | 旋转角度，取值仅支持0、90、180、270度。 | 3272 3273**返回值：** 3274 3275| 类型 | 说明 | 3276| ---------------- | -------------------------------- | 3277| Promise\<void> | 异步返回函数执行结果。 | 3278 3279**错误码：** 3280 3281以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3282 3283| 错误码ID | 错误信息 | 3284| -------- | -------------------------------------- | 3285| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3286| 5400102 | Operation not allowed. Return by promise. | 3287| 5400103 | IO error. Return by promise. | 3288| 5400105 | Service died. Return by promise. | 3289 3290**示例：** 3291 3292```ts 3293import { BusinessError } from '@kit.BasicServicesKit'; 3294 3295let rotation = 90 3296 3297avRecorder.updateRotation(rotation).then(() => { 3298 console.info('Succeeded in updateRotation'); 3299}).catch((err: BusinessError) => { 3300 console.error('Failed to updateRotation and catch error is ' + err.message); 3301}); 3302``` 3303 3304### start<sup>9+</sup> 3305 3306start(callback: AsyncCallback\<void>): void 3307 3308异步方式开始视频录制。通过注册回调函数获取返回值。 3309 3310纯音频录制需在[prepare()](#prepare9-2)事件成功触发后，才能调用start方法。纯视频录制，音视频录制需在[getInputSurface()](#getinputsurface9)事件成功触发后，才能调用start方法。 3311 3312**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3313 3314**参数：** 3315 3316| 参数名 | 类型 | 必填 | 说明 | 3317| -------- | -------------------- | ---- | ---------------------------- | 3318| callback | AsyncCallback\<void> | 是 |回调函数。当开始录制视频成功，err为undefined，否则为错误对象。 | 3319 3320**错误码：** 3321 3322以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3323 3324| 错误码ID | 错误信息 | 3325| -------- | --------------------------------------- | 3326| 5400102 | Operate not permit. Return by callback. | 3327| 5400103 | IO error. Return by callback. | 3328| 5400105 | Service died. Return by callback. | 3329 3330**示例：** 3331 3332```ts 3333import { BusinessError } from '@kit.BasicServicesKit'; 3334 3335avRecorder.start((err: BusinessError) => { 3336 if (err) { 3337 console.error('Failed to start AVRecorder and error is ' + err.message); 3338 } else { 3339 console.info('Succeeded in starting AVRecorder'); 3340 } 3341}); 3342``` 3343 3344### start<sup>9+</sup> 3345 3346start(): Promise\<void> 3347 3348异步方式开始视频录制。通过Promise获取返回值。 3349 3350纯音频录制需在[prepare()](#prepare9-3)事件成功触发后，才能调用start方法。纯视频录制，音视频录制需在[getInputSurface()](#getinputsurface9-1)事件成功触发后，才能调用start方法。 3351 3352**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3353 3354**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3355 3356**返回值：** 3357 3358| 类型 | 说明 | 3359| -------------- | ------------------------------------- | 3360| Promise\<void> | 异步开始视频录制方法的Promise返回值。 | 3361 3362**错误码：** 3363 3364以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3365 3366| 错误码ID | 错误信息 | 3367| -------- | -------------------------------------- | 3368| 5400102 | Operate not permit. Return by promise. | 3369| 5400103 | IO error. Return by promise. | 3370| 5400105 | Service died. Return by promise. | 3371 3372**示例：** 3373 3374```ts 3375import { BusinessError } from '@kit.BasicServicesKit'; 3376 3377avRecorder.start().then(() => { 3378 console.info('Succeeded in starting AVRecorder'); 3379}).catch((err: BusinessError) => { 3380 console.error('Failed to start AVRecorder and catch error is ' + err.message); 3381}); 3382``` 3383 3384### pause<sup>9+</sup> 3385 3386pause(callback: AsyncCallback\<void>): void 3387 3388异步方式暂停视频录制。通过注册回调函数获取返回值。 3389 3390需要[start()](#start9)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume9)接口来恢复录制。 3391 3392**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3393 3394**参数：** 3395 3396| 参数名 | 类型 | 必填 | 说明 | 3397| -------- | -------------------- | ---- | --------------------------- | 3398| callback | AsyncCallback\<void> | 是 | 回调函数。当暂停视频录制成功，err为undefined，否则为错误对象。 | 3399 3400**错误码：** 3401 3402以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3403 3404| 错误码ID | 错误信息 | 3405| -------- | --------------------------------------- | 3406| 5400102 | Operate not permit. Return by callback. | 3407| 5400103 | IO error. Return by callback. | 3408| 5400105 | Service died. Return by callback. | 3409 3410**示例：** 3411 3412```ts 3413import { BusinessError } from '@kit.BasicServicesKit'; 3414 3415avRecorder.pause((err: BusinessError) => { 3416 if (err) { 3417 console.error('Failed to pause AVRecorder and error is ' + err.message); 3418 } else { 3419 console.info('Succeeded in pausing'); 3420 } 3421}); 3422``` 3423 3424### pause<sup>9+</sup> 3425 3426pause(): Promise\<void> 3427 3428异步方式暂停视频录制。通过Promise获取返回值。 3429 3430需要[start()](#start9-1)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume9-1)接口来恢复录制。 3431 3432**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3433 3434**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3435 3436**返回值：** 3437 3438| 类型 | 说明 | 3439| -------------- | ------------------------------------- | 3440| Promise\<void> | 异步暂停视频录制方法的Promise返回值。 | 3441 3442**错误码：** 3443 3444以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3445 3446| 错误码ID | 错误信息 | 3447| -------- | -------------------------------------- | 3448| 5400102 | Operate not permit. Return by promise. | 3449| 5400103 | IO error. Return by promise. | 3450| 5400105 | Service died. Return by promise. | 3451 3452**示例：** 3453 3454```ts 3455import { BusinessError } from '@kit.BasicServicesKit'; 3456 3457avRecorder.pause().then(() => { 3458 console.info('Succeeded in pausing'); 3459}).catch((err: BusinessError) => { 3460 console.error('Failed to pause AVRecorder and catch error is ' + err.message); 3461}); 3462``` 3463 3464### resume<sup>9+</sup> 3465 3466resume(callback: AsyncCallback\<void>): void 3467 3468异步方式恢复视频录制。通过注册回调函数获取返回值。 3469 3470需要在[pause()](#pause9-2)事件成功触发后，才能调用resume方法。 3471 3472**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3473 3474**参数：** 3475 3476| 参数名 | 类型 | 必填 | 说明 | 3477| -------- | -------------------- | ---- | ---------------------------- | 3478| callback | AsyncCallback\<void> | 是 | 回调函数。当恢复视频录制成功，err为undefined，否则为错误对象。 | 3479 3480**错误码：** 3481 3482以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3483 3484| 错误码ID | 错误信息 | 3485| -------- | --------------------------------------- | 3486| 5400102 | Operate not permit. Return by callback. | 3487| 5400103 | IO error. Return by callback. | 3488| 5400105 | Service died. Return by callback. | 3489 3490**示例：** 3491 3492```ts 3493import { BusinessError } from '@kit.BasicServicesKit'; 3494 3495avRecorder.resume((err: BusinessError) => { 3496 if (err) { 3497 console.error('Failed to resume AVRecorder and error is ' + err.message); 3498 } else { 3499 console.info('Succeeded in resuming AVRecorder'); 3500 } 3501}); 3502``` 3503 3504### resume<sup>9+</sup> 3505 3506resume(): Promise\<void> 3507 3508异步方式恢复视频录制。通过Promise获取返回值。 3509 3510需要在[pause()](#pause9-3)事件成功触发后，才能调用resume方法。 3511 3512**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3513 3514**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3515 3516**返回值：** 3517 3518| 类型 | 说明 | 3519| -------------- | ------------------------------------- | 3520| Promise\<void> | 异步恢复视频录制方法的Promise返回值。 | 3521 3522**错误码：** 3523 3524以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3525 3526| 错误码ID | 错误信息 | 3527| -------- | -------------------------------------- | 3528| 5400102 | Operate not permit. Return by promise. | 3529| 5400103 | IO error. Return by promise. | 3530| 5400105 | Service died. Return by promise. | 3531 3532**示例：** 3533 3534```ts 3535import { BusinessError } from '@kit.BasicServicesKit'; 3536 3537avRecorder.resume().then(() => { 3538 console.info('Succeeded in resuming AVRecorder'); 3539}).catch((err: BusinessError) => { 3540 console.error('Failed to resume AVRecorder failed and catch error is ' + err.message); 3541}); 3542``` 3543 3544### stop<sup>9+</sup> 3545 3546stop(callback: AsyncCallback\<void>): void 3547 3548异步方式停止视频录制。通过注册回调函数获取返回值。 3549 3550需要在[start()](#start9)或[pause()](#pause9-2)事件成功触发后，才能调用stop方法。 3551 3552纯音频录制时，需要重新调用[prepare()](#prepare9-2)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-2)和[getInputSurface()](#getinputsurface9)接口才能重新录制。 3553 3554**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3555 3556**参数：** 3557 3558| 参数名 | 类型 | 必填 | 说明 | 3559| -------- | -------------------- | ---- | ---------------------------- | 3560| callback | AsyncCallback\<void> | 是 | 回调函数。当停止视频录制成功，err为undefined，否则为错误对象。 | 3561 3562**错误码：** 3563 3564以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3565 3566| 错误码ID | 错误信息 | 3567| -------- | --------------------------------------- | 3568| 5400102 | Operate not permit. Return by callback. | 3569| 5400103 | IO error. Return by callback. | 3570| 5400105 | Service died. Return by callback. | 3571 3572**示例：** 3573 3574```ts 3575import { BusinessError } from '@kit.BasicServicesKit'; 3576 3577avRecorder.stop((err: BusinessError) => { 3578 if (err) { 3579 console.error('Failed to stop AVRecorder and error is ' + err.message); 3580 } else { 3581 console.info('Succeeded in stopping AVRecorder'); 3582 } 3583}); 3584``` 3585 3586### stop<sup>9+</sup> 3587 3588stop(): Promise\<void> 3589 3590异步方式停止视频录制。通过Promise获取返回值。 3591 3592需要在[start()](#start9-1)或[pause()](#pause9-3)事件成功触发后，才能调用stop方法。 3593 3594纯音频录制时，需要重新调用[prepare()](#prepare9-3)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-3)和[getInputSurface()](#getinputsurface9-1)接口才能重新录制。 3595 3596**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3597 3598**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3599 3600**返回值：** 3601 3602| 类型 | 说明 | 3603| -------------- | ------------------------------------- | 3604| Promise\<void> | 异步停止视频录制方法的Promise返回值。 | 3605 3606**错误码：** 3607 3608以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3609 3610| 错误码ID | 错误信息 | 3611| -------- | -------------------------------------- | 3612| 5400102 | Operate not permit. Return by promise. | 3613| 5400103 | IO error. Return by promise. | 3614| 5400105 | Service died. Return by promise. | 3615 3616**示例：** 3617 3618```ts 3619import { BusinessError } from '@kit.BasicServicesKit'; 3620 3621avRecorder.stop().then(() => { 3622 console.info('Succeeded in stopping AVRecorder'); 3623}).catch((err: BusinessError) => { 3624 console.error('Failed to stop AVRecorder and catch error is ' + err.message); 3625}); 3626``` 3627 3628### reset<sup>9+</sup> 3629 3630reset(callback: AsyncCallback\<void>): void 3631 3632异步方式重置音视频录制。通过注册回调函数获取返回值。 3633 3634纯音频录制时，需要重新调用[prepare()](#prepare9-2)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-2)和[getInputSurface()](#getinputsurface9)接口才能重新录制。 3635 3636**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3637 3638**参数：** 3639 3640| 参数名 | 类型 | 必填 | 说明 | 3641| -------- | -------------------- | ---- | ------------------------------ | 3642| callback | AsyncCallback\<void> | 是 | 回调函数。当重置音视频录制成功，err为undefined，否则为错误对象。 | 3643 3644**错误码：** 3645 3646以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3647 3648| 错误码ID | 错误信息 | 3649| -------- | --------------------------------- | 3650| 5400103 | IO error. Return by callback. | 3651| 5400105 | Service died. Return by callback. | 3652 3653**示例：** 3654 3655```ts 3656import { BusinessError } from '@kit.BasicServicesKit'; 3657 3658avRecorder.reset((err: BusinessError) => { 3659 if (err) { 3660 console.error('Failed to reset AVRecorder and error is ' + err.message); 3661 } else { 3662 console.info('Succeeded in resetting AVRecorder'); 3663 } 3664}); 3665``` 3666 3667### reset<sup>9+</sup> 3668 3669reset(): Promise\<void> 3670 3671异步方式重置音视频录制。通过Promise获取返回值。 3672 3673纯音频录制时，需要重新调用[prepare()](#prepare9-3)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-3)和[getInputSurface()](#getinputsurface9-1)接口才能重新录制。 3674 3675**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3676 3677**返回值：** 3678 3679| 类型 | 说明 | 3680| -------------- | --------------------------------------- | 3681| Promise\<void> | 异步重置音视频录制方法的Promise返回值。 | 3682 3683**错误码：** 3684 3685以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3686 3687| 错误码ID | 错误信息 | 3688| -------- | -------------------------------- | 3689| 5400103 | IO error. Return by promise. | 3690| 5400105 | Service died. Return by promise. | 3691 3692**示例：** 3693 3694```ts 3695import { BusinessError } from '@kit.BasicServicesKit'; 3696 3697avRecorder.reset().then(() => { 3698 console.info('Succeeded in resetting AVRecorder'); 3699}).catch((err: BusinessError) => { 3700 console.error('Failed to reset and catch error is ' + err.message); 3701}); 3702``` 3703 3704### release<sup>9+</sup> 3705 3706release(callback: AsyncCallback\<void>): void 3707 3708异步方式释放音视频录制资源。通过注册回调函数获取返回值。 3709 3710释放音视频录制资源之后，该AVRecorder实例不能再进行任何操作。 3711 3712**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3713 3714**参数：** 3715 3716| 参数名 | 类型 | 必填 | 说明 | 3717| -------- | -------------------- | ---- | ---------------------------------- | 3718| callback | AsyncCallback\<void> | 是 | 回调函数。当释放音视频录制资源成功，err为undefined，否则为错误对象。 | 3719 3720**错误码：** 3721 3722以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3723 3724| 错误码ID | 错误信息 | 3725| -------- | --------------------------------- | 3726| 5400105 | Service died. Return by callback. | 3727 3728**示例：** 3729 3730```ts 3731import { BusinessError } from '@kit.BasicServicesKit'; 3732 3733avRecorder.release((err: BusinessError) => { 3734 if (err) { 3735 console.error('Failed to release AVRecorder and error is ' + err.message); 3736 } else { 3737 console.info('Succeeded in releasing AVRecorder'); 3738 } 3739}); 3740``` 3741 3742### release<sup>9+</sup> 3743 3744release(): Promise\<void> 3745 3746异步方式释放音视频录制资源。通过Promise获取返回值。 3747 3748释放音视频录制资源之后，该AVRecorder实例不能再进行任何操作。 3749 3750**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3751 3752**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3753 3754**返回值：** 3755 3756| 类型 | 说明 | 3757| -------------- | ------------------------------------------- | 3758| Promise\<void> | 异步释放音视频录制资源方法的Promise返回值。 | 3759 3760**错误码：** 3761 3762以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3763 3764| 错误码ID | 错误信息 | 3765| -------- | --------------------------------- | 3766| 5400105 | Service died. Return by callback. | 3767 3768**示例：** 3769 3770```ts 3771import { BusinessError } from '@kit.BasicServicesKit'; 3772 3773avRecorder.release().then(() => { 3774 console.info('Succeeded in releasing AVRecorder'); 3775}).catch((err: BusinessError) => { 3776 console.error('Failed to release AVRecorder and catch error is ' + err.message); 3777}); 3778``` 3779 3780### getCurrentAudioCapturerInfo<sup>11+</sup> 3781 3782getCurrentAudioCapturerInfo(callback: AsyncCallback\<audio.AudioCapturerChangeInfo>): void 3783 3784异步方式获取当前音频采集参数。通过注册回调函数获取返回值。 3785 3786在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 3787 3788**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3789 3790**参数**： 3791 3792| 参数名 | 类型 | 必填 | 说明 | 3793| -------- | ------------------------------------------------------------ | ---- | ------------------------------------ | 3794| callback | AsyncCallback\<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 是 | 回调函数。当获取音频采集参数成功时，err为undefined，data为获取到的audio.AudioCapturerChangeInfo，否则为错误对象。 | 3795 3796**错误码**： 3797 3798以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3799 3800| 错误码ID | 错误信息 | 3801| -------- | ------------------------------------------ | 3802| 5400102 | Operation not allowed. | 3803| 5400103 | I/O error. | 3804| 5400105 | Service died. Return by callback. | 3805 3806**示例**： 3807 3808```ts 3809import { audio } from '@kit.AudioKit'; 3810 3811let currentCapturerInfo: audio.AudioCapturerChangeInfo; 3812 3813avRecorder.getCurrentAudioCapturerInfo((err: BusinessError, capturerInfo: audio.AudioCapturerChangeInfo) => { 3814 if (err) { 3815 console.error('Failed to get CurrentAudioCapturerInfo and error is ' + err.message); 3816 } else { 3817 console.info('Succeeded in getting CurrentAudioCapturerInfo'); 3818 currentCapturerInfo = capturerInfo; 3819 } 3820}); 3821``` 3822 3823### getCurrentAudioCapturerInfo<sup>11+</sup> 3824 3825getCurrentAudioCapturerInfo(): Promise\<audio.AudioCapturerChangeInfo> 3826 3827异步方式获取当前音频采集参数。通过Promise获取返回值。 3828 3829在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 3830 3831**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3832 3833**返回值**： 3834 3835| 类型 | 说明 | 3836| ------------------------------------------------------------ | ------------------------------------------------- | 3837| Promise\<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | Promise对象，返回获取的当前音频采集参数。 | 3838 3839**错误码**： 3840 3841以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3842 3843| 错误码ID | 错误信息 | 3844| -------- | -------------------------------- | 3845| 5400102 | Operation not allowed. | 3846| 5400103 | I/O error. | 3847| 5400105 | Service died. Return by promise. | 3848 3849**示例**： 3850 3851```ts 3852import { audio } from '@kit.AudioKit'; 3853 3854let currentCapturerInfo: audio.AudioCapturerChangeInfo; 3855 3856avRecorder.getCurrentAudioCapturerInfo().then((capturerInfo: audio.AudioCapturerChangeInfo) => { 3857 console.info('Succeeded in getting CurrentAudioCapturerInfo'); 3858 currentCapturerInfo = capturerInfo; 3859}).catch((err: BusinessError) => { 3860 console.error('Failed to get CurrentAudioCapturerInfo and catch error is ' + err.message); 3861}); 3862``` 3863 3864### getAudioCapturerMaxAmplitude<sup>11+</sup> 3865 3866getAudioCapturerMaxAmplitude(callback: AsyncCallback\<number>): void 3867 3868异步方式获取当前音频最大振幅。通过注册回调函数获取返回值。 3869 3870在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 3871 3872调用接口时，获取到的返回值是上一次获取最大振幅的时刻到当前这段区间内的音频最大振幅。即，如果在1s的时刻获取了一次最大振幅，在2s时再获取到的最大振幅时1-2s这个区间里面的最大值。 3873 3874**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3875 3876**参数**： 3877 3878| 参数名 | 类型 | 必填 | 说明 | 3879| -------- | ---------------------- | ---- | ------------------------------------ | 3880| callback | AsyncCallback\<number> | 是 | 回调函数。获取当前音频最大振幅成功时，err为undefined，data为获取到的最大振幅，否则为错误对象。 | 3881 3882**错误码**： 3883 3884以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3885 3886| 错误码ID | 错误信息 | 3887| -------- | ------------------------------------------ | 3888| 5400102 | Operation not allowed. | 3889| 5400105 | Service died. Return by callback. | 3890 3891**示例**： 3892 3893```ts 3894let maxAmplitude: number; 3895 3896avRecorder.getAudioCapturerMaxAmplitude((err: BusinessError, amplitude: number) => { 3897 if (err) { 3898 console.error('Failed to get AudioCapturerMaxAmplitude and error is ' + err.message); 3899 } else { 3900 console.info('Succeeded in getting AudioCapturerMaxAmplitude'); 3901 maxAmplitude = amplitude; 3902 } 3903}); 3904``` 3905 3906### getAudioCapturerMaxAmplitude<sup>11+</sup> 3907 3908getAudioCapturerMaxAmplitude(): Promise\<number> 3909 3910异步方式获取当前音频最大振幅参数。通过Promise获取返回值。 3911 3912在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 3913 3914调用接口时，获取到的返回值是上一次获取最大振幅的时刻到当前这段区间内的音频最大振幅。即，如果在1s的时刻获取了一次最大振幅，在2s时再获取到的最大振幅时1-2s这个区间里面的最大值。 3915 3916**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3917 3918**返回值**： 3919 3920| 类型 | 说明 | 3921| ---------------- | ------------------------------------------------- | 3922| Promise\<number> | Promise对象，返回获取的当前音频最大振幅。 | 3923 3924**错误码**： 3925 3926以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3927 3928| 错误码ID | 错误信息 | 3929| -------- | -------------------------------- | 3930| 5400102 | Operation not allowed. | 3931| 5400105 | Service died. Return by promise. | 3932 3933**示例**： 3934 3935```ts 3936let maxAmplitude: number; 3937 3938avRecorder.getAudioCapturerMaxAmplitude().then((amplitude: number) => { 3939 console.info('Succeeded in getting AudioCapturerMaxAmplitude'); 3940 maxAmplitude = amplitude; 3941}).catch((err: BusinessError) => { 3942 console.error('Failed to get AudioCapturerMaxAmplitude and catch error is ' + err.message); 3943}); 3944``` 3945 3946### getAvailableEncoder<sup>11+</sup> 3947 3948getAvailableEncoder(callback: AsyncCallback\<Array\<EncoderInfo>>): void 3949 3950异步方式获取可用的编码器参数。通过注册回调函数获取返回值。 3951 3952**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3953 3954**参数**： 3955 3956| 参数名 | 类型 | 必填 | 说明 | 3957| -------- | ----------------------------------------------------- | ---- | ------------------------------------ | 3958| callback | AsyncCallback\<Array\<[EncoderInfo](#encoderinfo11)>> | 是 | 回调函数。获取可用的编码器参数成功时，err为undefined，data为获取到的编码器参数，否则为错误对象。 | 3959 3960**错误码**： 3961 3962以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3963 3964| 错误码ID | 错误信息 | 3965| -------- | ------------------------------------------ | 3966| 5400102 | Operation not allowed. | 3967| 5400105 | Service died. Return by callback. | 3968 3969**示例**： 3970 3971```ts 3972let encoderInfo: media.EncoderInfo; 3973 3974avRecorder.getAvailableEncoder((err: BusinessError, info: media.EncoderInfo[]) => { 3975 if (err) { 3976 console.error('Failed to get AvailableEncoder and error is ' + err.message); 3977 } else { 3978 console.info('Succeeded in getting AvailableEncoder'); 3979 encoderInfo = info[0]; 3980 } 3981}); 3982``` 3983 3984### getAvailableEncoder<sup>11+</sup> 3985 3986getAvailableEncoder(): Promise\<Array\<EncoderInfo>> 3987 3988异步方式获取可用的编码器参数。通过注册回调函数获取返回值。 3989 3990**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3991 3992**返回值**： 3993 3994| 类型 | 说明 | 3995| ----------------------------------------------- | ----------------------------------------------- | 3996| Promise\<Array\<[EncoderInfo](#encoderinfo11)>> | Promise对象，返回获取的可用的编码器参数。 | 3997 3998**错误码**： 3999 4000以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4001 4002| 错误码ID | 错误信息 | 4003| -------- | -------------------------------- | 4004| 5400102 | Operation not allowed. | 4005| 5400105 | Service died. Return by promise. | 4006 4007**示例**： 4008 4009```ts 4010let encoderInfo: media.EncoderInfo; 4011 4012avRecorder.getAvailableEncoder().then((info: media.EncoderInfo[]) => { 4013 console.info('Succeeded in getting AvailableEncoder'); 4014 encoderInfo = info[0]; 4015}).catch((err: BusinessError) => { 4016 console.error('Failed to get AvailableEncoder and catch error is ' + err.message); 4017}); 4018``` 4019 4020### getAVRecorderConfig<sup>11+</sup> 4021 4022getAVRecorderConfig(callback: AsyncCallback\<AVRecorderConfig>): void 4023 4024异步方式获取实时的配置参数。通过注册回调函数获取返回值。 4025 4026只能在[prepare()](#prepare9-2)接口调用后调用。 4027 4028**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4029 4030**参数：** 4031 4032| 参数名 | 类型 | 必填 | 说明 | 4033| -------- | ---------------------- | ---- | --------------------------- | 4034| callback | AsyncCallback\<[AVRecorderConfig](#avrecorderconfig9)> | 是 | 回调函数。获取实时配置的参数成功时，err为undefined，data为获取到的配置参数，否则为错误对象。 | 4035 4036**错误码：** 4037 4038以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 4039 4040| 错误码ID | 错误信息 | 4041| -------- | ------------------------------------------ | 4042| 5400102 | Operate not permit. Return by callback. | 4043| 5400103 | IO error. Return by callback. | 4044| 5400105 | Service died. Return by callback. | 4045 4046**示例：** 4047 4048```ts 4049import { BusinessError } from '@kit.BasicServicesKit'; 4050 4051let avConfig: media.AVRecorderConfig; 4052 4053avRecorder.getAVRecorderConfig((err: BusinessError, config: media.AVRecorderConfig) => { 4054 if (err) { 4055 console.error('Failed to get avConfig and error is ' + err.message); 4056 } else { 4057 console.info('Succeeded in getting AVRecorderConfig'); 4058 avConfig = config; 4059 } 4060}); 4061``` 4062 4063### getAVRecorderConfig<sup>11+</sup> 4064 4065getAVRecorderConfig(): Promise\<AVRecorderConfig>; 4066 4067异步方式获取实时的配置参数。通过Promise获取返回值。 4068 4069只能在[prepare()](#prepare9-3)接口调用后调用。 4070 4071**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4072 4073**返回值：** 4074 4075| 类型 | 说明 | 4076| ---------------- | -------------------------------- | 4077| Promise\<[AVRecorderConfig](#avrecorderconfig9)> | 异步获得实时配置参数的回调方法。 | 4078 4079**错误码：** 4080 4081以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 4082 4083| 错误码ID | 错误信息 | 4084| -------- | ----------------------------------------- | 4085| 5400102 | Operate not permit. Return by promise. | 4086| 5400103 | IO error. Return by promise. | 4087| 5400105 | Service died. Return by promise. | 4088 4089**示例：** 4090 4091```ts 4092import { BusinessError } from '@kit.BasicServicesKit'; 4093 4094let avConfig: media.AVRecorderConfig; 4095 4096avRecorder.getAVRecorderConfig().then((config: media.AVRecorderConfig) => { 4097 console.info('Succeeded in getting AVRecorderConfig'); 4098 avConfig = config; 4099}).catch((err: BusinessError) => { 4100 console.error('Failed to get AVRecorderConfig and catch error is ' + err.message); 4101}); 4102``` 4103 4104### on('stateChange')<sup>9+</sup> 4105 4106on(type: 'stateChange', callback: OnAVRecorderStateChangeHandler): void 4107 4108订阅录制状态机AVRecorderState切换的事件，当 AVRecorderState状态机发生变化时，会通过订阅的回调方法通知用户。用户只能订阅一个状态机切换事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 4109 4110**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4111 4112**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4113 4114**参数：** 4115 4116| 参数名 | 类型 | 必填 | 说明 | 4117| -------- | -------- | ---- | ------------------------------------------------------------ | 4118| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 4119| callback | [OnAVRecorderStateChangeHandler](#onavrecorderstatechangehandler12) | 是 | 状态机切换事件回调方法。 | 4120 4121**错误码：** 4122 4123以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4124 4125| 错误码ID | 错误信息 | 4126| -------- | --------------------------------- | 4127| 5400103 | IO error. Return by callback. | 4128| 5400105 | Service died. Return by callback. | 4129 4130**示例：** 4131 4132```ts 4133avRecorder.on('stateChange', async (state: media.AVRecorderState, reason: media.StateChangeReason) => { 4134 console.info('case state has changed, new state is :' + state + ',and new reason is : ' + reason); 4135}); 4136``` 4137 4138### off('stateChange')<sup>9+</sup> 4139 4140off(type: 'stateChange', callback?: OnAVRecorderStateChangeHandler): void 4141 4142取消订阅播放状态机[AVRecorderState](#avrecorderstate9)切换的事件。 4143 4144**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4145 4146**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4147 4148**参数：** 4149 4150| 参数名 | 类型 | 必填 | 说明 | 4151| ------ | ------ | ---- | ------------------------------------------------------------ | 4152| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 4153| callback | [OnAVRecorderStateChangeHandler](#onavrecorderstatechangehandler12) | 否 | 状态机切换事件回调方法。<br/>从API version 12开始支持此参数。 | 4154 4155**示例：** 4156 4157```ts 4158avRecorder.off('stateChange'); 4159``` 4160 4161### on('error')<sup>9+</sup> 4162 4163on(type: 'error', callback: ErrorCallback): void 4164 4165订阅AVRecorder的错误事件，该事件仅用于错误提示，不需要用户停止播控动作。如果此时[AVRecorderState](#avrecorderstate9)也切至error状态，用户需要通过[reset()](#reset9-2)或者[release()](#release9-2)退出录制操作。 4166 4167用户只能订阅一个错误事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 4168 4169**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4170 4171**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4172 4173**参数：** 4174 4175| 参数名 | 类型 | 必填 | 说明 | 4176| -------- | ------------- | ---- | ------------------------------------------------------------ | 4177| type | string | 是 | 录制错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 4178| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录制错误事件回调方法。 | 4179 4180**错误码：** 4181 4182以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4183 4184| 错误码ID | 错误信息 | 4185| -------- | ------------------------------------------ | 4186| 201 | Permission denied. | 4187| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 4188| 801 | Capability not supported. | 4189| 5400101 | No memory. | 4190| 5400102 | Operation not allowed. | 4191| 5400103 | I/O error. | 4192| 5400104 | Time out. | 4193| 5400105 | Service died. | 4194| 5400106 | Unsupported format. | 4195| 5400107 | Audio interrupted. | 4196 4197**示例：** 4198 4199```ts 4200import { BusinessError } from '@kit.BasicServicesKit'; 4201 4202avRecorder.on('error', (err: BusinessError) => { 4203 console.info('case avRecorder.on(error) called, errMessage is ' + err.message); 4204}); 4205``` 4206 4207### off('error')<sup>9+</sup> 4208 4209off(type: 'error', callback?: ErrorCallback): void 4210 4211取消订阅录制错误事件，取消后不再接收到AVRecorder的错误事件。 4212 4213**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4214 4215**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4216 4217**参数：** 4218 4219| 参数名 | 类型 | 必填 | 说明 | 4220| ------ | ------ | ---- | ------------------------------------------------------------ | 4221| type | string | 是 | 录制错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 4222| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 录制错误事件回调方法。<br/>从API version 12开始支持此参数。 | 4223 4224**示例：** 4225 4226```ts 4227avRecorder.off('error'); 4228``` 4229 4230### on('audioCapturerChange')<sup>11+</sup> 4231 4232on(type: 'audioCapturerChange', callback: Callback<audio.AudioCapturerChangeInfo>): void 4233 4234订阅录音配置变化的回调，任意录音配置的变化会触发变化后的录音配置全量信息回调。 4235 4236当用户重复订阅时，以最后一次订阅的回调接口为准。 4237 4238**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4239 4240**参数：** 4241 4242| 参数名 | 类型 | 必填 | 说明 | 4243| -------- | -------- | ---- | ------------------------------------------------------------ | 4244| type | string | 是 |录音配置变化的回调类型，支持的事件：'audioCapturerChange'。 | 4245| callback | Callback<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 是 | 变化后的录音配置全量信息。| 4246 4247**错误码：** 4248 4249| 错误码ID | 错误信息 | 4250| -------- | ------------------------------------------ | 4251| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 4252 4253**示例：** 4254 4255```ts 4256import { audio } from '@kit.AudioKit' 4257 4258let capturerChangeInfo: audio.AudioCapturerChangeInfo; 4259 4260avRecorder.on('audioCapturerChange', (audioCapturerChangeInfo: audio.AudioCapturerChangeInfo) => { 4261 console.info('audioCapturerChange called'); 4262 capturerChangeInfo = audioCapturerChangeInfo; 4263}); 4264``` 4265 4266### off('audioCapturerChange')<sup>11+</sup> 4267 4268off(type: 'audioCapturerChange', callback?: Callback<audio.AudioCapturerChangeInfo>): void 4269 4270取消订阅录音变化的回调事件。 4271 4272**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4273 4274**参数：** 4275 4276| 参数名 | 类型 | 必填 | 说明 | 4277| ------ | ------ | ---- | ------------------------------------------------------------ | 4278| type | string | 是 | 录音配置变化的回调类型，支持的事件：'audioCapturerChange'。 | 4279| callback | Callback<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 否 | 变化后的录音配置全量信息。<br/>从API version 12开始支持此参数。| 4280 4281**示例：** 4282 4283```ts 4284avRecorder.off('audioCapturerChange'); 4285``` 4286 4287### on('photoAssetAvailable')<sup>12+</sup> 4288 4289on(type: 'photoAssetAvailable', callback: Callback\<photoAccessHelper.PhotoAsset>): void 4290 4291订阅媒体资源回调事件，当[FileGenerationMode](#filegenerationmode12)枚举设置为系统创建媒体文件时，会在[stop](#stop9-2)操作结束后把[PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)对象回调给应用。 4292 4293当用户重复订阅时，以最后一次订阅的回调接口为准。 4294 4295**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4296 4297**参数：** 4298 4299| 参数名 | 类型 | 必填 | 说明 | 4300| -------- | -------- | ---- | ------------------------------------------------------------ | 4301| type | string | 是 |录像资源的回调类型，支持的事件：'photoAssetAvailable'。 | 4302| callback | Callback<[photoAccessHelper.PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)> | 是 | 系统创建的资源文件对应的PhotoAsset对象| 4303 4304**错误码：** 4305 4306| 错误码ID | 错误信息 | 4307| -------- | ------------------------------------------ | 4308| 5400103 | IO error. Return by callback. | 4309| 5400105 | Service died. Return by callback. | 4310 4311**示例：** 4312 4313```ts 4314import { photoAccessHelper } from '@kit.MediaLibraryKit'; 4315import { common } from '@kit.AbilityKit' 4316let photoAsset: photoAccessHelper.PhotoAsset; 4317let context = getContext(this) as common.UIAbilityContext 4318 4319// 例:处理photoAsset回调，保存video 4320async function saveVideo(asset: photoAccessHelper.PhotoAsset) { 4321 console.info("saveVideo called"); 4322 try { 4323 let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context); 4324 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset); 4325 assetChangeRequest.saveCameraPhoto(); 4326 await phAccessHelper.applyChanges(assetChangeRequest); 4327 console.info('apply saveVideo successfully'); 4328 } catch (err) { 4329 console.error(`apply saveVideo failed with error: ${err.code}, ${err.message}`); 4330 } 4331} 4332// 注册photoAsset监听 4333avRecorder.on('photoAssetAvailable', (asset: photoAccessHelper.PhotoAsset) => { 4334 console.info('photoAssetAvailable called'); 4335 if (asset != undefined) { 4336 photoAsset = asset; 4337 // 处理photoAsset回调 4338 // 例: this.saveVideo(asset); 4339 } else { 4340 console.error('photoAsset is undefined'); 4341 } 4342}); 4343``` 4344 4345### off('photoAssetAvailable')<sup>12+</sup> 4346 4347off(type: 'photoAssetAvailable', callback?: Callback<photoAccessHelper.PhotoAsset>): void 4348 4349取消订阅媒体资源的回调类型。 4350 4351**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4352 4353**参数：** 4354 4355| 参数名 | 类型 | 必填 | 说明 | 4356| ------ | ------ | ---- | ------------------------------------------------------------ | 4357| type | string | 是 | 录音配置变化的回调类型，支持的事件：'photoAssetAvailable'。 | 4358 4359**示例：** 4360 4361```ts 4362avRecorder.off('photoAssetAvailable'); 4363``` 4364 4365## AVRecorderState<sup>9+</sup> 4366 4367type AVRecorderState = 'idle' | 'prepared' | 'started' | 'paused' | 'stopped' | 'released' | 'error' 4368 4369音视频录制的状态机。可通过state属性获取当前状态。 4370 4371**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 4372 4373**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4374 4375| 类型 | 说明 | 4376| -------- | ------------------------------------------------------------ | 4377| 'idle' | 闲置状态。此时可以调用[AVRecorder.prepare()](#prepare9-2)方法设置录制参数，进入prepared状态。AVRecorder刚被创建，或者在任何非released状态下调用[AVRecorder.reset()](#reset9-2)方法，均进入idle状态。 | 4378| 'prepared' | 参数设置完成。此时可以调用[AVRecorder.start()](#start9)方法开始录制，进入started状态。 | 4379| 'started' | 正在录制。此时可以调用[AVRecorder.pause()](#pause9-2)方法暂停录制，进入paused状态。也可以调用[AVRecorder.stop()](#stop9-2)方法结束录制，进入stopped状态。 | 4380| 'paused' | 录制暂停。此时可以调用[AVRecorder.resume()](#resume9)方法继续录制，进入started状态。也可以调用[AVRecorder.stop()](#stop9-2)方法结束录制，进入stopped状态。 | 4381| 'stopped' | 录制停止。此时可以调用[AVRecorder.prepare()](#prepare9-2)方法设置录制参数，重新进入prepared状态。 | 4382| 'released' | 录制资源释放。此时不能再进行任何操作。在任何其他状态下，均可以通过调用[AVRecorder.release()](#release9-2)方法进入released状态。 | 4383| 'error' | 错误状态。当AVRecorder实例发生不可逆错误，会转换至当前状态。切换至error状态时会伴随[AVRecorder.on('error')事件](#onerror9-1)，该事件会上报详细错误原因。在error状态时，用户需要调用[AVRecorder.reset()](#reset9-2)方法重置AVRecorder实例，或者调用[AVRecorder.release()](#release9-2)方法释放资源。 | 4384 4385## OnAVRecorderStateChangeHandler<sup>12+</sup> 4386 4387type OnAVRecorderStateChangeHandler = (state: AVRecorderState, reason: StateChangeReason) => void 4388 4389状态机切换事件回调方法。 4390 4391**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4392 4393**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 4394 4395| 参数名 | 类型 | 必填 | 说明 | 4396| ------ | ------ | ------ | ------------------------------------------------------------ | 4397| state | [AVRecorderState](#avrecorderstate9) | 必填 | 当前播放状态。 | 4398| reason | [StateChangeReason](#statechangereason9) | 必填 | 当前播放状态的切换原因。 | 4399 4400## AVRecorderConfig<sup>9+</sup> 4401 4402表示音视频录制的参数设置。 4403 4404通过audioSourceType和videoSourceType区分纯音频录制、纯视频录制或音视频录制。纯音频录制时，仅需要设置audioSourceType；纯视频录制时，仅需要设置videoSourceType；音视频录制时，audioSourceType和videoSourceType均需要设置。 4405 4406**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4407 4408| 名称 | 类型 | 必填 | 说明 | 4409| --------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 4410| audioSourceType | [AudioSourceType](#audiosourcetype9) | 否 | 选择录制的音频源类型。选择音频录制时必填。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4411| videoSourceType | [VideoSourceType](#videosourcetype9) | 否 | 选择录制的视频源类型。选择视频录制时必填。 | 4412| profile | [AVRecorderProfile](#avrecorderprofile9) | 是 | 录制的profile，必要参数。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4413| url | string | 是 | 录制输出URL：fd://xx (fd number) ，必要参数。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4414|fileGenerationMode<sup>12+</sup> | [FileGenerationMode](#filegenerationmode12) | 否 | 创建媒体文件的模式，配合[on('photoAssetAvailable')](#onphotoassetavailable12)监听使用。| 4415| rotation<sup>(deprecated)</sup> | number | 否 | 录制的视频旋转角度，mp4格式支持0，90，180，270，默认值为0。<br>从API version 6开始支持，从API version 12开始废弃。建议使用[AVMetadata](#avmetadata11).videoOrientation替代。如果同时设置两个值，将会采用[AVMetadata](#avmetadata11).videoOrientation。 | 4416| location<sup>(deprecated)</sup> | [Location](#location) | 否 | 录制的地理位置，默认不记录地理位置信息。<br>从API version 6开始支持，从API version 12开始废弃。建议使用 [AVMetadata](#avmetadata11).location。如果同时设置两个值，将会采用[AVMetadata](#avmetadata11).location。 | 4417| metadata<sup>12+</sup> | [AVMetadata](#avmetadata11) | 否 | 设置元数据信息。详情见 [AVMetadata](#avmetadata11)。 | 4418 4419## AVRecorderProfile<sup>9+</sup> 4420 4421音视频录制的配置文件。 4422 4423**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4424 4425| 名称 | 类型 | 必填 | 说明 | 4426| ---------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 4427| audioBitrate | number | 否 | 音频编码比特率，选择音频录制时必填。<br>支持范围：<br>- AAC编码格式支持比特率范围[32000 - 500000]。<br>- G711-mulaw编码格式支持比特率范围[64000 - 64000]。<br>- MP3编码格式支持范围[8000, 16000, 32000, 40000, 48000, 56000, 64000, 80000, 96000, 112000, 128000, 160000, 192000, 224000, 256000, 320000]。<br>当使用MP3编码格式时，采样率和比特率的映射关系： <br>- 采样率使用16K以下时，对应比特率范围为[8kbps - 64kbps]。<br>- 采样率使用16K~32K时对应的比特率范围为[8kbps - 160kbps]。<br>- 采样率使用32K以上时对应的比特率范围为[32kbps - 320kbps]。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4428| audioChannels | number | 否 | 音频采集声道数，选择音频录制时必填。<br>- AAC编码格式支持范围[1 - 8]。<br>- G711-mulaw编码格式支持范围[1 - 1]。<br>- MP3编码格式支持范围[1 - 2]。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4429| audioCodec | [CodecMimeType](#codecmimetype8) | 否 | 音频编码格式，选择音频录制时必填。当前支持AUDIO_AAC，AUDIO_MP3，AUDIO_G711MU。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4430| audioSampleRate | number | 否 | 音频采样率，选择音频录制时必填。<br>支持范围：<br>- AAC编码支持采样率范围[8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000]。<br>- G711-mulaw编码支持采样率范围[8000 - 8000]。<br>- MP3编码支持采样率范围[8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000]。<br>可变比特率模式，码率仅作参考。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4431| fileFormat | [ContainerFormatType](#containerformattype8) | 是 | 文件的容器格式，必要参数。当前支持MP4、M4A、MP3、WAV封装格式，不支持在MP4封装格式下使用AUDIO_MP3编码格式。<br>**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4432| videoBitrate | number | 否 | 视频编码比特率，选择视频录制时必填，支持范围[10000 - 100000000]。 | 4433| videoCodec | [CodecMimeType](#codecmimetype8) | 否 | 视频编码格式，选择视频录制时必填。当前支持VIDEO_AVC。| 4434| videoFrameWidth | number | 否 | 视频帧的宽，选择视频录制时必填，支持范围[176 - 4096]。 | 4435| videoFrameHeight | number | 否 | 视频帧的高，选择视频录制时必填，支持范围[144 - 4096]。 | 4436| videoFrameRate | number | 否 | 视频帧率，选择视频录制时必填，支持范围[1 - 60]。 | 4437| isHdr<sup>11+</sup> | boolean | 否 | HDR编码，选择视频录制时选填，isHdr默认为false，对应编码格式没有要求，isHdr为true时，对应的编码格式必须为video/hevc。| 4438| enableTemporalScale<sup>12+</sup> | boolean | 否 | 视频录制是否支持时域分层编码功能，选择视频录制时选填，enableTemporalScale默认为false。设置为true时，编码输出的码流中部分帧可以支持跳过不编码。| 4439 4440## AudioSourceType<sup>9+</sup> 4441 4442表示视频录制中音频源类型的枚举。 4443 4444**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4445 4446| 名称 | 值 | 说明 | 4447| ------------------------- | ---- | ---------------------- | 4448| AUDIO_SOURCE_TYPE_DEFAULT | 0 | 默认的音频输入源类型。 | 4449| AUDIO_SOURCE_TYPE_MIC | 1 | 表示MIC的音频输入源。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4450| AUDIO_SOURCE_TYPE_VOICE_RECOGNITION<sup>12+</sup> | 2 | 表示语音识别场景的音频源。 | 4451| AUDIO_SOURCE_TYPE_VOICE_COMMUNICATION<sup>12+</sup> | 7 | 表示语音通话场景的音频源。 | 4452| AUDIO_SOURCE_TYPE_VOICE_MESSAGE<sup>12+</sup> | 10 | 表示短语音消息的音频源。 | 4453| AUDIO_SOURCE_TYPE_CAMCORDER<sup>12+</sup> | 13 | 表示相机录像的音频源。 | 4454 4455## VideoSourceType<sup>9+</sup> 4456 4457表示视频录制中视频源类型的枚举。 4458 4459**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4460 4461| 名称 | 值 | 说明 | 4462| ----------------------------- | ---- | ------------------------------- | 4463| VIDEO_SOURCE_TYPE_SURFACE_YUV | 0 | 输入surface中携带的是raw data。 | 4464| VIDEO_SOURCE_TYPE_SURFACE_ES | 1 | 输入surface中携带的是ES data。 | 4465 4466## ContainerFormatType<sup>8+</sup> 4467 4468表示容器格式类型的枚举，缩写为CFT。 4469 4470**系统能力：** SystemCapability.Multimedia.Media.Core 4471 4472| 名称 | 值 | 说明 | 4473| ----------- | ----- | --------------------- | 4474| CFT_MPEG_4 | 'mp4' | 视频的容器格式，MP4。 | 4475| CFT_MPEG_4A | 'm4a' | 音频的容器格式，M4A。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4476| CFT_MP3<sup>12+</sup> | 'mp3' | 音频的容器格式，MP3。 | 4477| CFT_WAV<sup>12+</sup> | 'wav' | 音频的容器格式，WAV。 | 4478 4479## Location 4480 4481视频录制的地理位置。 4482 4483**系统能力：** SystemCapability.Multimedia.Media.Core 4484 4485| 名称 | 类型 | 必填 | 说明 | 4486| --------- | ------ | ---- | ---------------- | 4487| latitude | number | 是 | 地理位置的纬度。 | 4488| longitude | number | 是 | 地理位置的经度。 | 4489 4490## EncoderInfo<sup>11+</sup> 4491 4492编码器和规格参数 4493 4494系统能力：SystemCapability.Multimedia.Media.AVRecorder 4495 4496| 名称 | 类型 | 可读 | 可写 | 说明 | 4497| ---------- | -------------------------------- | ---- | ---- | ------------------------------------------------------------ | 4498| mimeType | [CodecMimeType](#codecmimetype8) | 是 | 否 | 编码器MIME类型名称 | 4499| type | string | 是 | 否 | 编码器类型，audio表示音频编码器，video表示视频编码器 | 4500| bitRate | [Range](#range11) | 是 | 否 | 比特率，包含该编码器的最大和最小值 | 4501| frameRate | [Range](#range11) | 是 | 否 | 视频帧率，包含帧率的最大和最小值，仅视频编码器拥有 | 4502| width | [Range](#range11) | 是 | 否 | 视频帧的宽度，包含宽度的最大和最小值，仅视频编码器拥有 | 4503| height | [Range](#range11) | 是 | 否 | 视频帧的高度，包含高度的最大和最小值，仅视频编码器拥有 | 4504| channels | [Range](#range11) | 是 | 否 | 音频采集声道数，包含声道数的最大和最小值，仅音频编码器拥有 | 4505| sampleRate | Array\<number> | 是 | 否 | 音频采样率，包含所有可以使用的音频采样率值，仅音频编码器拥有 | 4506 4507## Range<sup>11+</sup> 4508 4509表示一个类型的范围 4510 4511系统能力：SystemCapability.Multimedia.Media.AVRecorder 4512 4513| 名称 | 类型 | 可读 | 可写 | 说明 | 4514| ---- | ------ | ---- | ---- | ------------ | 4515| min | number | 是 | 否 | 范围的最小值 | 4516| max | number | 是 | 否 | 范围的最大值 | 4517 4518## FileGenerationMode<sup>12+</sup> 4519 4520表示创建媒体文件模式的枚举。 4521 4522**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4523 4524| 名称 | 值 | 说明 | 4525| ----------------------------- | ---- | ------------------------------- | 4526| APP_CREATE | 0 | 由应用自行在沙箱创建媒体文件。 | 4527| AUTO_CREATE_CAMERA_SCENE | 1 | 由系统创建媒体文件，当前仅在相机录制场景下生效，会忽略应用设置的url。 | 4528 4529## AVTranscoder<sup>12+</sup> 4530 4531视频转码管理类，用于视频转码。在调用AVTranscoder的方法前，需要先通过createAVTranscoder()构建一个AVTranscoder实例。 4532 4533视频转码demo可参考：[视频转码开发指导](../../media/media/using-avtranscoder-for-transcodering.md) 4534 4535### 属性 4536 4537**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4538 4539| 名称 | 类型 | 只读 | 可选 | 说明 | 4540| ------- | ------------------------------------ | ---- | ---- | ------------------ | 4541| fdSrc<sup>12+</sup> | [AVFileDescriptor](#avfiledescriptor9) | 否 | 否 | 源媒体文件描述，通过该属性设置数据源。<br/> **使用示例**：<br/>假设一个连续存储的媒体文件，地址偏移:0，字节长度:100。其文件描述为 AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVTranscoder 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。 | 4542| fdDst<sup>12+</sup> | number | 否 | 否 | 目标媒体文件描述，通过该属性设置数据输出。在创建AVTranscoder实例后，必须设置fdSrc和fdDst属性。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVTranscoder 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。 | 4543 4544### prepare<sup>12+</sup> 4545 4546prepare(config: AVTranscoderConfig): Promise\<void> 4547 4548异步方式进行视频转码的参数设置。通过Promise获取返回值。 4549 4550**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4551 4552**参数：** 4553 4554| 参数名 | 类型 | 必填 | 说明 | 4555| ------ | -------------------------------------- | ---- | -------------------------- | 4556| config | [AVTranscoderConfig](#avtranscoderconfig12) | 是 | 配置视频转码的相关参数。 | 4557 4558**返回值：** 4559 4560| 类型 | 说明 | 4561| -------------- | ------------------------------------------ | 4562| Promise\<void> | 异步视频转码prepare方法的Promise返回值。 | 4563 4564**错误码：** 4565 4566以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4567 4568| 错误码ID | 错误信息 | 4569| -------- | -------------------------------------- | 4570| 401 | The parameter check failed. Return by promise. | 4571| 5400102 | Operation not allowed. Return by promise. | 4572| 5400105 | Service died. Return by promise. | 4573| 5400106 | Unsupported format. Returned by promise. | 4574 4575**示例：** 4576 4577```ts 4578import { BusinessError } from '@kit.BasicServicesKit'; 4579 4580// 配置参数以实际硬件设备支持的范围为准 4581let avTranscoderConfig: media.AVTranscoderConfig = { 4582 audioBitrate : 200000, 4583 audioCodec : media.CodecMimeType.AUDIO_AAC, 4584 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 4585 videoBitrate : 3000000, 4586 videoCodec : media.CodecMimeType.VIDEO_AVC, 4587 videoFrameWidth : 1280, 4588 videoFrameHeight : 720, 4589} 4590 4591avTranscoder.prepare(avTranscoderConfig).then(() => { 4592 console.info('prepare success'); 4593}).catch((err: BusinessError) => { 4594 console.error('prepare failed and catch error is ' + err.message); 4595}); 4596``` 4597 4598### start<sup>12+</sup> 4599 4600start(): Promise\<void> 4601 4602异步方式开始视频转码。通过Promise获取返回值。 4603 4604需要[prepare()](#prepare12)事件成功触发后，才能调用start方法。 4605 4606**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4607 4608**返回值：** 4609 4610| 类型 | 说明 | 4611| -------------- | ------------------------------------- | 4612| Promise\<void> | 异步开始视频转码方法的Promise返回值。 | 4613 4614**错误码：** 4615 4616以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4617 4618| 错误码ID | 错误信息 | 4619| -------- | -------------------------------------- | 4620| 5400102 | Operation not allowed. Return by promise. | 4621| 5400103 | IO error. Return by promise. | 4622| 5400105 | Service died. Return by promise. | 4623 4624**示例：** 4625 4626```ts 4627import { BusinessError } from '@kit.BasicServicesKit'; 4628 4629avTranscoder.start().then(() => { 4630 console.info('start AVTranscoder success'); 4631}).catch((err: BusinessError) => { 4632 console.error('start AVTranscoder failed and catch error is ' + err.message); 4633}); 4634``` 4635 4636### pause<sup>12+</sup> 4637 4638pause(): Promise\<void> 4639 4640异步方式暂停视频转码。通过Promise获取返回值。 4641 4642需要[start()](#start12)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume12)接口来恢复转码。 4643 4644**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4645 4646**返回值：** 4647 4648| 类型 | 说明 | 4649| -------------- | ------------------------------------- | 4650| Promise\<void> | 异步暂停视频转码方法的Promise返回值。 | 4651 4652**错误码：** 4653 4654以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4655 4656| 错误码ID | 错误信息 | 4657| -------- | -------------------------------------- | 4658| 5400102 | Operation not allowed. Return by promise. | 4659| 5400103 | IO error. Return by promise. | 4660| 5400105 | Service died. Return by promise. | 4661 4662**示例：** 4663 4664```ts 4665import { BusinessError } from '@kit.BasicServicesKit'; 4666 4667avTranscoder.pause().then(() => { 4668 console.info('pause AVTranscoder success'); 4669}).catch((err: BusinessError) => { 4670 console.error('pause AVTranscoder failed and catch error is ' + err.message); 4671}); 4672``` 4673 4674### resume<sup>12+</sup> 4675 4676resume(): Promise\<void> 4677 4678异步方式恢复视频转码。通过Promise获取返回值。 4679 4680需要在[pause()](#pause12)事件成功触发后，才能调用resume方法。 4681 4682**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4683 4684**返回值：** 4685 4686| 类型 | 说明 | 4687| -------------- | ------------------------------------- | 4688| Promise\<void> | 异步恢复视频转码方法的Promise返回值。 | 4689 4690**错误码：** 4691 4692以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4693 4694| 错误码ID | 错误信息 | 4695| -------- | -------------------------------------- | 4696| 5400102 | Operation not allowed. Return by promise. | 4697| 5400103 | IO error. Return by promise. | 4698| 5400105 | Service died. Return by promise. | 4699 4700**示例：** 4701 4702```ts 4703import { BusinessError } from '@kit.BasicServicesKit'; 4704 4705avTranscoder.resume().then(() => { 4706 console.info('resume AVTranscoder success'); 4707}).catch((err: BusinessError) => { 4708 console.error('resume AVTranscoder failed and catch error is ' + err.message); 4709}); 4710``` 4711 4712### cancel<sup>12+</sup> 4713 4714cancel(): Promise\<void> 4715 4716异步方式取消视频转码。通过Promise获取返回值。 4717 4718需要在[prepare()](#prepare12)、[start()](#start12)、[pause()](#pause12)或[resume()](#resume12)事件成功触发后，才能调用cancel方法。 4719 4720**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4721 4722**返回值：** 4723 4724| 类型 | 说明 | 4725| -------------- | ------------------------------------- | 4726| Promise\<void> | 异步取消视频转码方法的Promise返回值。 | 4727 4728**错误码：** 4729 4730以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4731 4732| 错误码ID | 错误信息 | 4733| -------- | -------------------------------------- | 4734| 5400102 | Operation not allowed. Return by promise. | 4735| 5400103 | IO error. Return by promise. | 4736| 5400105 | Service died. Return by promise. | 4737 4738**示例：** 4739 4740```ts 4741import { BusinessError } from '@kit.BasicServicesKit'; 4742 4743avTranscoder.cancel().then(() => { 4744 console.info('cancel AVTranscoder success'); 4745}).catch((err: BusinessError) => { 4746 console.error('cancel AVTranscoder failed and catch error is ' + err.message); 4747}); 4748``` 4749 4750### release<sup>12+</sup> 4751 4752release(): Promise\<void> 4753 4754异步方式释放视频转码资源。通过Promise获取返回值。 4755 4756释放视频转码资源之后，该AVTranscoder实例不能再进行任何操作。 4757 4758**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4759 4760**返回值：** 4761 4762| 类型 | 说明 | 4763| -------------- | ------------------------------------------- | 4764| Promise\<void> | 异步释放视频转码资源方法的Promise返回值。 | 4765 4766**错误码：** 4767 4768以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4769 4770| 错误码ID | 错误信息 | 4771| -------- | --------------------------------- | 4772| 5400102 | Operation not allowed. Return by promise. | 4773| 5400105 | Service died. Return by promise. | 4774 4775**示例：** 4776 4777```ts 4778import { BusinessError } from '@kit.BasicServicesKit'; 4779 4780avTranscoder.release().then(() => { 4781 console.info('release AVTranscoder success'); 4782}).catch((err: BusinessError) => { 4783 console.error('release AVTranscoder failed and catch error is ' + err.message); 4784}); 4785``` 4786 4787### on('progressUpdate')<sup>12+</sup> 4788 4789on(type: 'progressUpdate', callback: Callback\<number>): void 4790 4791注册转码进度更新事件，并通过注册的回调方法通知用户。用户只能注册一个进度更新事件的回调方法，当用户重复注册时，以最后一次注册的回调接口为准。 4792 4793**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4794 4795**参数：** 4796 4797| 参数名 | 类型 | 必填 | 说明 | 4798| -------- | -------- | ---- | ------------------------------------------------------------ | 4799| type | string | 是 | 进度更新事件回调类型，支持的事件：'progressUpdate'，在转码过程中系统会自动触发此事件。 | 4800| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback) | 是 | 进度更新事件回调方法，progress: number，表示当前转码进度 | 4801 4802**示例：** 4803 4804```ts 4805avTranscoder.on('progressUpdate', (progress: number) => { 4806 console.info('avTranscoder progressUpdate = ' + progress); 4807}); 4808``` 4809 4810### off('progressUpdate')<sup>12+</sup> 4811 4812off(type:'progressUpdate', callback?: Callback\<number>): void 4813 4814取消注册转码进度更新事件。 4815 4816**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4817 4818**参数：** 4819 4820| 参数名 | 类型 | 必填 | 说明 | 4821| ------ | ------ | ---- | ------------------------------------------------------------ | 4822| type | string | 是 | 进度更新事件回调类型，支持的事件：'progressUpdate'，用户操作和系统都会触发此事件。 | 4823| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback) | 否 | 进度更新事件回调方法，progress: number，表示当前转码进度 | 4824 4825**示例：** 4826 4827```ts 4828avTranscoder.off('progressUpdate'); 4829``` 4830 4831### on('error')<sup>12+</sup> 4832 4833on(type: 'error', callback: ErrorCallback): void 4834 4835注册AVtranscoder的错误事件，该事件仅用于错误提示。如果AVTranscoder上报error事件，用户需要通过[release()](#release12)退出转码操作。 4836 4837用户只能订阅一个错误事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 4838 4839**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4840 4841**参数：** 4842 4843| 参数名 | 类型 | 必填 | 说明 | 4844| -------- | ------------- | ---- | ------------------------------------------------------------ | 4845| type | string | 是 | 转码错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 4846| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 转码错误事件回调方法。 | 4847 4848**错误码：** 4849 4850以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4851 4852| 错误码ID | 错误信息 | 4853| -------- | ------------------------------------------ | 4854| 401 | The parameter check failed. | 4855| 801 | Capability not supported. | 4856| 5400101 | No memory. | 4857| 5400102 | Operation not allowed. | 4858| 5400103 | I/O error. | 4859| 5400104 | Time out. | 4860| 5400105 | Service died. | 4861| 5400106 | Unsupported format. | 4862 4863**示例：** 4864 4865```ts 4866import { BusinessError } from '@kit.BasicServicesKit'; 4867 4868avTranscoder.on('error', (err: BusinessError) => { 4869 console.info('case avTranscoder.on(error) called, errMessage is ' + err.message); 4870}); 4871``` 4872 4873### off('error')<sup>12+</sup> 4874 4875off(type:'error', callback?: ErrorCallback): void 4876 4877取消注册转码错误事件，取消后不再接收到AVTranscoder的错误事件。 4878 4879**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4880 4881**参数：** 4882 4883| 参数名 | 类型 | 必填 | 说明 | 4884| ------ | ------ | ---- | ------------------------------------------------------------ | 4885| type | string | 是 | 转码错误事件回调类型'error'。 <br>- 'error'：转码过程中发生错误，触发该事件。 | 4886| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 错误事件回调方法 | 4887 4888**示例：** 4889 4890```ts 4891avTranscoder.off('error'); 4892``` 4893 4894### on('complete')<sup>12+</sup> 4895 4896on(type: 'complete', callback: Callback\<void>): void 4897 4898注册转码完成事件，并通过注册的回调方法通知用户。用户只能注册一个进度更新事件的回调方法，当用户重复注册时，以最后一次注册的回调接口为准。 4899 4900当AVTranscoder上报complete事件时，当前转码操作已完成，用户可通过[release()](#release12)退出转码操作。 4901 4902**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4903 4904**参数：** 4905 4906| 参数名 | 类型 | 必填 | 说明 | 4907| -------- | -------- | ---- | ------------------------------------------------------------ | 4908| type | string | 是 | 完成事件回调类型，支持的事件：'complete'，在转码过程中系统会自动触发此事件。 | 4909| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback) | 是 | 完成事件回调方法 | 4910 4911**示例：** 4912 4913```ts 4914avTranscoder.on('complete', () => { 4915 console.info('avTranscoder complete'); 4916}); 4917``` 4918 4919### off('complete')<sup>12+</sup> 4920 4921off(type:'complete', callback?: Callback\<void>): void 4922 4923取消注册转码完成事件。 4924 4925**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4926 4927**参数：** 4928 4929| 参数名 | 类型 | 必填 | 说明 | 4930| ------ | ------ | ---- | ------------------------------------------------------------ | 4931| type | string | 是 | 转码完成事件回调类型，支持的事件：'complete'，用户操作和系统都会触发此事件。 | 4932| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback) | 否 | 完成事件回调方法 | 4933 4934**示例：** 4935 4936```ts 4937avTranscoder.off('complete'); 4938``` 4939 4940## AVTranscoderConfig<sup>12+</sup> 4941 4942表示视频转码的参数设置。 4943 4944**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4945 4946| 名称 | 类型 | 只读 | 可选 | 说明 | 4947| --------------- | ---------------------------------------- |---- | ---- | ------------------------------------------------------------ | 4948| audioBitrate | number | 否 | 是 | 输出音频的码率，单位为比特率（bps）。用户不设置，则默认设置为48Kbps| 4949| audioCodec | [CodecMimeType](#codecmimetype8) | 否 | 是 | 输出音频的编码格式，当前仅支持AAC。 | 4950| fileFormat | [ContainerFormatType](#containerformattype8) | 否 | 否 | 输出视频文件的封装格式，当前视频文件仅支持MP4。| 4951| videoBitrate | number | 否 | 是 | 输出视频的码率，单位为比特率（bps）。用户不设置，则默认码率按输出视频的分辨率设置，[240p，480P]默认码率值为1Mbps，(480P,720P]默认码率值为2Mbps，(720P,1080P]默认码率值为4Mbps，1080P及以上默认值为8Mbps。| 4952| videoCodec | [CodecMimeType](#codecmimetype8) | 否 | 是 | 输出视频的编码格式，当前仅支持AVC和HEVC。| 4953| videoFrameWidth | number | 否 | 是 | 输出视频帧的宽，单位为像素（px）。用户不设置，则默认设置为源视频帧的宽| 4954| videoFrameHeight | number | 否 | 是 | 输出视频帧的高，单位为像素（px）。用户不设置，则默认设置为源视频帧的高| 4955 4956 4957 4958## AVMetadataExtractor<sup>11+</sup> 4959 4960元数据获取类，用于从媒体资源中获取元数据。在调用AVMetadataExtractor的方法前，需要先通过[createAVMetadataExtractor()](#mediacreateavmetadataextractor11)构建一个AVMetadataExtractor实例。 4961 4962获取音频或视频元数据的demo可参考：[获取音视频元数据开发指导](../../media/media/avmetadataextractor.md)。 4963 4964### 属性 4965 4966**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 4967 4968| 名称 | 类型 | 可读 | 可写 | 说明 | 4969| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 4970| 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。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致音视频元数据获取异常。 | 4971| dataSrc<sup>11+</sup> | [AVDataSrcDescriptor](#avdatasrcdescriptor10) | 是 | 是 | 流式媒体资源描述，通过该属性设置数据源。在获取元数据之前，必须设置数据源属性，只能设置fdSrc和dataSrc的其中一个。<br/> 当应用从远端获取音视频媒体文件，在应用未下载完整音视频资源时，可以设置dataSrc提前获取该资源的元数据。| 4972 4973### fetchMetadata<sup>11+</sup> 4974 4975fetchMetadata(callback: AsyncCallback\<AVMetadata>): void 4976 4977异步方式获取媒体元数据。通过注册回调函数获取返回值。 4978 4979**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 4980 4981**参数：** 4982 4983| 参数名 | 类型 | 必填 | 说明 | 4984| -------- | -------------------------------------------- | ---- | ----------------------------------- | 4985| callback | AsyncCallback\<[AVMetadata](#avmetadata11)> | 是 | 回调函数。异步返回音视频元数据对象（AVMetadata）。| 4986 4987**错误码：** 4988 4989以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 4990 4991| 错误码ID | 错误信息 | 4992| -------- | ------------------------------------------ | 4993| 5400102 | Operation not allowed. Returned by callback. | 4994| 5400106 | Unsupported format. Returned by callback. | 4995 4996**示例：** 4997 4998```ts 4999import { BusinessError } from '@kit.BasicServicesKit'; 5000 5001avMetadataExtractor.fetchMetadata((error: BusinessError, metadata: media.AVMetadata) => { 5002 if (error) { 5003 console.error(`Failed to fetch Metadata, err = ${JSON.stringify(error)}`); 5004 return; 5005 } 5006 console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`); 5007}); 5008``` 5009 5010### fetchMetadata<sup>11+</sup> 5011 5012fetchMetadata(): Promise\<AVMetadata> 5013 5014异步方式获取媒体元数据。通过Promise获取返回值。 5015 5016**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5017 5018**返回值：** 5019 5020| 类型 | 说明 | 5021| -------------- | ---------------------------------------- | 5022| Promise\<[AVMetadata](#avmetadata11)> | Promise对象。异步返回音视频元数据对象（AVMetadata）。 | 5023 5024**错误码：** 5025 5026以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5027 5028| 错误码ID | 错误信息 | 5029| -------- | ----------------------------------------- | 5030| 5400102 | Operation not allowed. Returned by promise. | 5031| 5400106 | Unsupported format. Returned by promise. | 5032 5033**示例：** 5034 5035```ts 5036import { BusinessError } from '@kit.BasicServicesKit'; 5037 5038avMetadataExtractor.fetchMetadata().then((metadata: media.AVMetadata) => { 5039 console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`) 5040}).catch((error: BusinessError) => { 5041 console.error(`Failed to fetch Metadata, error message:${error.message}`); 5042}); 5043``` 5044 5045### fetchAlbumCover<sup>11+</sup> 5046 5047fetchAlbumCover(callback: AsyncCallback\<image.PixelMap>): void 5048 5049异步方式获取音频专辑封面。通过注册回调函数获取返回值。 5050 5051**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5052 5053**参数：** 5054 5055| 参数名 | 类型 | 必填 | 说明 | 5056| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5057| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | 回调函数。异步返回专辑封面。 | 5058 5059**错误码：** 5060 5061以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5062 5063| 错误码ID | 错误信息 | 5064| -------- | ------------------------------------------ | 5065| 5400102 | Operation not allowed. Return by callback. | 5066| 5400106 | Unsupported format. Returned by callback. | 5067 5068**示例：** 5069 5070```ts 5071import { BusinessError } from '@kit.BasicServicesKit'; 5072import { image } from '@kit.ImageKit'; 5073 5074let pixel_map : image.PixelMap | undefined = undefined; 5075 5076avMetadataExtractor.fetchAlbumCover((error: BusinessError, pixelMap: image.PixelMap) => { 5077 if (error) { 5078 console.error(`Failed to fetch AlbumCover, error = ${JSON.stringify(error)}`); 5079 return; 5080 } 5081 pixel_map = pixelMap; 5082}); 5083``` 5084 5085### fetchAlbumCover<sup>11+</sup> 5086 5087fetchAlbumCover(): Promise\<image.PixelMap> 5088 5089异步方式获取专辑封面。通过Promise获取返回值。 5090 5091**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5092 5093**返回值：** 5094 5095| 类型 | 说明 | 5096| -------------- | ---------------------------------------- | 5097| Promise\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise对象。异步返回专辑封面。 | 5098 5099**错误码：** 5100 5101以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5102 5103| 错误码ID | 错误信息 | 5104| -------- | ----------------------------------------- | 5105| 5400102 | Operation not allowed. Returned by promise. | 5106| 5400106 | Unsupported format. Returned by promise. | 5107 5108**示例：** 5109 5110```ts 5111import { BusinessError } from '@kit.BasicServicesKit'; 5112import { image } from '@kit.ImageKit'; 5113 5114let pixel_map : image.PixelMap | undefined = undefined; 5115 5116avMetadataExtractor.fetchAlbumCover().then((pixelMap: image.PixelMap) => { 5117 pixel_map = pixelMap; 5118}).catch((error: BusinessError) => { 5119 console.error(`Failed to fetch AlbumCover, error message:${error.message}`); 5120}); 5121``` 5122 5123### release<sup>11+</sup> 5124 5125release(callback: AsyncCallback\<void>): void 5126 5127异步方式释放资源。通过注册回调函数获取返回值。 5128 5129**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5130 5131**参数：** 5132 5133| 参数名 | 类型 | 必填 | 说明 | 5134| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5135| callback | AsyncCallback\<void> | 是 |回调函数。当释放资源成功，err为undefined，否则为错误对象。 | 5136 5137**错误码：** 5138 5139以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5140 5141| 错误码ID | 错误信息 | 5142| -------- | ------------------------------------------ | 5143| 5400102 | Operation not allowed. Returned by callback. | 5144 5145**示例：** 5146 5147```ts 5148import { BusinessError } from '@kit.BasicServicesKit'; 5149 5150avMetadataExtractor.release((error: BusinessError) => { 5151 if (error) { 5152 console.error(`Failed to release, err = ${JSON.stringify(error)}`); 5153 return; 5154 } 5155 console.info(`Succeeded in releasing.`); 5156}); 5157``` 5158 5159### release<sup>11+</sup> 5160 5161release(): Promise\<void> 5162 5163异步方式释放资源。通过Promise获取返回值。 5164 5165**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5166 5167**返回值：** 5168 5169| 类型 | 说明 | 5170| -------------- | ---------------------------------------- | 5171| Promise\<void> | 异步方式释放资源release方法的Promise返回值。 | 5172 5173**错误码：** 5174 5175以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5176 5177| 错误码ID | 错误信息 | 5178| -------- | ----------------------------------------- | 5179| 5400102 | Operation not allowed. Returned by promise. | 5180 5181**示例：** 5182 5183```ts 5184import { BusinessError } from '@kit.BasicServicesKit'; 5185 5186avMetadataExtractor.release().then(() => { 5187 console.info(`Succeeded in releasing.`); 5188}).catch((error: BusinessError) => { 5189 console.error(`Failed to release, error message:${error.message}`); 5190}); 5191``` 5192 5193## AVMetadata<sup>11+</sup> 5194 5195音视频元数据，包含各个元数据字段。在[AVRecorderConfig](#avrecorderconfig9)中使用时未声明为当前版本只读的参数可以作为使用[AVRecorder](#avrecorder9)录制时的入参。 5196 5197**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5198 5199| 名称 | 类型 | 必填 | 说明 | 5200| ------ | ------ | ---- | ------------------------------------------------------------ | 5201| album | string | 否 | 专辑的标题。当前版本为只读参数。 | 5202| albumArtist | string | 否 | 专辑的艺术家。当前版本为只读参数。 | 5203| artist | string | 否 | 媒体资源的艺术家。当前版本为只读参数。 | 5204| author | string | 否 | 媒体资源的作者。当前版本为只读参数。 | 5205| dateTime | string | 否 | 媒体资源的创建时间。当前版本为只读参数。 | 5206| dateTimeFormat | string | 否 | 媒体资源的创建时间，按YYYY-MM-DD HH:mm:ss格式输出。当前版本为只读参数。 | 5207| composer | string | 否 | 媒体资源的作曲家。当前版本为只读参数。 | 5208| duration | string | 否 | 媒体资源的时长。当前版本为只读参数。 | 5209| genre | string | 否 | 媒体资源的类型或体裁。| 5210| hasAudio | string | 否 | 媒体资源是否包含音频。当前版本为只读参数。 | 5211| hasVideo | string | 否 | 媒体资源是否包含视频。当前版本为只读参数。 | 5212| mimeType | string | 否 | 媒体资源的mime类型。当前版本为只读参数。 | 5213| trackCount | string | 否 | 媒体资源的轨道数量。当前版本为只读参数。 | 5214| sampleRate | string | 否 | 音频的采样率，单位为赫兹（Hz）。当前版本为只读参数。 | 5215| title | string | 否 | 媒体资源的标题。当前版本为只读参数。当前版本为只读参数。 | 5216| videoHeight | string | 否 | 视频的高度，单位为像素。当前版本为只读参数。 | 5217| videoWidth | string | 否 | 视频的宽度，单位为像素。当前版本为只读参数。 | 5218| videoOrientation | string | 否 | 视频的旋转方向，单位为度（°）。| 5219| hdrType<sup>12+</sup> | [HdrType](#hdrtype12) | 否 | 媒体资源的HDR类型。当前版本为只读参数。 | 5220| location<sup>12+</sup> | [Location](#location) | 否 | 视频的地理位置信息。 | 5221| customInfo<sup>12+</sup> | Record<string, string> | 否 | 从moov.meta.list 获取的自定义参数键值映射。| 5222 5223## HdrType<sup>12+</sup> 5224 5225表示视频HDR类型的枚举。 5226 5227**系统能力：** SystemCapability.Multimedia.Media.Core 5228 5229| 名称 | 值 | 说明 | 5230| ------------------------- | ---- | ---------------------- | 5231| AV_HDR_TYPE_NONE | 0 | 表示无HDR类型。 | 5232| AV_HDR_TYPE_VIVID | 1 | 表示为HDR VIVID类型。 | 5233 5234## media.createAudioPlayer<sup>(deprecated)</sup> 5235 5236createAudioPlayer(): AudioPlayer 5237 5238同步方式创建音频播放实例。 5239 5240> **说明：** 5241> 从API version 6开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9)替代。 5242 5243**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5244 5245**返回值：** 5246 5247| 类型 | 说明 | 5248| --------------------------- | ------------------------------------------------------------ | 5249| [AudioPlayer](#audioplayerdeprecated) | 返回AudioPlayer类实例，失败时返回null。可用于音频播放、暂停、停止等操作。 | 5250 5251**示例：** 5252 5253```ts 5254let audioPlayer: media.AudioPlayer = media.createAudioPlayer(); 5255``` 5256 5257## media.createVideoPlayer<sup>(deprecated)</sup> 5258 5259createVideoPlayer(callback: AsyncCallback\<VideoPlayer>): void 5260 5261异步方式创建视频播放实例，通过注册回调函数获取返回值。 5262 5263> **说明：** 5264> 从API version 8开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9)替代。 5265 5266**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5267 5268**参数：** 5269 5270| 参数名 | 类型 | 必填 | 说明 | 5271| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 5272| callback | AsyncCallback<[VideoPlayer](#videoplayerdeprecated)> | 是 | 回调函数。创建VideoPlayer实例成功时，err为undefined，data为获取到的VideoPlayer实例，否则为错误对象。 | 5273 5274**示例：** 5275 5276```ts 5277import { BusinessError } from '@kit.BasicServicesKit'; 5278 5279let videoPlayer: media.VideoPlayer; 5280media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 5281 if (video != null) { 5282 videoPlayer = video; 5283 console.info('Succeeded in creating VideoPlayer'); 5284 } else { 5285 console.error(`Failed to create VideoPlayer, error:${error}`); 5286 } 5287}); 5288``` 5289 5290## media.createVideoPlayer<sup>(deprecated)</sup> 5291 5292createVideoPlayer(): Promise\<VideoPlayer> 5293 5294异步方式创建视频播放实例，通过Promise获取返回值。 5295 5296> **说明：** 5297> 从API version 8开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9-1)替代。 5298 5299**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5300 5301**返回值：** 5302 5303| 类型 | 说明 | 5304| ------------------------------------ | ------------------------------------------------------------ | 5305| Promise<[VideoPlayer](#videoplayerdeprecated)> | Promise对象。异步返回VideoPlayer实例，失败时返回null。可用于管理和播放视频媒体。 | 5306 5307**示例：** 5308 5309```ts 5310import { BusinessError } from '@kit.BasicServicesKit'; 5311 5312let videoPlayer: media.VideoPlayer; 5313media.createVideoPlayer().then((video: media.VideoPlayer) => { 5314 if (video != null) { 5315 videoPlayer = video; 5316 console.info('Succeeded in creating VideoPlayer'); 5317 } else { 5318 console.error('Failed to create VideoPlayer'); 5319 } 5320}).catch((error: BusinessError) => { 5321 console.error(`Failed to create VideoPlayer, error:${error}`); 5322}); 5323``` 5324 5325## media.createAudioRecorder<sup>(deprecated)</sup> 5326 5327createAudioRecorder(): AudioRecorder 5328 5329创建音频录制的实例来控制音频的录制。 5330一台设备只允许创建一个录制实例。 5331 5332> **说明：** 5333> 从API version 6开始支持，从API version 9开始废弃，建议使用[createAVRecorder](#mediacreateavrecorder9)替代。 5334 5335**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 5336 5337**返回值:** 5338 5339| 类型 | 说明 | 5340| ------------------------------- | ------------------------------------------------------------ | 5341| [AudioRecorder](#audiorecorderdeprecated) | 返回AudioRecorder类实例，失败时返回null。可用于录制音频媒体。 | 5342 5343**示例：** 5344 5345```ts 5346let audioRecorder: media.AudioRecorder = media.createAudioRecorder(); 5347``` 5348 5349## MediaErrorCode<sup>(deprecated)</sup> 5350 5351媒体服务错误类型枚举。 5352 5353> **说明：** 5354> 从API version 8开始支持，从API version 11开始废弃，建议使用[媒体错误码](#averrorcode9)替代。 5355 5356**系统能力：** SystemCapability.Multimedia.Media.Core 5357 5358| 名称 | 值 | 说明 | 5359| -------------------------- | ---- | -------------------------------------- | 5360| MSERR_OK | 0 | 表示操作成功。 | 5361| MSERR_NO_MEMORY | 1 | 表示申请内存失败，系统可能无可用内存。 | 5362| MSERR_OPERATION_NOT_PERMIT | 2 | 表示无权限执行此操作。 | 5363| MSERR_INVALID_VAL | 3 | 表示传入入参无效。 | 5364| MSERR_IO | 4 | 表示发生IO错误。 | 5365| MSERR_TIMEOUT | 5 | 表示操作超时。 | 5366| MSERR_UNKNOWN | 6 | 表示未知错误。 | 5367| MSERR_SERVICE_DIED | 7 | 表示服务端失效。 | 5368| MSERR_INVALID_STATE | 8 | 表示在当前状态下，不允许执行此操作。 | 5369| MSERR_UNSUPPORTED | 9 | 表示在当前版本下，不支持此操作。 | 5370 5371## AudioPlayer<sup>(deprecated)</sup> 5372 5373> **说明：** 5374> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer](#avplayer9)替代。 5375 5376音频播放管理类，用于管理和播放音频媒体。在调用AudioPlayer的方法前，需要先通过[createAudioPlayer()](#mediacreateaudioplayerdeprecated)构建一个AudioPlayer实例。 5377 5378### 属性<sup>(deprecated)</sup> 5379 5380**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5381 5382| 名称 | 类型 | 只读 | 可选 | 说明 | 5383| ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 5384| 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。 | 5385| 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/> | 5386| loop | boolean | 否 | 否 | 音频循环播放属性，设置为'true'表示循环播放。 | 5387| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9) | 是 | 是 | 音频焦点模型。 | 5388| currentTime | number | 是 | 否 | 音频的当前播放位置，单位为毫秒（ms）。 | 5389| duration | number | 是 | 否 | 音频时长，单位为毫秒（ms）。 | 5390| state | [AudioState](#audiostatedeprecated) | 是 | 否 | 可以查询音频播放的状态，该状态不可作为调用play/pause/stop等状态切换的触发条件。 | 5391 5392### play<sup>(deprecated)</sup> 5393 5394play(): void 5395 5396开始播放音频资源，需在'dataLoad'事件成功触发后，才能调用。 5397 5398> **说明：** 5399> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9)替代。 5400 5401**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5402 5403**示例：** 5404 5405```ts 5406audioPlayer.on('play', () => { //设置'play'事件回调 5407 console.info('audio play called'); 5408}); 5409audioPlayer.play(); 5410``` 5411 5412### pause<sup>(deprecated)</sup> 5413 5414pause(): void 5415 5416暂停播放音频资源。 5417 5418> **说明：** 5419> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9)替代。 5420 5421**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5422 5423**示例：** 5424 5425```ts 5426audioPlayer.on('pause', () => { //设置'pause'事件回调 5427 console.info('audio pause called'); 5428}); 5429audioPlayer.pause(); 5430``` 5431 5432### stop<sup>(deprecated)</sup> 5433 5434stop(): void 5435 5436停止播放音频资源。 5437 5438> **说明：** 5439> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9)替代。 5440 5441**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5442 5443**示例：** 5444 5445```ts 5446audioPlayer.on('stop', () => { //设置'stop'事件回调 5447 console.info('audio stop called'); 5448}); 5449audioPlayer.stop(); 5450``` 5451 5452### reset<sup>(deprecated)</sup> 5453 5454reset(): void 5455 5456重置播放音频资源。 5457 5458> **说明：** 5459> 从API version 7开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9)替代。 5460 5461**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5462 5463**示例：** 5464 5465```ts 5466audioPlayer.on('reset', () => { //设置'reset'事件回调 5467 console.info('audio reset called'); 5468}); 5469audioPlayer.reset(); 5470``` 5471 5472### seek<sup>(deprecated)</sup> 5473 5474seek(timeMs: number): void 5475 5476跳转到指定播放位置。 5477 5478> **说明：** 5479> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 5480 5481**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5482 5483**参数：** 5484 5485| 参数名 | 类型 | 必填 | 说明 | 5486| ------ | ------ | ---- | ----------------------------------------------------------- | 5487| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围[0, duration]。 | 5488 5489**示例：** 5490 5491```ts 5492audioPlayer.on('timeUpdate', (seekDoneTime: number) => { //设置'timeUpdate'事件回调 5493 if (seekDoneTime == null) { 5494 console.error('Failed to seek'); 5495 return; 5496 } 5497 console.info('Succeeded in seek. seekDoneTime: ' + seekDoneTime); 5498}); 5499audioPlayer.seek(30000); //seek到30000ms的位置 5500``` 5501 5502### setVolume<sup>(deprecated)</sup> 5503 5504setVolume(vol: number): void 5505 5506设置音量。 5507 5508> **说明：** 5509> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 5510 5511**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5512 5513**参数：** 5514 5515| 参数名 | 类型 | 必填 | 说明 | 5516| ------ | ------ | ---- | ------------------------------------------------------------ | 5517| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 5518 5519**示例：** 5520 5521```ts 5522audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调 5523 console.info('audio volumeChange called'); 5524}); 5525audioPlayer.setVolume(1); //设置音量到100% 5526``` 5527 5528### release<sup>(deprecated)</sup> 5529 5530release(): void 5531 5532释放音频资源。 5533 5534> **说明：** 5535> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9)替代。 5536 5537**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5538 5539**示例：** 5540 5541```ts 5542audioPlayer.release(); 5543audioPlayer = undefined; 5544``` 5545 5546### getTrackDescription<sup>(deprecated)</sup> 5547 5548getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 5549 5550获取音频轨道信息。需在'dataLoad'事件成功触发后，才能调用。通过回调函数获取返回值。 5551 5552> **说明：** 5553> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9)替代。 5554 5555**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5556 5557**参数：** 5558 5559| 参数名 | 类型 | 必填 | 说明 | 5560| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 5561| callback | AsyncCallback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 回调函数。获取音频轨道信息成功时，err为undefined，data为获取到的MediaDescription数组，否则为错误对象。 | 5562 5563**示例：** 5564 5565```ts 5566import { BusinessError } from '@kit.BasicServicesKit'; 5567 5568audioPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 5569 if (arrList != null) { 5570 console.info('Succeeded in getting TrackDescription'); 5571 } else { 5572 console.error(`Failed to get TrackDescription, error:${error}`); 5573 } 5574}); 5575``` 5576 5577### getTrackDescription<sup>(deprecated)</sup> 5578 5579getTrackDescription(): Promise\<Array\<MediaDescription>> 5580 5581获取音频轨道信息。需在'dataLoad'事件成功触发后，才能调用。通过Promise获取返回值。 5582 5583> **说明：** 5584> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9-1)替代。 5585 5586**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5587 5588**返回值：** 5589 5590| 类型 | 说明 | 5591| ------------------------------------------------------ | ----------------------------------------------- | 5592| Promise<Array<[MediaDescription](#mediadescription8)>> | 音频轨道信息MediaDescription数组Promise返回值。 | 5593 5594**示例：** 5595 5596```ts 5597import { BusinessError } from '@kit.BasicServicesKit'; 5598 5599audioPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 5600 console.info('Succeeded in getting TrackDescription'); 5601}).catch((error: BusinessError) => { 5602 console.error(`Failed to get TrackDescription, error:${error}`); 5603}); 5604``` 5605 5606### on('bufferingUpdate')<sup>(deprecated)</sup> 5607 5608on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void 5609 5610开始订阅音频缓存更新事件。仅网络播放支持该订阅事件。 5611 5612> **说明：** 5613> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('bufferingUpdate')](#onbufferingupdate9)替代。 5614 5615**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5616 5617**参数：** 5618 5619| 参数名 | 类型 | 必填 | 说明 | 5620| -------- | -------- | ---- | ------------------------------------------------------------ | 5621| type | string | 是 | 音频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 5622| callback | function | 是 | 音频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)value值固定为0。 | 5623 5624**示例：** 5625 5626```ts 5627audioPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 5628 console.info('audio bufferingInfo type: ' + infoType); 5629 console.info('audio bufferingInfo value: ' + value); 5630}); 5631``` 5632 5633### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')<sup>(deprecated)</sup> 5634 5635on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void): void 5636 5637开始订阅音频播放事件。 5638 5639> **说明：** 5640> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('stateChange')](#onstatechange9)替代。 5641 5642**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5643 5644**参数：** 5645 5646| 参数名 | 类型 | 必填 | 说明 | 5647| -------- | ---------- | ---- | ------------------------------------------------------------ | 5648| 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)调用，播放音量改变后触发该事件。 | 5649| callback | () => void | 是 | 播放事件回调方法。 | 5650 5651**示例：** 5652 5653```ts 5654import { fileIo as fs } from '@kit.CoreFileKit'; 5655import { BusinessError } from '@kit.BasicServicesKit'; 5656 5657let audioPlayer: media.AudioPlayer = media.createAudioPlayer(); //创建一个音频播放实例 5658audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调，src属性设置成功后，触发此回调 5659 console.info('audio set source called'); 5660 audioPlayer.play(); //开始播放，并触发'play'事件回调 5661}); 5662audioPlayer.on('play', () => { //设置'play'事件回调 5663 console.info('audio play called'); 5664 audioPlayer.seek(30000); //调用seek方法，并触发'timeUpdate'事件回调 5665}); 5666audioPlayer.on('pause', () => { //设置'pause'事件回调 5667 console.info('audio pause called'); 5668 audioPlayer.stop(); //停止播放，并触发'stop'事件回调 5669}); 5670audioPlayer.on('reset', () => { //设置'reset'事件回调 5671 console.info('audio reset called'); 5672 audioPlayer.release(); //释放播放实例资源 5673 audioPlayer = undefined; 5674}); 5675audioPlayer.on('timeUpdate', (seekDoneTime: number) => { //设置'timeUpdate'事件回调 5676 if (seekDoneTime == null) { 5677 console.error('Failed to seek'); 5678 return; 5679 } 5680 console.info('Succeeded in seek, and seek time is ' + seekDoneTime); 5681 audioPlayer.setVolume(0.5); //设置音量为50%，并触发'volumeChange'事件回调 5682}); 5683audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调 5684 console.info('audio volumeChange called'); 5685 audioPlayer.pause(); //暂停播放，并触发'pause'事件回调 5686}); 5687audioPlayer.on('finish', () => { //设置'finish'事件回调 5688 console.info('audio play finish'); 5689 audioPlayer.stop(); //停止播放，并触发'stop'事件回调 5690}); 5691audioPlayer.on('error', (error: BusinessError) => { //设置'error'事件回调 5692 console.error(`audio error called, error: ${error}`); 5693}); 5694 5695// 用户选择音频设置fd(本地播放) 5696let fdPath = 'fd://'; 5697// path路径的码流可通过"hdc file send D:\xxx\01.mp3 /data/accounts/account_0/appdata" 命令，将其推送到设备上 5698let path = '/data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3'; 5699fs.open(path).then((file) => { 5700 fdPath = fdPath + '' + file.fd; 5701 console.info('Succeeded in opening fd, fd is' + fdPath); 5702 audioPlayer.src = fdPath; //设置src属性，并触发'dataLoad'事件回调 5703}, (err: BusinessError) => { 5704 console.error('Failed to open fd, err is' + err); 5705}).catch((err: BusinessError) => { 5706 console.error('Failed to open fd, err is' + err); 5707}); 5708``` 5709 5710### on('timeUpdate')<sup>(deprecated)</sup> 5711 5712on(type: 'timeUpdate', callback: Callback\<number>): void 5713 5714开始订阅音频播放时间更新事件。处于播放状态时，每隔1s上报一次该事件。 5715 5716> **说明：** 5717> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('timeUpdate')](#ontimeupdate9)替代。 5718 5719**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5720 5721**参数：** 5722 5723| 参数名 | 类型 | 必填 | 说明 | 5724| -------- | ----------------- | ---- | ------------------------------------------------------------ | 5725| type | string | 是 | 播放事件回调类型，支持的事件包括：'timeUpdate'。<br>- 'timeUpdate'：音频播放时间戳更新，开始播放后自动触发该事件。 | 5726| callback | Callback\<number> | 是 | 播放事件回调方法。回调方法入参为更新后的时间戳。 | 5727 5728**示例：** 5729 5730```ts 5731audioPlayer.on('timeUpdate', (newTime: number) => { //设置'timeUpdate'事件回调 5732 if (newTime == null) { 5733 console.error('Failed to do timeUpadate'); 5734 return; 5735 } 5736 console.info('Succeeded in doing timeUpadate. seekDoneTime: ' + newTime); 5737}); 5738audioPlayer.play(); //开始播放后，自动触发时间戳更新事件 5739``` 5740 5741### on('audioInterrupt')<sup>(deprecated)</sup> 5742 5743on(type: 'audioInterrupt', callback: (info: audio.InterruptEvent) => void): void 5744 5745监听音频焦点变化事件，参考[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)。 5746 5747> **说明：** 5748> 从API version 9开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('audioInterrupt')](#onaudiointerrupt9)替代。 5749 5750**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5751 5752**参数：** 5753 5754| 参数名 | 类型 | 必填 | 说明 | 5755| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 5756| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 5757| callback | function | 是 | 音频焦点变化事件回调方法。 | 5758 5759**示例：** 5760 5761```ts 5762import { audio } from '@kit.AudioKit'; 5763 5764audioPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 5765 console.info('audioInterrupt called,and InterruptEvent info is:' + info) 5766}) 5767``` 5768 5769### on('error')<sup>(deprecated)</sup> 5770 5771on(type: 'error', callback: ErrorCallback): void 5772 5773开始订阅音频播放错误事件，当上报error错误事件后，用户需处理error事件，退出播放操作。 5774 5775> **说明：** 5776> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('error')](#onerror9)替代。 5777 5778**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5779 5780**参数：** 5781 5782| 参数名 | 类型 | 必填 | 说明 | 5783| -------- | ------------- | ---- | ------------------------------------------------------------ | 5784| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：音频播放中发生错误，触发该事件。 | 5785| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 播放错误事件回调方法。 | 5786 5787**示例：** 5788 5789```ts 5790import { BusinessError } from '@kit.BasicServicesKit'; 5791 5792audioPlayer.on('error', (error: BusinessError) => { //设置'error'事件回调 5793 console.error(`audio error called, error: ${error}`); 5794}); 5795audioPlayer.setVolume(3); //设置volume为无效值，触发'error'事件 5796``` 5797 5798## AudioState<sup>(deprecated)</sup> 5799 5800type AudioState = 'idle' | 'playing' | 'paused' | 'stopped' | 'error' 5801 5802音频播放的状态机。可通过state属性获取当前状态。 5803 5804> **说明：** 5805> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayerState](#avplayerstate9)替代。 5806 5807**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5808 5809| 类型 | 说明 | 5810| ------- | ---------------------------------------------- | 5811| 'idle' | 音频播放空闲，dataload/reset成功后处于此状态。 | 5812| 'playing' | 音频正在播放，play成功后处于此状态。 | 5813| 'paused' | 音频暂停播放，pause成功后处于此状态。 | 5814| 'stopped' | 音频播放停止，stop/播放结束后处于此状态。 | 5815| 'error' | 错误状态。 | 5816 5817## VideoPlayer<sup>(deprecated)</sup> 5818 5819> **说明：** 5820> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer](#avplayer9)替代。 5821 5822视频播放管理类，用于管理和播放视频媒体。在调用VideoPlayer的方法前，需要先通过[createVideoPlayer()](#mediacreatevideoplayerdeprecated)构建一个VideoPlayer实例。 5823 5824### 属性 5825 5826**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5827 5828| 名称 | 类型 | 只读 | 可选 | 说明 | 5829| ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 5830| 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。 | 5831| 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/> | 5832| loop<sup>8+</sup> | boolean | 否 | 否 | 视频循环播放属性，设置为'true'表示循环播放。 | 5833| videoScaleType<sup>9+</sup> | [VideoScaleType](#videoscaletype9) | 否 | 是 | 视频缩放模式。默认值为VIDEO_SCALE_TYPE_FIT。 | 5834| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9) | 否 | 是 | 音频焦点模型。 | 5835| currentTime<sup>8+</sup> | number | 是 | 否 | 视频的当前播放位置，单位为毫秒（ms）。 | 5836| duration<sup>8+</sup> | number | 是 | 否 | 视频时长，单位为毫秒（ms），返回-1表示直播模式。 | 5837| state<sup>8+</sup> | [VideoPlayState](#videoplaystatedeprecated) | 是 | 否 | 视频播放的状态。 | 5838| width<sup>8+</sup> | number | 是 | 否 | 视频宽，单位为像素（px）。 | 5839| height<sup>8+</sup> | number | 是 | 否 | 视频高，单位为像素（px）。 | 5840 5841### setDisplaySurface<sup>(deprecated)</sup> 5842 5843setDisplaySurface(surfaceId: string, callback: AsyncCallback\<void>): void 5844 5845设置SurfaceId。通过回调函数获取返回值。 5846 5847*注意：SetDisplaySurface需要在设置url和Prepare之间，无音频的视频流必须设置Surface否则Prepare失败。 5848 5849> **说明：** 5850> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.surfaceId](#属性)替代。 5851 5852**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5853 5854**参数：** 5855 5856| 参数名 | 类型 | 必填 | 说明 | 5857| --------- | -------------------- | ---- | ------------------------- | 5858| surfaceId | string | 是 | SurfaceId | 5859| callback | AsyncCallback\<void> | 是 | 回调函数。当设置SurfaceId成功，err为undefined，否则为错误对象。 | 5860 5861**示例：** 5862 5863```ts 5864import { BusinessError } from '@kit.BasicServicesKit'; 5865 5866let surfaceId: string = ''; 5867videoPlayer.setDisplaySurface(surfaceId, (err: BusinessError) => { 5868 if (err) { 5869 console.error('Failed to set DisplaySurface!'); 5870 } else { 5871 console.info('Succeeded in setting DisplaySurface!'); 5872 } 5873}); 5874``` 5875 5876### setDisplaySurface<sup>(deprecated)</sup> 5877 5878setDisplaySurface(surfaceId: string): Promise\<void> 5879 5880设置SurfaceId。通过Promise获取返回值。 5881 5882*注意：SetDisplaySurface需要在设置url和Prepare之间，无音频的视频流必须设置Surface否则Prepare失败。 5883 5884> **说明：** 5885> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.surfaceId](#属性)替代。 5886 5887**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5888 5889**参数：** 5890 5891| 参数名 | 类型 | 必填 | 说明 | 5892| --------- | ------ | ---- | --------- | 5893| surfaceId | string | 是 | SurfaceId | 5894 5895**返回值：** 5896 5897| 类型 | 说明 | 5898| -------------- | ------------------------------ | 5899| Promise\<void> | 设置SurfaceId的Promise返回值。 | 5900 5901**示例：** 5902 5903```ts 5904import { BusinessError } from '@kit.BasicServicesKit'; 5905 5906let surfaceId: string = ''; 5907videoPlayer.setDisplaySurface(surfaceId).then(() => { 5908 console.info('Succeeded in setting DisplaySurface'); 5909}).catch((error: BusinessError) => { 5910 console.error(`video catchCallback, error:${error}`); 5911}); 5912``` 5913 5914### prepare<sup>(deprecated)</sup> 5915 5916prepare(callback: AsyncCallback\<void>): void 5917 5918准备播放视频。通过回调函数获取返回值。 5919 5920> **说明：** 5921> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.prepare](#prepare9)替代。 5922 5923**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5924 5925**参数：** 5926 5927| 参数名 | 类型 | 必填 | 说明 | 5928| -------- | -------------------- | ---- | ------------------------ | 5929| callback | AsyncCallback\<void> | 是 | 回调函数。当准备播放视频成功，err为undefined，否则为错误对象。| 5930 5931**示例：** 5932 5933```ts 5934import { BusinessError } from '@kit.BasicServicesKit'; 5935 5936videoPlayer.prepare((err: BusinessError) => { 5937 if (err) { 5938 console.error('Failed to prepare!'); 5939 } else { 5940 console.info('Succeeded in preparing!'); 5941 } 5942}); 5943``` 5944 5945### prepare<sup>(deprecated)</sup> 5946 5947prepare(): Promise\<void> 5948 5949准备播放视频。通过Promise获取返回值。 5950 5951> **说明：** 5952> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.prepare](#prepare9-1)替代。 5953 5954**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5955 5956**返回值：** 5957 5958| 类型 | 说明 | 5959| -------------- | ----------------------------- | 5960| Promise\<void> | 准备播放视频的Promise返回值。 | 5961 5962**示例：** 5963 5964```ts 5965import { BusinessError } from '@kit.BasicServicesKit'; 5966 5967videoPlayer.prepare().then(() => { 5968 console.info('Succeeded in preparing'); 5969}).catch((error: BusinessError) => { 5970 console.error(`video catchCallback, error:${error}`); 5971}); 5972``` 5973 5974### play<sup>(deprecated)</sup> 5975 5976play(callback: AsyncCallback\<void>): void 5977 5978开始播放视频。通过回调函数获取返回值。 5979 5980> **说明：** 5981> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9)替代。 5982 5983**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5984 5985**参数：** 5986 5987| 参数名 | 类型 | 必填 | 说明 | 5988| -------- | -------------------- | ---- | ------------------------ | 5989| callback | AsyncCallback\<void> | 是 | 回调函数。当开始播放视频成功，err为undefined，否则为错误对象。 | 5990 5991**示例：** 5992 5993```ts 5994import { BusinessError } from '@kit.BasicServicesKit'; 5995 5996videoPlayer.play((err: BusinessError) => { 5997 if (err) { 5998 console.error('Failed to play!'); 5999 } else { 6000 console.info('Succeeded in playing!'); 6001 } 6002}); 6003``` 6004 6005### play<sup>(deprecated)</sup> 6006 6007play(): Promise\<void> 6008 6009开始播放视频。通过Promise获取返回值。 6010 6011> **说明：** 6012> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9-1)替代。 6013 6014**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6015 6016**返回值：** 6017 6018| 类型 | 说明 | 6019| -------------- | ----------------------------- | 6020| Promise\<void> | 开始播放视频的Promise返回值。 | 6021 6022**示例：** 6023 6024```ts 6025import { BusinessError } from '@kit.BasicServicesKit'; 6026 6027videoPlayer.play().then(() => { 6028 console.info('Succeeded in playing'); 6029}).catch((error: BusinessError) => { 6030 console.error(`video catchCallback, error:${error}`); 6031}); 6032``` 6033 6034### pause<sup>(deprecated)</sup> 6035 6036pause(callback: AsyncCallback\<void>): void 6037 6038通过回调方式暂停播放视频。通过回调函数获取返回值。 6039 6040> **说明：** 6041> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9)替代。 6042 6043**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6044 6045**参数：** 6046 6047| 参数名 | 类型 | 必填 | 说明 | 6048| -------- | -------------------- | ---- | ------------------------ | 6049| callback | AsyncCallback\<void> | 是 | 回调函数。当暂停播放视频成功，err为undefined，否则为错误对象。 | 6050 6051**示例：** 6052 6053```ts 6054import { BusinessError } from '@kit.BasicServicesKit'; 6055 6056videoPlayer.pause((err: BusinessError) => { 6057 if (err) { 6058 console.error('Failed to pause!'); 6059 } else { 6060 console.info('Succeeded in pausing!'); 6061 } 6062}); 6063``` 6064 6065### pause<sup>(deprecated)</sup> 6066 6067pause(): Promise\<void> 6068 6069暂停播放视频。通过Promise获取返回值。 6070 6071> **说明：** 6072> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9-1)替代。 6073 6074**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6075 6076**返回值：** 6077 6078| 类型 | 说明 | 6079| -------------- | ----------------------------- | 6080| Promise\<void> | 暂停播放视频的Promise返回值。 | 6081 6082**示例：** 6083 6084```ts 6085import { BusinessError } from '@kit.BasicServicesKit'; 6086 6087videoPlayer.pause().then(() => { 6088 console.info('Succeeded in pausing'); 6089}).catch((error: BusinessError) => { 6090 console.error(`video catchCallback, error:${error}`); 6091}); 6092``` 6093 6094### stop<sup>(deprecated)</sup> 6095 6096stop(callback: AsyncCallback\<void>): void 6097 6098通过回调方式停止播放视频。通过回调函数获取返回值。 6099 6100> **说明：** 6101> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9)替代。 6102 6103**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6104 6105**参数：** 6106 6107| 参数名 | 类型 | 必填 | 说明 | 6108| -------- | -------------------- | ---- | ------------------------ | 6109| callback | AsyncCallback\<void> | 是 | 回调函数。当停止播放视频成功，err为undefined，否则为错误对象。 | 6110 6111**示例：** 6112 6113```ts 6114import { BusinessError } from '@kit.BasicServicesKit'; 6115 6116videoPlayer.stop((err: BusinessError) => { 6117 if (err) { 6118 console.error('Failed to stop!'); 6119 } else { 6120 console.info('Succeeded in stopping!'); 6121 } 6122}); 6123``` 6124 6125### stop<sup>(deprecated)</sup> 6126 6127stop(): Promise\<void> 6128 6129停止播放视频。通过Promise获取返回值。 6130 6131> **说明：** 6132> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9-1)替代。 6133 6134**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6135 6136**返回值：** 6137 6138| 类型 | 说明 | 6139| -------------- | ----------------------------- | 6140| Promise\<void> | 停止播放视频的Promise返回值。 | 6141 6142**示例：** 6143 6144```ts 6145import { BusinessError } from '@kit.BasicServicesKit'; 6146 6147videoPlayer.stop().then(() => { 6148 console.info('Succeeded in stopping'); 6149}).catch((error: BusinessError) => { 6150 console.error(`video catchCallback, error:${error}`); 6151}); 6152``` 6153 6154### reset<sup>(deprecated)</sup> 6155 6156reset(callback: AsyncCallback\<void>): void 6157 6158重置播放视频。通过回调函数获取返回值。 6159 6160> **说明：** 6161> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9)替代。 6162 6163**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6164 6165**参数：** 6166 6167| 参数名 | 类型 | 必填 | 说明 | 6168| -------- | -------------------- | ---- | ------------------------ | 6169| callback | AsyncCallback\<void> | 是 | 回调函数。当重置播放视频成功，err为undefined，否则为错误对象。 | 6170 6171**示例：** 6172 6173```ts 6174import { BusinessError } from '@kit.BasicServicesKit'; 6175 6176videoPlayer.reset((err: BusinessError) => { 6177 if (err) { 6178 console.error('Failed to reset!'); 6179 } else { 6180 console.info('Succeeded in resetting!'); 6181 } 6182}); 6183``` 6184 6185### reset<sup>(deprecated)</sup> 6186 6187reset(): Promise\<void> 6188 6189重置播放视频。通过Promise获取返回值。 6190 6191> **说明：** 6192> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9-1)替代。 6193 6194**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6195 6196**返回值：** 6197 6198| 类型 | 说明 | 6199| -------------- | ----------------------------- | 6200| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6201 6202**示例：** 6203 6204```ts 6205import { BusinessError } from '@kit.BasicServicesKit'; 6206 6207videoPlayer.reset().then(() => { 6208 console.info('Succeeded in resetting'); 6209}).catch((error: BusinessError) => { 6210 console.error(`video catchCallback, error:${error}`); 6211}); 6212``` 6213 6214### seek<sup>(deprecated)</sup> 6215 6216seek(timeMs: number, callback: AsyncCallback\<number>): void 6217 6218跳转到指定播放位置，默认跳转到指定时间点的上一个关键帧。通过回调函数获取返回值。 6219 6220> **说明：** 6221> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6222 6223**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6224 6225**参数：** 6226 6227| 参数名 | 类型 | 必填 | 说明 | 6228| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 6229| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6230| callback | AsyncCallback\<number> | 是 | 回调函数。跳转到指定播放位置成功时，err为undefined，data为获取到的跳转到的播放位置，否则为错误对象。 | 6231 6232**示例：** 6233 6234```ts 6235import { BusinessError } from '@kit.BasicServicesKit'; 6236 6237let videoPlayer: media.VideoPlayer; 6238media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6239 if (video != null) { 6240 videoPlayer = video; 6241 console.info('Succeeded in creating VideoPlayer'); 6242 } else { 6243 console.error(`Failed to create VideoPlayer, error:${error}`); 6244 } 6245}); 6246 6247let seekTime: number = 5000; 6248videoPlayer.seek(seekTime, (err: BusinessError, result: number) => { 6249 if (err) { 6250 console.error('Failed to do seek!'); 6251 } else { 6252 console.info('Succeeded in doing seek!'); 6253 } 6254}); 6255``` 6256 6257### seek<sup>(deprecated)</sup> 6258 6259seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\<number>): void 6260 6261跳转到指定播放位置。通过回调函数获取返回值。 6262 6263> **说明：** 6264> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6265 6266**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6267 6268**参数：** 6269 6270| 参数名 | 类型 | 必填 | 说明 | 6271| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 6272| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6273| mode | [SeekMode](#seekmode8) | 是 | 跳转模式。 | 6274| callback | AsyncCallback\<number> | 是 | 回调函数。跳转到指定播放位置成功时，err为undefined，data为获取到的跳转到的播放位置，否则为错误对象。 | 6275 6276**示例：** 6277 6278```ts 6279import { BusinessError } from '@kit.BasicServicesKit'; 6280 6281let videoPlayer: media.VideoPlayer | null = null; 6282media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6283 if (video != null) { 6284 videoPlayer = video; 6285 console.info('Succeeded in creating VideoPlayer'); 6286 } else { 6287 console.error(`Failed to create VideoPlayer, error:${error}`); 6288 } 6289}); 6290let seekTime: number = 5000; 6291if (videoPlayer) { 6292 (videoPlayer as media.VideoPlayer).seek(seekTime, media.SeekMode.SEEK_NEXT_SYNC, (err: BusinessError, result: number) => { 6293 if (err) { 6294 console.error('Failed to do seek!'); 6295 } else { 6296 console.info('Succeeded in doing seek!'); 6297 } 6298 }); 6299} 6300``` 6301 6302### seek<sup>(deprecated)</sup> 6303 6304seek(timeMs: number, mode?:SeekMode): Promise\<number> 6305 6306跳转到指定播放位置，如果没有设置mode则跳转到指定时间点的上一个关键帧。通过Promise获取返回值。 6307 6308> **说明：** 6309> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6310 6311**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6312 6313**参数：** 6314 6315| 参数名 | 类型 | 必填 | 说明 | 6316| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 6317| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6318| mode | [SeekMode](#seekmode8) | 否 | 基于视频I帧的跳转模式，默认为SEEK_PREV_SYNC模式。 | 6319 6320**返回值：** 6321 6322| 类型 | 说明 | 6323| ---------------- | ------------------------------------------- | 6324| Promise\<number> | 跳转到指定播放位置的Promise返回值，单位ms。 | 6325 6326**示例：** 6327 6328```ts 6329import { BusinessError } from '@kit.BasicServicesKit'; 6330 6331let videoPlayer: media.VideoPlayer | null = null; 6332media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6333 if (video != null) { 6334 videoPlayer = video; 6335 console.info('Succeeded in creating VideoPlayer'); 6336 } else { 6337 console.error(`Failed to create VideoPlayer, error:${error}`); 6338 } 6339}); 6340let seekTime: number = 5000; 6341if (videoPlayer) { 6342 (videoPlayer as media.VideoPlayer).seek(seekTime).then((seekDoneTime: number) => { // seekDoneTime表示seek完成后的时间点 6343 console.info('Succeeded in doing seek'); 6344 }).catch((error: BusinessError) => { 6345 console.error(`video catchCallback, error:${error}`); 6346 }); 6347 6348 (videoPlayer as media.VideoPlayer).seek(seekTime, media.SeekMode.SEEK_NEXT_SYNC).then((seekDoneTime: number) => { 6349 console.info('Succeeded in doing seek'); 6350 }).catch((error: BusinessError) => { 6351 console.error(`video catchCallback, error:${error}`); 6352 }); 6353} 6354``` 6355 6356### setVolume<sup>(deprecated)</sup> 6357 6358setVolume(vol: number, callback: AsyncCallback\<void>): void 6359 6360设置音量。通过回调函数获取返回值。 6361 6362> **说明：** 6363> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 6364 6365**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6366 6367**参数：** 6368 6369| 参数名 | 类型 | 必填 | 说明 | 6370| -------- | -------------------- | ---- | ------------------------------------------------------------ | 6371| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 6372| callback | AsyncCallback\<void> | 是 | 回调函数。当设置音量成功，err为undefined，否则为错误对象。 | 6373 6374**示例：** 6375 6376```ts 6377import { BusinessError } from '@kit.BasicServicesKit'; 6378 6379let vol: number = 0.5; 6380videoPlayer.setVolume(vol, (err: BusinessError) => { 6381 if (err) { 6382 console.error('Failed to set Volume!'); 6383 } else { 6384 console.info('Succeeded in setting Volume!'); 6385 } 6386}); 6387``` 6388 6389### setVolume<sup>(deprecated)</sup> 6390 6391setVolume(vol: number): Promise\<void> 6392 6393设置音量。通过Promise获取返回值。 6394 6395> **说明：** 6396> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 6397 6398**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6399 6400**参数：** 6401 6402| 参数名 | 类型 | 必填 | 说明 | 6403| ------ | ------ | ---- | ------------------------------------------------------------ | 6404| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 6405 6406**返回值：** 6407 6408| 类型 | 说明 | 6409| -------------- | ------------------------- | 6410| Promise\<void> | 设置音量的Promise返回值。 | 6411 6412**示例：** 6413 6414```ts 6415import { BusinessError } from '@kit.BasicServicesKit'; 6416 6417let vol: number = 0.5; 6418videoPlayer.setVolume(vol).then(() => { 6419 console.info('Succeeded in setting Volume'); 6420}).catch((error: BusinessError) => { 6421 console.error(`video catchCallback, error:${error}`); 6422}); 6423``` 6424 6425### release<sup>(deprecated)</sup> 6426 6427release(callback: AsyncCallback\<void>): void 6428 6429释放视频资源。通过回调函数获取返回值。 6430 6431> **说明：** 6432> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9)替代。 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.release((err: BusinessError) => { 6448 if (err) { 6449 console.error('Failed to release!'); 6450 } else { 6451 console.info('Succeeded in releasing!'); 6452 } 6453}); 6454``` 6455 6456### release<sup>(deprecated)</sup> 6457 6458release(): Promise\<void> 6459 6460释放视频资源。通过Promise获取返回值。 6461 6462> **说明：** 6463> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9-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.release().then(() => { 6479 console.info('Succeeded in releasing'); 6480}).catch((error: BusinessError) => { 6481 console.error(`video catchCallback, error:${error}`); 6482}); 6483``` 6484 6485### getTrackDescription<sup>(deprecated)</sup> 6486 6487getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 6488 6489获取视频轨道信息。通过回调函数获取返回值。 6490 6491> **说明：** 6492> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9)替代。 6493 6494**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6495 6496**参数：** 6497 6498| 参数名 | 类型 | 必填 | 说明 | 6499| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 6500| callback | AsyncCallback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 回调函数。获取视频轨道信息成功时，err为undefined，data为获取到的视频轨道信息MediaDescription数组，否则为错误对象。 | 6501 6502**示例：** 6503 6504```ts 6505import { BusinessError } from '@kit.BasicServicesKit'; 6506 6507videoPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 6508 if ((arrList) != null) { 6509 console.info('Succeeded in getting TrackDescription'); 6510 } else { 6511 console.error(`Failed to get TrackDescription, error:${error}`); 6512 } 6513}); 6514``` 6515 6516### getTrackDescription<sup>(deprecated)</sup> 6517 6518getTrackDescription(): Promise\<Array\<MediaDescription>> 6519 6520获取视频轨道信息。通过Promise获取返回值。 6521 6522> **说明：** 6523> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9-1)替代。 6524 6525**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6526 6527**返回值：** 6528 6529| 类型 | 说明 | 6530| ------------------------------------------------------ | ----------------------------------------------- | 6531| Promise<Array<[MediaDescription](#mediadescription8)>> | Promise对象，返回获取的视频轨道信息MediaDescription数组。 | 6532 6533**示例：** 6534 6535```ts 6536import { BusinessError } from '@kit.BasicServicesKit'; 6537 6538videoPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 6539 if (arrList != null) { 6540 console.info('Succeeded in getting TrackDescription'); 6541 } else { 6542 console.error('Failed to get TrackDescription'); 6543 } 6544}).catch((error: BusinessError) => { 6545 console.error(`video catchCallback, error:${error}`); 6546}); 6547``` 6548 6549### setSpeed<sup>(deprecated)</sup> 6550 6551setSpeed(speed: number, callback: AsyncCallback\<number>): void 6552 6553设置播放速度。通过回调函数获取返回值。 6554 6555> **说明：** 6556> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setSpeed](#setspeed9)替代。 6557 6558**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6559 6560**参数：** 6561 6562| 参数名 | 类型 | 必填 | 说明 | 6563| -------- | ---------------------- | ---- | ---------------------------------------------------------- | 6564| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 6565| callback | AsyncCallback\<number> | 是 | 回调函数。设置播放速度成功时，err为undefined，data为设置的播放速度，否则为错误对象。 | 6566 6567**示例：** 6568 6569```ts 6570import { BusinessError } from '@kit.BasicServicesKit'; 6571 6572let videoPlayer: media.VideoPlayer | null = null; 6573media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6574 if (video != null) { 6575 videoPlayer = video; 6576 console.info('Succeeded in creating VideoPlayer'); 6577 } else { 6578 console.error(`Failed to create VideoPlayer, error:${error}`); 6579 } 6580}); 6581let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X; 6582if (videoPlayer) { 6583 (videoPlayer as media.VideoPlayer).setSpeed(speed, (err: BusinessError, result: number) => { 6584 if (err) { 6585 console.error('Failed to set Speed!'); 6586 } else { 6587 console.info('Succeeded in setting Speed!'); 6588 } 6589 }); 6590} 6591``` 6592 6593### setSpeed<sup>(deprecated)</sup> 6594 6595setSpeed(speed: number): Promise\<number> 6596 6597设置播放速度。通过Promise获取返回值。 6598 6599> **说明：** 6600> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setSpeed](#setspeed9)替代。 6601 6602**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6603 6604**参数：** 6605 6606| 参数名 | 类型 | 必填 | 说明 | 6607| ------ | ------ | ---- | ---------------------------------------------------------- | 6608| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 6609 6610**返回值：** 6611 6612| 类型 | 说明 | 6613| ---------------- | ------------------------------------------------------------ | 6614| Promise\<number> | Promise对象，返回设置的播放速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 6615 6616**示例：** 6617 6618```ts 6619import { BusinessError } from '@kit.BasicServicesKit'; 6620 6621let videoPlayer: media.VideoPlayer | null = null; 6622media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6623 if (video != null) { 6624 videoPlayer = video; 6625 console.info('Succeeded in creating VideoPlayer'); 6626 } else { 6627 console.error(`Failed to create VideoPlayer, error:${error}`); 6628 } 6629}); 6630let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X; 6631if (videoPlayer) { 6632 (videoPlayer as media.VideoPlayer).setSpeed(speed).then((result: number) => { 6633 console.info('Succeeded in setting Speed'); 6634 }).catch((error: BusinessError) => { 6635 console.error(`Failed to set Speed, error:${error}`);//todo:: error 6636 }); 6637} 6638``` 6639 6640### on('playbackCompleted')<sup>(deprecated)</sup> 6641 6642on(type: 'playbackCompleted', callback: Callback\<void>): void 6643 6644开始监听视频播放完成事件。 6645 6646> **说明：** 6647> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('stateChange')](#onstatechange9)替代。 6648 6649**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6650 6651**参数：** 6652 6653| 参数名 | 类型 | 必填 | 说明 | 6654| -------- | -------- | ---- | ----------------------------------------------------------- | 6655| type | string | 是 | 视频播放完成事件回调类型，支持的事件：'playbackCompleted'。 | 6656| callback | Callback\<void> | 是 | 视频播放完成事件回调方法。 | 6657 6658**示例：** 6659 6660```ts 6661videoPlayer.on('playbackCompleted', () => { 6662 console.info('playbackCompleted called!'); 6663}); 6664``` 6665 6666### on('bufferingUpdate')<sup>(deprecated)</sup> 6667 6668on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void 6669 6670开始监听视频缓存更新事件。仅网络播放支持该订阅事件。 6671 6672> **说明：** 6673> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('bufferingUpdate')](#onbufferingupdate9)替代。 6674 6675**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6676 6677**参数：** 6678 6679| 参数名 | 类型 | 必填 | 说明 | 6680| -------- | -------- | ---- | ------------------------------------------------------------ | 6681| type | string | 是 | 视频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 6682| callback | function | 是 | 视频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)value值固定为0。 | 6683 6684**示例：** 6685 6686```ts 6687videoPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 6688 console.info('video bufferingInfo type: ' + infoType); 6689 console.info('video bufferingInfo value: ' + value); 6690}); 6691``` 6692 6693### on('startRenderFrame')<sup>(deprecated)</sup> 6694 6695on(type: 'startRenderFrame', callback: Callback\<void>): void 6696 6697开始监听视频播放首帧送显上报事件。 6698 6699> **说明：** 6700> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('startRenderFrame')](#onstartrenderframe9)替代。 6701 6702**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6703 6704**参数：** 6705 6706| 参数名 | 类型 | 必填 | 说明 | 6707| -------- | --------------- | ---- | ------------------------------------------------------------ | 6708| type | string | 是 | 视频播放首帧送显上报事件回调类型，支持的事件：'startRenderFrame'。 | 6709| callback | Callback\<void> | 是 | 视频播放首帧送显上报事件回调方法。 | 6710 6711**示例：** 6712 6713```ts 6714videoPlayer.on('startRenderFrame', () => { 6715 console.info('startRenderFrame called!'); 6716}); 6717``` 6718 6719### on('videoSizeChanged')<sup>(deprecated)</sup> 6720 6721on(type: 'videoSizeChanged', callback: (width: number, height: number) => void): void 6722 6723开始监听视频播放宽高变化事件。 6724 6725> **说明：** 6726> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('videoSizeChange')](#onvideosizechange9)替代。 6727 6728**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6729 6730**参数：** 6731 6732| 参数名 | 类型 | 必填 | 说明 | 6733| -------- | -------- | ---- | ------------------------------------------------------------ | 6734| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChanged'。 | 6735| callback | function | 是 | 视频播放宽高变化事件回调方法，width表示宽，height表示高。 | 6736 6737**示例：** 6738 6739```ts 6740videoPlayer.on('videoSizeChanged', (width: number, height: number) => { 6741 console.info('video width is: ' + width); 6742 console.info('video height is: ' + height); 6743}); 6744``` 6745### on('audioInterrupt')<sup>(deprecated)</sup> 6746 6747on(type: 'audioInterrupt', callback: (info: audio.InterruptEvent) => void): void 6748 6749监听音频焦点变化事件，参考[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)。 6750 6751> **说明：** 6752> 从API version 9开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('audioInterrupt')](#onaudiointerrupt9)替代。 6753 6754**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6755 6756**参数：** 6757 6758| 参数名 | 类型 | 必填 | 说明 | 6759| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 6760| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 6761| callback | function | 是 | 音频焦点变化事件回调方法。 | 6762 6763**示例：** 6764 6765```ts 6766import { audio } from '@kit.AudioKit'; 6767 6768videoPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 6769 console.info('audioInterrupt called,and InterruptEvent info is:' + info) 6770}) 6771``` 6772 6773### on('error')<sup>(deprecated)</sup> 6774 6775on(type: 'error', callback: ErrorCallback): void 6776 6777开始监听视频播放错误事件，当上报error错误事件后，用户需处理error事件，退出播放操作。 6778 6779> **说明：** 6780> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('error')](#onerror9)替代。 6781 6782**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6783 6784**参数：** 6785 6786| 参数名 | 类型 | 必填 | 说明 | 6787| -------- | ------------- | ---- | ------------------------------------------------------------ | 6788| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：视频播放中发生错误，触发该事件。 | 6789| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 播放错误事件回调方法。 | 6790 6791**示例：** 6792 6793```ts 6794import { BusinessError } from '@kit.BasicServicesKit'; 6795 6796videoPlayer.on('error', (error: BusinessError) => { // 设置'error'事件回调 6797 console.error(`video error called, error: ${error}`); 6798}); 6799videoPlayer.url = 'fd://error'; //设置错误的播放地址，触发'error'事件 6800``` 6801 6802## VideoPlayState<sup>(deprecated)</sup> 6803 6804type VideoPlayState = 'idle' | 'prepared' | 'playing' | 'paused' | 'stopped' | 'error' 6805 6806视频播放的状态机，可通过state属性获取当前状态。 6807 6808> **说明：** 6809> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayerState](#avplayerstate9)替代。 6810 6811**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6812 6813| 类型 | 说明 | 6814| -------- | -------------- | 6815| 'idle' | 视频播放空闲。 | 6816| 'prepared' | 视频播放准备。 | 6817| 'playing' | 视频正在播放。 | 6818| 'paused' | 视频暂停播放。 | 6819| 'stopped' | 视频播放停止。 | 6820| 'error' | 错误状态。 | 6821 6822## AudioRecorder<sup>(deprecated)</sup> 6823 6824> **说明：** 6825> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder](#avrecorder9)替代。 6826 6827音频录制管理类，用于录制音频媒体。在调用AudioRecorder的方法前，需要先通过[createAudioRecorder()](#mediacreateaudiorecorderdeprecated) 构建一个AudioRecorder实例。 6828 6829### prepare<sup>(deprecated)</sup> 6830 6831prepare(config: AudioRecorderConfig): void 6832 6833录音准备。 6834 6835> **说明：** 6836> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.prepare](#prepare9-2)替代。 6837 6838**需要权限：** ohos.permission.MICROPHONE 6839 6840**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6841 6842**参数：** 6843 6844| 参数名 | 类型 | 必填 | 说明 | 6845| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ | 6846| config | [AudioRecorderConfig](#audiorecorderconfigdeprecated) | 是 | 配置录音的相关参数，包括音频输出URI、编码格式、采样率、声道数、输出格式等。 | 6847 6848**错误码：** 6849 6850以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 6851 6852| 错误码ID | 错误信息 | 6853| -------- | --------------------- | 6854| 201 | permission denied | 6855 6856**示例：** 6857 6858```ts 6859let audioRecorderConfig: media.AudioRecorderConfig = { 6860 audioEncoder : media.AudioEncoder.AAC_LC, 6861 audioEncodeBitRate : 22050, 6862 audioSampleRate : 22050, 6863 numberOfChannels : 2, 6864 format : media.AudioOutputFormat.AAC_ADTS, 6865 uri : 'fd://1', // 文件需先由调用者创建，并给予适当的权限 6866 location : { latitude : 30, longitude : 130}, 6867} 6868audioRecorder.on('prepare', () => { //设置'prepare'事件回调 6869 console.info('prepare called'); 6870}); 6871audioRecorder.prepare(audioRecorderConfig); 6872``` 6873 6874### start<sup>(deprecated)</sup> 6875 6876start(): void 6877 6878开始录制，需在'prepare'事件成功触发后，才能调用start方法。 6879 6880> **说明：** 6881> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.start](#start9)替代。 6882 6883**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6884 6885**示例：** 6886 6887```ts 6888audioRecorder.on('start', () => { //设置'start'事件回调 6889 console.info('audio recorder start called'); 6890}); 6891audioRecorder.start(); 6892``` 6893 6894### pause<sup>(deprecated)</sup> 6895 6896pause():void 6897 6898暂停录制，需要在'start'事件成功触发后，才能调用pause方法。 6899 6900> **说明：** 6901> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.pause](#pause9-2)替代。 6902 6903**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6904 6905**示例：** 6906 6907```ts 6908audioRecorder.on('pause', () => { //设置'pause'事件回调 6909 console.info('audio recorder pause called'); 6910}); 6911audioRecorder.pause(); 6912``` 6913 6914### resume<sup>(deprecated)</sup> 6915 6916resume():void 6917 6918恢复录制，需要在'pause'事件成功触发后，才能调用resume方法。 6919 6920> **说明：** 6921> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.resume](#resume9)替代。 6922 6923**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6924 6925**示例：** 6926 6927```ts 6928audioRecorder.on('resume', () => { //设置'resume'事件回调 6929 console.info('audio recorder resume called'); 6930}); 6931audioRecorder.resume(); 6932``` 6933 6934### stop<sup>(deprecated)</sup> 6935 6936stop(): void 6937 6938停止录音。 6939 6940> **说明：** 6941> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.stop](#stop9-2)替代。 6942 6943**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6944 6945**示例：** 6946 6947```ts 6948audioRecorder.on('stop', () => { //设置'stop'事件回调 6949 console.info('audio recorder stop called'); 6950}); 6951audioRecorder.stop(); 6952``` 6953 6954### release<sup>(deprecated)</sup> 6955 6956release(): void 6957 6958释放录音资源。 6959 6960> **说明：** 6961> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.release](#release9-2)替代。 6962 6963**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6964 6965**示例：** 6966 6967```ts 6968audioRecorder.on('release', () => { //设置'release'事件回调 6969 console.info('audio recorder release called'); 6970}); 6971audioRecorder.release(); 6972audioRecorder = undefined; 6973``` 6974 6975### reset<sup>(deprecated)</sup> 6976 6977reset(): void 6978 6979重置录音。 6980 6981进行重置录音之前，需要先调用stop()停止录音。重置录音之后，需要调用prepare()设置录音参数项，才能再次进行录音。 6982 6983> **说明：** 6984> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.reset](#reset9-2)替代。 6985 6986**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6987 6988**示例：** 6989 6990```ts 6991audioRecorder.on('reset', () => { //设置'reset'事件回调 6992 console.info('audio recorder reset called'); 6993}); 6994audioRecorder.reset(); 6995``` 6996 6997### on('prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset')<sup>(deprecated)</sup> 6998 6999on(type: 'prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset', callback: () => void): void 7000 7001开始订阅音频录制事件。 7002 7003> **说明：** 7004> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.on('stateChange')](#onstatechange9-1)替代。 7005 7006**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7007 7008**参数：** 7009 7010| 参数名 | 类型 | 必填 | 说明 | 7011| -------- | -------- | ---- | ------------------------------------------------------------ | 7012| 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调用，音频重置为初始状态，触发该事件。 | 7013| callback | ()=>void | 是 | 录制事件回调方法。 | 7014 7015**示例：** 7016 7017```ts 7018import { BusinessError } from '@kit.BasicServicesKit'; 7019 7020let audioRecorder: media.AudioRecorder = media.createAudioRecorder(); // 创建一个音频录制实例 7021let audioRecorderConfig: media.AudioRecorderConfig = { 7022 audioEncoder : media.AudioEncoder.AAC_LC, 7023 audioEncodeBitRate : 22050, 7024 audioSampleRate : 22050, 7025 numberOfChannels : 2, 7026 format : media.AudioOutputFormat.AAC_ADTS, 7027 uri : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限 7028 location : { latitude : 30, longitude : 130} 7029} 7030audioRecorder.on('error', (error: BusinessError) => { // 设置'error'事件回调 7031 console.error(`audio error called, error: ${error}`); 7032}); 7033audioRecorder.on('prepare', () => { // 设置'prepare'事件回调 7034 console.info('prepare called'); 7035 audioRecorder.start(); // 开始录制，并触发'start'事件回调 7036}); 7037audioRecorder.on('start', () => { // 设置'start'事件回调 7038 console.info('audio recorder start called'); 7039}); 7040audioRecorder.on('pause', () => { // 设置'pause'事件回调 7041 console.info('audio recorder pause called'); 7042}); 7043audioRecorder.on('resume', () => { // 设置'resume'事件回调 7044 console.info('audio recorder resume called'); 7045}); 7046audioRecorder.on('stop', () => { // 设置'stop'事件回调 7047 console.info('audio recorder stop called'); 7048}); 7049audioRecorder.on('release', () => { // 设置'release'事件回调 7050 console.info('audio recorder release called'); 7051}); 7052audioRecorder.on('reset', () => { // 设置'reset'事件回调 7053 console.info('audio recorder reset called'); 7054}); 7055audioRecorder.prepare(audioRecorderConfig) // 设置录制参数 ，并触发'prepare'事件回调 7056``` 7057 7058### on('error')<sup>(deprecated)</sup> 7059 7060on(type: 'error', callback: ErrorCallback): void 7061 7062开始订阅音频录制错误事件，当上报error错误事件后，用户需处理error事件，退出录制操作。 7063 7064> **说明：** 7065> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.on('error')](#onerror9-1)替代。 7066 7067**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7068 7069**参数：** 7070 7071| 参数名 | 类型 | 必填 | 说明 | 7072| -------- | ------------- | ---- | ------------------------------------------------------------ | 7073| type | string | 是 | 录制错误事件回调类型'error'。<br/>- 'error'：音频录制过程中发生错误，触发该事件。 | 7074| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录制错误事件回调方法。 | 7075 7076**示例：** 7077 7078```ts 7079import { BusinessError } from '@kit.BasicServicesKit'; 7080 7081let audioRecorderConfig: media.AudioRecorderConfig = { 7082 audioEncoder : media.AudioEncoder.AAC_LC, 7083 audioEncodeBitRate : 22050, 7084 audioSampleRate : 22050, 7085 numberOfChannels : 2, 7086 format : media.AudioOutputFormat.AAC_ADTS, 7087 uri : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限 7088 location : { latitude : 30, longitude : 130} 7089} 7090audioRecorder.on('error', (error: BusinessError) => { // 设置'error'事件回调 7091 console.error(`audio error called, error: ${error}`); 7092}); 7093audioRecorder.prepare(audioRecorderConfig); // prepare不设置参数，触发'error'事件 7094``` 7095 7096## AudioRecorderConfig<sup>(deprecated)</sup> 7097 7098> **说明：** 7099> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorderConfig](#avrecorderconfig9)替代。 7100 7101表示音频的录音配置。 7102 7103**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7104 7105| 名称 | 类型 | 必填 | 说明 | 7106| ----------------------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 7107| audioEncoder | [AudioEncoder](#audioencoderdeprecated) | 否 | 音频编码格式，默认设置为AAC_LC。<br/>**说明：** 从API version 8开始废弃，建议使用audioEncoderMime替代。 | 7108| audioEncodeBitRate | number | 否 | 音频编码比特率，默认值为48000。 | 7109| audioSampleRate | number | 否 | 音频采集采样率，默认值为48000。<br>可变比特率模式，码率仅作参考。 | 7110| numberOfChannels | number | 否 | 音频采集声道数，默认值为2。 | 7111| format | [AudioOutputFormat](#audiooutputformatdeprecated) | 否 | 音频输出封装格式，默认设置为MPEG_4。<br/>**说明：** 从API version 8开始废弃，建议使用fileFormat替代。 | 7112| location | [Location](#location) | 否 | 音频采集的地理位置。 | 7113| uri | string | 是 | 音频输出URI：fd://xx (fd number)<br/> <br/>文件需要由调用者创建，并赋予适当的权限。 | 7114| audioEncoderMime<sup>8+</sup> | [CodecMimeType](#codecmimetype8) | 否 | 容器编码格式。 | 7115| fileFormat<sup>8+</sup> | [ContainerFormatType](#containerformattype8) | 否 | 音频编码格式。 | 7116 7117## AudioEncoder<sup>(deprecated)</sup> 7118 7119> **说明：** 7120> 从API version 6开始支持，从API version 8开始废弃，建议使用[CodecMimeType](#codecmimetype8)替代。 7121 7122表示音频编码格式的枚举。 7123 7124**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7125 7126| 名称 | 值 | 说明 | 7127| ------- | ---- | ------------------------------------------------------------ | 7128| DEFAULT | 0 | 默认编码格式。<br/>仅做接口定义，暂不支持使用。 | 7129| AMR_NB | 1 | AMR-NB(Adaptive Multi Rate-Narrow Band Speech Codec) 编码格式。<br/>仅做接口定义，暂不支持使用。 | 7130| AMR_WB | 2 | AMR-WB(Adaptive Multi Rate-Wide Band Speech Codec) 编码格式。<br/>仅做接口定义，暂不支持使用。 | 7131| AAC_LC | 3 | AAC-LC（Advanced Audio Coding Low Complexity）编码格式。 | 7132| HE_AAC | 4 | HE_AAC（High-Efficiency Advanced Audio Coding）编码格式。<br/>仅做接口定义，暂不支持使用。 | 7133 7134## AudioOutputFormat<sup>(deprecated)</sup> 7135 7136> **说明：** 7137> 从API version 6开始支持，从API version 8 开始废弃，建议使用[ContainerFormatType](#containerformattype8)替代。 7138 7139表示音频封装格式的枚举。 7140 7141**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7142 7143| 名称 | 值 | 说明 | 7144| -------- | ---- | ------------------------------------------------------------ | 7145| DEFAULT | 0 | 默认封装格式。<br/>仅做接口定义，暂不支持使用。 | 7146| MPEG_4 | 2 | 封装为MPEG-4格式。 | 7147| AMR_NB | 3 | 封装为AMR_NB格式。<br/>仅做接口定义，暂不支持使用。 | 7148| AMR_WB | 4 | 封装为AMR_WB格式。<br/>仅做接口定义，暂不支持使用。 | 7149| AAC_ADTS | 6 | 封装为ADTS（Audio Data Transport Stream）格式，是AAC音频的传输流格式。 | 7150 7151 7152## media.createAVImageGenerator<sup>12+</sup> 7153 7154createAVImageGenerator(callback: AsyncCallback\<AVImageGenerator>): void 7155 7156创建AVImageGenerator实例，通过回调函数获取返回值。 7157 7158**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7159 7160**参数：** 7161 7162| 参数名 | 类型 | 必填 | 说明 | 7163| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 7164| callback | AsyncCallback\<[AVImageGenerator](#avimagegenerator12)> | 是 | 回调函数。异步返回AVImageGenerator实例，失败时返回null。可用于获取视频缩略图。 | 7165 7166**错误码：** 7167 7168以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7169 7170| 错误码ID | 错误信息 | 7171| -------- | ------------------------------ | 7172| 5400101 | No memory. Returned by callback. | 7173 7174**示例：** 7175 7176```ts 7177import { BusinessError } from '@kit.BasicServicesKit'; 7178 7179let avImageGenerator: media.AVImageGenerator; 7180media.createAVImageGenerator((error: BusinessError, generator: media.AVImageGenerator) => { 7181 if (generator != null) { 7182 avImageGenerator = generator; 7183 console.info('Succeeded in creating AVImageGenerator'); 7184 } else { 7185 console.error(`Failed to creat AVImageGenerator, error message:${error.message}`); 7186 } 7187}); 7188``` 7189 7190## media.createAVImageGenerator<sup>12+</sup> 7191 7192createAVImageGenerator(): Promise\<AVImageGenerator> 7193 7194创建AVImageGenerator对象，通过Promise获取返回值。 7195 7196**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7197 7198**返回值：** 7199 7200| 类型 | 说明 | 7201| ------------------------------- | ------------------------------------------------------------ | 7202| Promise\<[AVImageGenerator](#avimagegenerator12)> | Promise对象。异步返回AVImageGenerator实例，失败时返回null。可用于获取视频缩略图。 | 7203 7204**错误码：** 7205 7206以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7207 7208| 错误码ID | 错误信息 | 7209| -------- | ----------------------------- | 7210| 5400101 | No memory. Returned by promise. | 7211 7212**示例：** 7213 7214```ts 7215import { BusinessError } from '@kit.BasicServicesKit'; 7216 7217let avImageGenerator: media.AVImageGenerator; 7218media.createAVImageGenerator().then((generator: media.AVImageGenerator) => { 7219 if (generator != null) { 7220 avImageGenerator = generator; 7221 console.info('Succeeded in creating AVImageGenerator'); 7222 } else { 7223 console.error('Failed to creat AVImageGenerator'); 7224 } 7225}).catch((error: BusinessError) => { 7226 console.error(`Failed to creat AVImageGenerator, error message:${error.message}`); 7227}); 7228``` 7229 7230## AVImageGenerator<sup>12+</sup> 7231 7232视频缩略图获取类，用于从视频资源中获取缩略图。在调用AVImageGenerator的方法前，需要先通过[createAVImageGenerator()](#mediacreateavimagegenerator12)构建一个AVImageGenerator实例。 7233 7234获取视频缩略图的demo可参考：[获取视频缩略图开发指导](../../media/media/avimagegenerator.md)。 7235 7236### 属性 7237 7238**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7239 7240| 名称 | 类型 | 可读 | 可写 | 说明 | 7241| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 7242| 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。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频缩略图数据获取异常。 | 7243 7244### fetchFrameByTime<sup>12+</sup> 7245 7246fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams, callback: AsyncCallback\<image.PixelMap>): void 7247 7248异步方式获取视频缩略图。通过注册回调函数获取返回值。 7249 7250**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7251 7252**参数：** 7253 7254| 参数名 | 类型 | 必填 | 说明 | 7255| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7256| timeUs | number | 是 | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 | 7257| options | [AVImageQueryOptions](#avimagequeryoptions12) | 是 | 需要获取的缩略图时间点与视频帧的对应关系。 | 7258| param | [PixelMapParams](#pixelmapparams12) | 是 | 需要获取的缩略图的格式参数。 | 7259| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | 回调函数。获取缩略图成功时，err为undefined，data为PixelMap实例，否则为错误对象。 | 7260 7261**错误码：** 7262 7263以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7264 7265| 错误码ID | 错误信息 | 7266| -------- | ------------------------------------------ | 7267| 5400102 | Operation not allowed. Returned by callback. | 7268| 5400106 | Unsupported format. Returned by callback. | 7269 7270**示例：** 7271 7272```ts 7273import { BusinessError } from '@kit.BasicServicesKit'; 7274import { media } from '@kit.MediaKit'; 7275import { image } from '@kit.ImageKit'; 7276 7277let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7278let pixel_map : image.PixelMap | undefined = undefined; 7279 7280// 初始化入参 7281let timeUs: number = 0 7282 7283let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC 7284 7285let param: media.PixelMapParams = { 7286 width : 300, 7287 height : 300, 7288} 7289 7290// 获取缩略图 7291media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7292 if(generator != null){ 7293 avImageGenerator = generator; 7294 console.info(`Succeeded in creating AVImageGenerator`); 7295 avImageGenerator.fetchFrameByTime(timeUs, queryOption, param, (error: BusinessError, pixelMap) => { 7296 if (error) { 7297 console.error(`Failed to fetch FrameByTime, err = ${JSON.stringify(error)}`) 7298 return 7299 } 7300 pixel_map = pixelMap; 7301 }); 7302 } else { 7303 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7304 }; 7305}); 7306``` 7307 7308### fetchFrameByTime<sup>12+</sup> 7309 7310fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams): Promise<image.PixelMap> 7311 7312异步方式获取视频缩略图。通过Promise获取返回值。 7313 7314**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7315 7316**参数：** 7317 7318| 参数名 | 类型 | 必填 | 说明 | 7319| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7320| timeUs | number | 是 | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 | 7321| options | [AVImageQueryOptions](#avimagequeryoptions12) | 是 | 需要获取的缩略图时间点与视频帧的对应关系。 | 7322| param | [PixelMapParams](#pixelmapparams12) | 是 | 需要获取的缩略图的格式参数。 | 7323 7324**返回值：** 7325 7326| 类型 | 说明 | 7327| -------------- | ---------------------------------------- | 7328| Promise\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise对象，返回视频缩略图对象。 | 7329 7330**错误码：** 7331 7332以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7333 7334| 错误码ID | 错误信息 | 7335| -------- | ----------------------------------------- | 7336| 5400102 | Operation not allowed. Returned by promise. | 7337| 5400106 | Unsupported format. Returned by promise. | 7338 7339**示例：** 7340 7341```ts 7342import { BusinessError } from '@kit.BasicServicesKit'; 7343import { media } from '@kit.MediaKit'; 7344import { image } from '@kit.ImageKit'; 7345 7346let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7347let pixel_map : image.PixelMap | undefined = undefined; 7348 7349// 初始化入参 7350let timeUs: number = 0 7351 7352let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC 7353 7354let param: media.PixelMapParams = { 7355 width : 300, 7356 height : 300, 7357} 7358 7359// 获取缩略图 7360media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7361 if(generator != null){ 7362 avImageGenerator = generator; 7363 console.info(`Succeeded in creating AVImageGenerator`); 7364 avImageGenerator.fetchFrameByTime(timeUs, queryOption, param).then((pixelMap: image.PixelMap) => { 7365 pixel_map = pixelMap; 7366 }).catch((error: BusinessError) => { 7367 console.error(`Failed to fetch FrameByTime, error message:${error.message}`); 7368 }); 7369 } else { 7370 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7371 }; 7372}); 7373``` 7374 7375### release<sup>12+</sup> 7376 7377release(callback: AsyncCallback\<void>): void 7378 7379异步方式释放资源。通过注册回调函数获取返回值。 7380 7381**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7382 7383**参数：** 7384 7385| 参数名 | 类型 | 必填 | 说明 | 7386| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7387| callback | AsyncCallback\<void> | 是 | 回调函数。当释放资源成功，err为undefined，否则为错误对象。 | 7388 7389**错误码：** 7390 7391以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7392 7393| 错误码ID | 错误信息 | 7394| -------- | ------------------------------------------ | 7395| 5400102 | Operation not allowed. Returned by callback. | 7396 7397**示例：** 7398 7399```ts 7400import { BusinessError } from '@kit.BasicServicesKit'; 7401import { media } from '@kit.MediaKit'; 7402 7403let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7404 7405//释放资源 7406media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7407 if(generator != null){ 7408 avImageGenerator = generator; 7409 console.info(`Succeeded in creating AVImageGenerator`); 7410 avImageGenerator.release((error: BusinessError) => { 7411 if (error) { 7412 console.error(`Failed to release, err = ${JSON.stringify(error)}`); 7413 return; 7414 } 7415 console.info(`Succeeded in releasing`); 7416 }); 7417 } else { 7418 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7419 }; 7420}); 7421``` 7422 7423### release<sup>12+</sup> 7424 7425release(): Promise\<void> 7426 7427异步方式释放资源。通过Promise获取返回值。 7428 7429**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7430 7431**返回值：** 7432 7433| 类型 | 说明 | 7434| -------------- | ---------------------------------------- | 7435| Promise\<void> | 异步方式释放资源release方法的Promise返回值。 | 7436 7437**错误码：** 7438 7439以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7440 7441| 错误码ID | 错误信息 | 7442| -------- | ----------------------------------------- | 7443| 5400102 | Operation not allowed. Returned by promise. | 7444 7445**示例：** 7446 7447```ts 7448import { BusinessError } from '@kit.BasicServicesKit'; 7449import { media } from '@kit.MediaKit'; 7450 7451let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7452 7453//释放资源 7454media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7455 if(generator != null){ 7456 avImageGenerator = generator; 7457 console.info(`Succeeded in creating AVImageGenerator`); 7458 avImageGenerator.release().then(() => { 7459 console.info(`Succeeded in releasing.`); 7460 }).catch((error: BusinessError) => { 7461 console.error(`Failed to release, error message:${error.message}`); 7462 }); 7463 } else { 7464 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7465 }; 7466}); 7467``` 7468 7469## AVImageQueryOptions<sup>12+</sup> 7470 7471需要获取的缩略图时间点与视频帧的对应关系。 7472 7473在获取视频缩略图时，传入的时间点与实际取得的视频帧所在时间点不一定相等，需要指定传入的时间点与实际取得的视频帧的时间关系。 7474 7475**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7476 7477| 名称 | 值 | 说明 | 7478| ------------------------ | --------------- | ------------------------------------------------------------ | 7479| AV_IMAGE_QUERY_NEXT_SYNC | 0 | 表示选取传入时间点或之后的关键帧。 | 7480| AV_IMAGE_QUERY_PREVIOUS_SYNC | 1 | 表示选取传入时间点或之前的关键帧。 | 7481| AV_IMAGE_QUERY_CLOSEST_SYNC | 2 | 表示选取离传入时间点最近的关键帧。 | 7482| AV_IMAGE_QUERY_CLOSEST | 3 | 表示选取离传入时间点最近的帧，该帧不一定是关键帧。 | 7483 7484## PixelMapParams<sup>12+</sup> 7485 7486获取视频缩略图时，输出缩略图的格式参数。 7487 7488**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7489 7490| 名称 | 类型 | 可读 | 可写 | 说明 | 7491|--------|--------|------|------|---------------------------------------------------------------------------------| 7492| width | number | 是 | 是 | 输出的缩略图宽度。应保证大于0且不大于原始视频宽度。否则返回的缩略图不会进行缩放。 | 7493| height | number | 是 | 是 | 输出的缩略图高度。应保证大于0且不大于原始视频高度。否则返回的缩略图不会进行缩放。 | 7494 7495## media.createMediaSourceWithUrl<sup>12+</sup> 7496 7497createMediaSourceWithUrl(url: string, headers?: Record\<string, string>): MediaSource 7498 7499创建流媒体预下载媒体来源实例方法。 7500 7501**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 7502 7503**系统能力：** SystemCapability.Multimedia.Media.Core 7504 7505**参数：** 7506 7507| 参数名 | 类型 | 必填 | 说明 | 7508| -------- | -------- | ---- | -------------------- | 7509| url | string | 是 | - 流媒体预下载媒体来源url，支持的流媒体格式：HLS、HTTP-FLV、Dash、Https。<br> - 本地m3u8的fd路径。 | 7510| headers | Record\<string, string> | 否 | 支持流媒体预下载HttpHeader自定义。 | 7511 7512**返回值：** 7513 7514| 类型 | 说明 | 7515| -------------- | ------------------------------------------ | 7516| [MediaSource](#mediasource12) | MediaSource返回值。 | 7517 7518**错误码：** 7519 7520以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7521 7522| 错误码ID | 错误信息 | 7523| -------- | ----------------------------------------- | 7524| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 7525| 5400101 | No memory. | 7526 7527**示例1：** 7528 7529```ts 7530import { media } from '@kit.MediaKit'; 7531 7532let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 7533let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 7534``` 7535 7536**示例2：** 7537 7538```ts 7539import { media } from '@kit.MediaKit'; 7540import { common } from '@kit.AbilityKit'; 7541import { resourceManager } from '@kit.LocalizationKit'; 7542 7543let context = getContext(this) as common.UIAbilityContext; 7544let mgr = context.resourceManager; 7545let fileDescriptor = await mgr.getRawFd("xxx.m3u8"); 7546 7547let fd:string = fileDescriptor.fd.toString(); 7548let offset:string = fileDescriptor.offset.toString(); 7549let length:string = fileDescriptor.length.toString(); 7550let fdUrl:string = "fd://" + fd + "?offset=" + offset + "&size=" + length; 7551 7552let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 7553let mediaSource : media.MediaSource = media.createMediaSourceWithUrl(fdUrl, headers); 7554 7555let mimeType : media.AVMimeTypes = media.AVMimeTypes.APPLICATION_M3U8; 7556mediaSource.setMimeType(mimeType); 7557 7558``` 7559 7560## MediaSource<sup>12+</sup> 7561 7562媒体数据信息。来源自[createMediaSourceWithUrl](#mediacreatemediasourcewithurl12)。 7563 7564**系统能力：** SystemCapability.Multimedia.Media.Core 7565 7566### setMimeType<sup>12+</sup> 7567 7568setMimeType(mimeType: AVMimeTypes): void 7569 7570设置媒体MIME类型，以帮助播放器处理扩展的媒体源。 7571 7572**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7573 7574**系统能力：** SystemCapability.Multimedia.Media.Core 7575 7576**参数：** 7577 7578| 参数名 | 类型 | 必填 | 说明 | 7579| -------- | -------- | ---- | -------------------- | 7580| mimeType | [AVMimeTypes](#mediasource12) | 是 | 媒体MIME类型。 | 7581 7582## AVMimeTypes<sup>12+</sup> 7583 7584媒体MIME类型，通过[setMimeType](#setmimetype12)设置。 7585 7586**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7587 7588**系统能力：** SystemCapability.Multimedia.Media.Core 7589 7590 7591| 名称 | 值 | 说明 | 7592| ---------- | ---- | ------------------------------------------------------------ | 7593| APPLICATION_M3U8 | application/m3u8 | 表示m3u8本地文件。 | 7594 7595 7596## PlaybackStrategy<sup>12+</sup> 7597 7598播放策略。 7599 7600**系统能力：** SystemCapability.Multimedia.Media.Core 7601 7602| 名称 | 类型 | 必填 | 说明 | 7603| -------- | -------- | ---- | -------------------- | 7604| preferredWidth| number | 否 | 播放策略首选宽度，int类型，如1080。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 7605| preferredHeight | number | 否 | 播放策略首选高度，int类型，如1920。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 7606| preferredBufferDuration | number | 否 | 播放策略首选缓冲持续时间，单位s，取值范围1-20。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 7607| preferredHdr | boolean | 否 | 播放策略true是hdr，false非hdr，默认非hdr。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 7608| mutedMediaType | [MediaType](#mediatype8) | 否 | 静音播放的媒体类型，仅支持设置 MediaType.MEDIA_TYPE_AUD。 | 7609| preferredAudioLanguage<sup>13+</sup> | string | 否 | 播放策略首选音轨语言。dash场景下应用可按需设置。非dash场景暂不支持，建议缺省。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 7610| preferredSubtitleLanguage<sup>13+</sup> | string | 否 | 播放策略首选字幕语言。dash场景下应用可按需设置。非dash场景暂不支持，建议缺省。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 7611 7612## AVScreenCaptureRecordPreset<sup>12+</sup> 7613 7614进行屏幕录制时的编码、封装格式参数的枚举。 7615 7616**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7617 7618| 名称 | 值 | 说明 | 7619| --------------------------------- | ---- | -------------------------------------------- | 7620| SCREEN_RECORD_PRESET_H264_AAC_MP4 | 0 | 使用视频H264编码，音频AAC编码，MP4封装格式。 | 7621| SCREEN_RECORD_PRESET_H265_AAC_MP4 | 1 | 使用视频H265编码，音频AAC编码，MP4封装格式。 | 7622 7623## AVScreenCaptureStateCode<sup>12+</sup> 7624 7625屏幕录制的状态回调。 7626 7627**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7628 7629| 名称 | 值 | 说明 | 7630| ---------------------------------------- | ---- | ------------------------ | 7631| SCREENCAPTURE_STATE_STARTED | 0 | 录屏已开始。 | 7632| SCREENCAPTURE_STATE_CANCELED | 1 | 录屏被取消。 | 7633| SCREENCAPTURE_STATE_STOPPED_BY_USER | 2 | 录屏被用户手动停止。 | 7634| SCREENCAPTURE_STATE_INTERRUPTED_BY_OTHER | 3 | 录屏被其他录屏打断。 | 7635| SCREENCAPTURE_STATE_STOPPED_BY_CALL | 4 | 录屏被来电打断。 | 7636| SCREENCAPTURE_STATE_MIC_UNAVAILABLE | 5 | 录屏无法使用麦克风收音。 | 7637| SCREENCAPTURE_STATE_MIC_MUTED_BY_USER | 6 | 麦克风被用户关闭。 | 7638| SCREENCAPTURE_STATE_MIC_UNMUTED_BY_USER | 7 | 麦克风被用户打开。 | 7639| SCREENCAPTURE_STATE_ENTER_PRIVATE_SCENE | 8 | 录屏进入隐私页面。 | 7640| SCREENCAPTURE_STATE_EXIT_PRIVATE_SCENE | 9 | 录屏退出隐私页面。 | 7641| SCREENCAPTURE_STATE_STOPPED_BY_USER_SWITCHES | 10 | 系统用户切换，录屏中断。 | 7642 7643## AVScreenCaptureRecordConfig<sup>12+</sup> 7644 7645表示录屏参数配置。 7646 7647**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7648 7649| 名称 | 类型 | 必填 | 说明 | 7650| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 7651| fd | number | 是 | 录制输出的文件fd。 | 7652| frameWidth | number | 否 | 录屏的视频宽度，默认屏幕宽度，根据不同屏幕默认值不同，单位px。 | 7653| frameHeight | number | 否 | 录屏的视频高度，默认屏幕高度，根据不同屏幕默认值不同，单位px。 | 7654| videoBitrate | number | 否 | 录屏的视频比特率，默认10000000。 | 7655| audioSampleRate | number | 否 | 录屏的音频采样率，内录的系统音和外录的麦克风都是用此采样率，默认48000，仅支持设置48000或16000。 | 7656| audioChannelCount | number | 否 | 录屏的音频通道数，内录的系统音和外录的麦克风都是用此通道数，默认2声道，仅支持设置1或2声道。 | 7657| audioBitrate | number | 否 | 录屏的音频比特率，内录的系统音和外录的麦克风都是用此比特率，默认96000。 | 7658| preset | [AVScreenCaptureRecordPreset](#avscreencapturerecordpreset12) | 否 | 录屏使用的编码和封装格式，默认SCREEN_RECORD_PRESET_H264_AAC_MP4格式。 | 7659 7660## AVScreenCaptureRecorder<sup>12+</sup> 7661 7662屏幕录制管理类，用于进行屏幕录制。在调用AVScreenCaptureRecorder的方法前，需要先通过[createAVScreenCaptureRecorder()](#mediacreateavscreencapturerecorder12)创建一个AVScreenCaptureRecorder实例。 7663 7664### init<sup>12+</sup> 7665 7666init(config: AVScreenCaptureRecordConfig): Promise\<void> 7667 7668异步方式进行录屏初始化，设置录屏参数。通过Promise获取返回值。 7669 7670**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7671 7672**参数：** 7673 7674| 参数名 | 类型 | 必填 | 说明 | 7675| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 7676| config | [AVScreenCaptureRecordConfig](#avscreencapturerecordconfig12) | 是 | 配置屏幕录制的相关参数。 | 7677 7678**返回值：** 7679 7680| 类型 | 说明 | 7681| -------------- | ----------------------------------- | 7682| Promise\<void> | 异步录屏初始化方法的Promise返回值。 | 7683 7684**错误码：** 7685 7686| 错误码ID | 错误信息 | 7687| -------- | ---------------------------------------------- | 7688| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 7689| 5400103 | IO error. Return by promise. | 7690| 5400105 | Service died. Return by promise. | 7691 7692**示例：** 7693 7694```ts 7695import { BusinessError } from '@kit.BasicServicesKit'; 7696 7697let avCaptureConfig: media.AVScreenCaptureRecordConfig = { 7698 fd: 0, // 文件需要先有调用者创建，赋予写权限，将文件fd传给此参数 7699 frameWidth: 640, 7700 frameHeight: 480 7701 // 补充其他参数 7702} 7703 7704avScreenCaptureRecorder.init(avCaptureConfig).then(() => { 7705 console.info('Succeeded in initing avScreenCaptureRecorder'); 7706}).catch((err: BusinessError) => { 7707 console.info('Failed to init avScreenCaptureRecorder, error: ' + err.message); 7708}) 7709``` 7710 7711### startRecording<sup>12+</sup> 7712 7713startRecording(): Promise\<void> 7714 7715异步方式开始录屏。通过Promise获取返回值。 7716 7717**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7718 7719**返回值：** 7720 7721| 类型 | 说明 | 7722| -------------- | -------------------------------- | 7723| Promise\<void> | 异步开始录屏方法的Promise返回值. | 7724 7725**错误码：** 7726 7727| 错误码ID | 错误信息 | 7728| -------- | -------------------------------- | 7729| 5400103 | IO error. Return by promise. | 7730| 5400105 | Service died. Return by promise. | 7731 7732**示例：** 7733 7734```ts 7735import { BusinessError } from '@kit.BasicServicesKit'; 7736 7737avScreenCaptureRecorder.startRecording().then(() => { 7738 console.info('Succeeded in starting avScreenCaptureRecorder'); 7739}).catch((err: BusinessError) => { 7740 console.info('Failed to start avScreenCaptureRecorder, error: ' + err.message); 7741}) 7742``` 7743 7744### stopRecording<sup>12+</sup> 7745 7746stopRecording(): Promise\<void> 7747 7748异步方式结束录屏。通过Promise获取返回值。 7749 7750**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7751 7752**返回值：** 7753 7754| 类型 | 说明 | 7755| -------------- | --------------------------------- | 7756| Promise\<void> | 异步结束录屏方法的Promise返回值。 | 7757 7758**错误码：** 7759 7760| 错误码ID | 错误信息 | 7761| -------- | -------------------------------- | 7762| 5400103 | IO error. Return by promise. | 7763| 5400105 | Service died. Return by promise. | 7764 7765**示例：** 7766 7767```ts 7768import { BusinessError } from '@kit.BasicServicesKit'; 7769 7770avScreenCaptureRecorder.stopRecording().then(() => { 7771 console.info('Succeeded in stopping avScreenCaptureRecorder'); 7772}).catch((err: BusinessError) => { 7773 console.info('Failed to stop avScreenCaptureRecorder, error: ' + err.message); 7774}) 7775``` 7776 7777### skipPrivacyMode<sup>12+</sup> 7778 7779skipPrivacyMode(windowIDs: Array\<number>): Promise\<void> 7780 7781录屏时，应用可对本应用的隐私窗口做安全豁免。通过Promise获取返回值。 7782如录屏时，用户在本应用进行输入密码等操作，应用不会进行黑屏处理。 7783 7784**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7785 7786**参数：** 7787 7788| 参数名 | 类型 | 必填 | 说明 | 7789| ------ | ------- | ---- | --------------------------------------------------------- | 7790| windowIDs | Array\<number> | 是 | 需要豁免隐私的窗口列表，包括主窗口id和子窗口id，窗口属性获取方法可以参考[窗口API引用](../apis-arkui/js-apis-window.md#getwindowproperties9) | 7791 7792**返回值：** 7793 7794| 类型 | 说明 | 7795| -------------- | -------------------------------- | 7796| Promise\<void> | 豁免隐私窗口的Promise返回值. | 7797 7798**错误码：** 7799 7800| 错误码ID | 错误信息 | 7801| -------- | -------------------------------- | 7802| 5400103 | IO error. Return by promise. | 7803| 5400105 | Service died. Return by promise. | 7804 7805**示例：** 7806 7807```ts 7808import { BusinessError } from '@kit.BasicServicesKit'; 7809 7810let windowIDs = []; 7811avScreenCaptureRecorder.skipPrivacyMode(windowIDs).then(() => { 7812 console.info('Succeeded in skipping privacy mode'); 7813}).catch((err: BusinessError) => { 7814 console.info('Failed to skip privacy mode, error: ' + err.message); 7815}) 7816``` 7817 7818### setMicEnabled<sup>12+</sup> 7819 7820setMicEnabled(enable: boolean): Promise\<void> 7821 7822异步方式设置麦克风开关。通过Promise获取返回值。 7823 7824**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7825 7826**参数：** 7827 7828| 参数名 | 类型 | 必填 | 说明 | 7829| ------ | ------- | ---- | --------------------------------------------------------- | 7830| enable | boolean | 是 | 麦克风开关控制，true代表麦克风打开，false代表麦克风关闭。 | 7831 7832**返回值：** 7833 7834| 类型 | 说明 | 7835| -------------- | --------------------------------------- | 7836| Promise\<void> | 异步设置麦克风开关方法的Promise返回值。 | 7837 7838**错误码：** 7839 7840| 错误码ID | 错误信息 | 7841| -------- | -------------------------------- | 7842| 5400103 | IO error. Return by promise. | 7843| 5400105 | Service died. Return by promise. | 7844 7845**示例：** 7846 7847```ts 7848import { BusinessError } from '@kit.BasicServicesKit'; 7849 7850avScreenCaptureRecorder.setMicEnabled(true).then(() => { 7851 console.info('Succeeded in setMicEnabled avScreenCaptureRecorder'); 7852}).catch((err: BusinessError) => { 7853 console.info('Failed to setMicEnabled avScreenCaptureRecorder, error: ' + err.message); 7854}) 7855``` 7856 7857### release<sup>12+</sup> 7858 7859release(): Promise\<void> 7860 7861异步方式释放录屏。通过Promise获取返回值。 7862 7863**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7864 7865**返回值：** 7866 7867| 类型 | 说明 | 7868| -------------- | --------------------------------- | 7869| Promise\<void> | 异步释放录屏方法的Promise返回值。 | 7870 7871**错误码：** 7872 7873| 错误码ID | 错误信息 | 7874| -------- | -------------------------------- | 7875| 5400103 | IO error. Return by promise. | 7876| 5400105 | Service died. Return by promise. | 7877 7878**示例：** 7879 7880```ts 7881import { BusinessError } from '@kit.BasicServicesKit'; 7882 7883avScreenCaptureRecorder.release().then(() => { 7884 console.info('Succeeded in releasing avScreenCaptureRecorder'); 7885}).catch((err: BusinessError) => { 7886 console.info('Faile to release avScreenCaptureRecorder, error: ' + err.message); 7887}) 7888``` 7889 7890### on('stateChange')<sup>12+</sup> 7891 7892on(type: 'stateChange', callback: Callback\<AVScreenCaptureStateCode>): void 7893 7894订阅录屏状态切换的事件，当状态发生的时候，会通过订阅的回调通知用户。用户只能订阅一个状态切换的回调方法，重复订阅时，以最后一次订阅的回调接口为准。 7895 7896**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7897 7898**参数：** 7899 7900| 参数名 | 类型 | 必填 | 说明 | 7901| -------- | -------- | ---- | ------------------------------------------------------------ | 7902| type | string | 是 | 状态切换事件回调类型，支持的事件：'stateChange'。 | 7903| callback | function | 是 | 状态切换事件回调方法，[AVScreenCaptureStateCode](#avscreencapturestatecode12)表示切换到的状态。 | 7904 7905**示例：** 7906 7907```ts 7908avScreenCaptureRecorder.on('stateChange', (state: media.AVScreenCaptureStateCode) => { 7909 console.info('avScreenCaptureRecorder stateChange to ' + state); 7910}) 7911``` 7912 7913### on('error')<sup>12+</sup> 7914 7915on(type: 'error', callback: ErrorCallback): void 7916 7917订阅AVScreenCaptureRecorder的错误事件，用户可以根据应用自身逻辑对错误事件进行处理。用户只能订阅一个错误事件的回调方法，重复订阅时，以最后一次订阅的回调接口为准。 7918 7919**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7920 7921**参数：** 7922 7923| 参数名 | 类型 | 必填 | 说明 | 7924| -------- | ------------- | ---- | --------------------------------------- | 7925| type | string | 是 | 错误事件回调类型，支持的事件：'error'。 | 7926| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录屏错误事件回调方法。 | 7927 7928**错误码：** 7929 7930| 错误码ID | 错误信息 | 7931| -------- | -------------------------------- | 7932| 201 | permission denied. | 7933| 5400103 | IO error. Return by ErrorCallback. | 7934| 5400105 | Service died. Return by ErrorCallback. | 7935 7936**示例：** 7937 7938```ts 7939avScreenCaptureRecorder.on('error', (err: BusinessError) => { 7940 console.error('avScreenCaptureRecorder error:' + err.message); 7941}) 7942``` 7943 7944### off('stateChange')<sup>12+</sup> 7945 7946 off(type: 'stateChange', callback?: Callback\<AVScreenCaptureStateCode>): void 7947 7948取消订阅状态切换回调事件。用户可以指定填入状态切换的回调方法来取消订阅。 7949 7950**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7951 7952**参数：** 7953 7954| 参数名 | 类型 | 必填 | 说明 | 7955| -------- | -------- | ---- | ------------------------------------------------------------ | 7956| type | string | 是 | 状态切换事件回调类型，支持的事件：'stateChange'。 | 7957| callback | function | 否 | 状态切换事件回调方法，[AVScreenCaptureStateCode](#avscreencapturestatecode12)表示切换到的状态，不填此参数则会取消最后一次订阅事件。 | 7958 7959**示例：** 7960 7961```ts 7962avScreenCaptureRecorder.off('stateChange'); 7963``` 7964 7965### off('error')<sup>12+</sup> 7966 7967off(type: 'error', callback?: ErrorCallback): void 7968 7969取消订阅错误回调事件。用户可以指定填入错误回调方法来取消订阅。 7970 7971**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7972 7973**参数：** 7974 7975| 参数名 | 类型 | 必填 | 说明 | 7976| -------- | -------- | ---- | ---------------------------------------------------------- | 7977| type | string | 是 | 状态切换事件回调类型，支持的事件：'error'。 | 7978| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 录屏错误事件回调方法，不填此参数则会取消最后一次订阅事件。 | 7979 7980**示例：** 7981 7982```ts 7983avScreenCaptureRecorder.off('error'); 7984```
