1# @ohos.multimedia.media (媒体服务) 2 3> **说明：** 4> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 5 6媒体子系统为开发者提供一套简单且易于理解的接口，使得开发者能够方便接入系统并使用系统的媒体资源。 7 8媒体子系统包含了音视频相关媒体业务，提供以下常用功能： 9 10- 音视频播放（[AVPlayer](#avplayer9)<sup>9+</sup>） 11 12- 音视频录制（[AVRecorder](#avrecorder9)<sup>9+</sup>） 13 14- 视频转码（[AVTranscoder](#avtranscoder12)<sup>12+</sup>） 15 16- 获取音视频元数据（[AVMetadataExtractor](#avmetadataextractor11)<sup>11+</sup>） 17 18- 获取视频缩略图（[AVImageGenerator](#avimagegenerator12)<sup>12+</sup>） 19 20- 屏幕录制（[AVScreenCaptureRecorder](#avscreencapturerecorder12)<sup>12+</sup>） 21 22## 导入模块 23 24```ts 25import { media } from '@kit.MediaKit'; 26``` 27 28## media.createAVPlayer<sup>9+</sup> 29 30createAVPlayer(callback: AsyncCallback\<AVPlayer>): void 31 32异步方式创建音视频播放实例，通过注册回调函数获取返回值。 33 34> **说明：** 35> 36> - 推荐单个应用创建的音视频播放实例（即音频、视频、音视频三类相加）不超过16个。<!--Del--> 37> - 可创建的音视频播放实例数量依赖于设备芯片的支持情况，如芯片支持创建的数量少于上述情况，请以芯片规格为准。如RK3568推荐单个应用创建6个以内的音视频播放实例。<!--DelEnd--> 38 39**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 42 43**参数：** 44 45| 参数名 | 类型 | 必填 | 说明 | 46| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 47| callback | AsyncCallback\<[AVPlayer](#avplayer9)> | 是 | 回调函数。异步返回AVPlayer实例，失败时返回null。可用于音视频播放。 | 48 49**错误码：** 50 51以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 52 53| 错误码ID | 错误信息 | 54| -------- | ------------------------------ | 55| 5400101 | No memory. Return by callback. | 56 57**示例：** 58 59```ts 60import { BusinessError } from '@kit.BasicServicesKit'; 61 62let avPlayer: media.AVPlayer; 63media.createAVPlayer((error: BusinessError, video: media.AVPlayer) => { 64 if (video != null) { 65 avPlayer = video; 66 console.info('Succeeded in creating AVPlayer'); 67 } else { 68 console.error(`Failed to create AVPlayer, error message:${error.message}`); 69 } 70}); 71``` 72 73## media.createAVPlayer<sup>9+</sup> 74 75createAVPlayer(): Promise\<AVPlayer> 76 77异步方式创建音视频播放实例，通过Promise获取返回值。 78 79> **说明：** 80> 81> - 推荐单个应用创建的音视频播放实例（即音频、视频、音视频三类相加）不超过16个。<!--Del--> 82> - 可创建的音视频播放实例数量依赖于设备芯片的支持情况，如芯片支持创建的数量少于上述情况，请以芯片规格为准。如RK3568推荐单个应用创建6个以内的音视频播放实例。<!--DelEnd--> 83 84**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 85 86**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 87 88**返回值：** 89 90| 类型 | 说明 | 91| ------------------------------- | ------------------------------------------------------------ | 92| Promise\<[AVPlayer](#avplayer9)> | Promise对象。异步返回AVPlayer实例，失败时返回null。可用于音视频播放。 | 93 94**错误码：** 95 96以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 97 98| 错误码ID | 错误信息 | 99| -------- | ----------------------------- | 100| 5400101 | No memory. Return by promise. | 101 102**示例：** 103 104```ts 105import { BusinessError } from '@kit.BasicServicesKit'; 106 107let avPlayer: media.AVPlayer; 108media.createAVPlayer().then((video: media.AVPlayer) => { 109 if (video != null) { 110 avPlayer = video; 111 console.info('Succeeded in creating AVPlayer'); 112 } else { 113 console.error('Failed to create AVPlayer'); 114 } 115}).catch((error: BusinessError) => { 116 console.error(`Failed to create AVPlayer, error message:${error.message}`); 117}); 118``` 119 120## media.createAVRecorder<sup>9+</sup> 121 122createAVRecorder(callback: AsyncCallback\<AVRecorder>): void 123 124异步方式创建音视频录制实例。通过注册回调函数获取返回值。 125 126> **说明：** 127> 128> 应用可创建多个音视频录制实例，但由于设备共用音频通路，一个设备仅能有一个实例进行音频录制。创建第二个实例录制音频时，将会因为音频通路冲突导致创建失败。 129 130**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 131 132**参数：** 133 134| 参数名 | 类型 | 必填 | 说明 | 135| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 136| callback | AsyncCallback\<[AVRecorder](#avrecorder9)> | 是 | 回调函数。异步返回AVRecorder实例，失败时返回null。可用于录制音视频媒体。 | 137 138**错误码：** 139 140以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 141 142| 错误码ID | 错误信息 | 143| -------- | ------------------------------ | 144| 5400101 | No memory. Return by callback. | 145 146**示例：** 147 148```ts 149import { BusinessError } from '@kit.BasicServicesKit'; 150let avRecorder: media.AVRecorder; 151 152media.createAVRecorder((error: BusinessError, recorder: media.AVRecorder) => { 153 if (recorder != null) { 154 avRecorder = recorder; 155 console.info('Succeeded in creating AVRecorder'); 156 } else { 157 console.error(`Failed to create AVRecorder, error message:${error.message}`); 158 } 159}); 160``` 161 162## media.createAVRecorder<sup>9+</sup> 163 164createAVRecorder(): Promise\<AVRecorder> 165 166异步方式创建音视频录制实例。通过Promise获取返回值。 167 168> **说明：** 169> 170> 应用可创建多个音视频录制实例，但由于设备共用音频通路，一个设备仅能有一个实例进行音频录制。创建第二个实例录制音频时，将会因为音频通路冲突导致创建失败。 171 172**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 173 174**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 175 176**返回值：** 177 178| 类型 | 说明 | 179| ------------------------------------ | ------------------------------------------------------------ | 180| Promise\<[AVRecorder](#avrecorder9)> | Promise对象。异步返回AVRecorder实例，失败时返回null。可用于录制音视频媒体。 | 181 182**错误码：** 183 184以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 185 186| 错误码ID | 错误信息 | 187| -------- | ----------------------------- | 188| 5400101 | No memory. Return by promise. | 189 190**示例：** 191 192```ts 193import { BusinessError } from '@kit.BasicServicesKit'; 194 195let avRecorder: media.AVRecorder; 196media.createAVRecorder().then((recorder: media.AVRecorder) => { 197 if (recorder != null) { 198 avRecorder = recorder; 199 console.info('Succeeded in creating AVRecorder'); 200 } else { 201 console.error('Failed to create AVRecorder'); 202 } 203}).catch((error: BusinessError) => { 204 console.error(`Failed to create AVRecorder, error message:${error.message}`); 205}); 206``` 207 208## media.createAVTranscoder<sup>12+</sup> 209 210createAVTranscoder(): Promise\<AVTranscoder> 211 212异步方式创建视频转码实例，通过Promise获取返回值。 213 214> **说明：** 215 216> 可创建的视频转码实例不能超过2个。 217 218**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 219 220**返回值：** 221 222| 类型 | 说明 | 223| ------------------------------- | ------------------------------------------------------------ | 224| Promise\<[AVTranscoder](#avtranscoder12)> | Promise对象。异步返回AVTranscoder实例，失败时返回null。可用于视频转码。 | 225 226**错误码：** 227 228以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 229 230| 错误码ID | 错误信息 | 231| -------- | ----------------------------- | 232| 5400101 | No memory. Return by promise. | 233 234**示例：** 235 236```ts 237import { BusinessError } from '@kit.BasicServicesKit'; 238 239let avTranscoder: media.AVTranscoder; 240media.createAVTranscoder().then((transcoder: media.AVTranscoder) => { 241 if (transcoder != null) { 242 avTranscoder = transcoder; 243 console.info('Succeeded in creating AVTranscoder'); 244 } else { 245 console.error('Failed to create AVTranscoder'); 246 } 247}).catch((error: BusinessError) => { 248 console.error(`Failed to create AVTranscoder, error message:${error.message}`); 249}); 250``` 251 252## media.createAVMetadataExtractor<sup>11+</sup> 253 254createAVMetadataExtractor(callback: AsyncCallback\<AVMetadataExtractor>): void 255 256异步方式创建AVMetadataExtractor实例，通过注册回调函数获取返回值。 257 258**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 259 260**参数：** 261 262| 参数名 | 类型 | 必填 | 说明 | 263| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 264| callback | AsyncCallback\<[AVMetadataExtractor](#avmetadataextractor11)> | 是 | 回调函数。当创建AVMetadataExtractor实例成功，err为undefined，data为获取到的AVMetadataExtractor实例，否则为错误对象。 | 265 266**错误码：** 267 268以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 269 270| 错误码ID | 错误信息 | 271| -------- | ------------------------------ | 272| 5400101 | No memory. Returned by callback. | 273 274**示例：** 275 276```ts 277import { BusinessError } from '@kit.BasicServicesKit'; 278 279let avMetadataExtractor: media.AVMetadataExtractor; 280media.createAVMetadataExtractor((error: BusinessError, extractor: media.AVMetadataExtractor) => { 281 if (extractor != null) { 282 avMetadataExtractor = extractor; 283 console.info('Succeeded in creating AVMetadataExtractor'); 284 } else { 285 console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`); 286 } 287}); 288``` 289 290## media.createAVMetadataExtractor<sup>11+</sup> 291 292createAVMetadataExtractor(): Promise\<AVMetadataExtractor> 293 294异步方式创建AVMetadataExtractor实例，通过Promise获取返回值。 295 296**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 297 298**错误码：** 299 300以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 301 302| 错误码ID | 错误信息 | 303| -------- | ------------------------------ | 304| 5400101 | No memory. Returned by promise. | 305 306**示例：** 307 308```ts 309import { BusinessError } from '@kit.BasicServicesKit'; 310 311let avMetadataExtractor: media.AVMetadataExtractor; 312media.createAVMetadataExtractor().then((extractor: media.AVMetadataExtractor) => { 313 if (extractor != null) { 314 avMetadataExtractor = extractor; 315 console.info('Succeeded in creating AVMetadataExtractor'); 316 } else { 317 console.error(`Failed to create AVMetadataExtractor`); 318 } 319}).catch((error: BusinessError) => { 320 console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`); 321}); 322``` 323 324## media.createSoundPool<sup>10+</sup> 325 326createSoundPool(maxStreams: number, audioRenderInfo: audio.AudioRendererInfo, callback: AsyncCallback\<SoundPool>): void 327 328创建音频池实例，使用callback方式异步获取返回值。 329 330**系统能力：** SystemCapability.Multimedia.Media.SoundPool 331 332**参数：** 333 334| 参数名 | 类型 | 必填 | 说明 | 335| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 336| maxStreams | number | 是 | soundPool实例的最大播放的流数 | 337| 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播放短音时为混音模式，不会打断其他音频播放。 | 338| callback | AsyncCallback<[SoundPool](js-apis-inner-multimedia-soundPool.md)> | 是 | 回调函数。异步返回SoundPool实例，失败时返回null。用于音频池实例的加载播放功能。 | 339 340**错误码：** 341 342以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 343 344| 错误码ID | 错误信息 | 345| -------- | ------------------------------ | 346| 5400101 | No memory. Return by callback. | 347 348**示例：** 349 350```js 351import { audio } from '@kit.AudioKit'; 352 353let soundPool: media.SoundPool; 354let audioRendererInfo: audio.AudioRendererInfo = { 355 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 356 rendererFlags : 0 357} 358 359media.createSoundPool(5, audioRendererInfo, (error, soundPool_: media.SoundPool) => { 360 if (error) { 361 console.error(`Failed to createSoundPool`) 362 return; 363 } else { 364 soundPool = soundPool_; 365 console.info(`Succeeded in createSoundPool`) 366 } 367}); 368``` 369 370## media.createSoundPool<sup>10+</sup> 371 372createSoundPool(maxStreams: number, audioRenderInfo: audio.AudioRendererInfo): Promise\<SoundPool> 373 374创建音频池实例，通过Promise获取返回值。 375 376**系统能力：** SystemCapability.Multimedia.Media.SoundPool 377 378**参数：** 379 380| 参数名 | 类型 | 必填 | 说明 | 381| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 382| maxStreams | number | 是 | soundPool实例的最大播放的流数 | 383| audioRenderInfo | [audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8) | 是 | 音频播放参数信息 | 384 385**返回值：** 386 387| 类型 | 说明 | 388| ----------------------------------------- | ------------------------------------------------------------ | 389| Promise<[SoundPool](js-apis-inner-multimedia-soundPool.md)> | Promise对象。异步返回SoundPool实例，失败时返回null。用于音频池实例的加载播放功能。 | 390 391**错误码：** 392 393以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 394 395| 错误码ID | 错误信息 | 396| -------- | ----------------------------- | 397| 5400101 | No memory. Return by promise. | 398 399**示例：** 400 401```js 402import { audio } from '@kit.AudioKit'; 403import { BusinessError } from '@kit.BasicServicesKit'; 404 405let soundPool: media.SoundPool; 406let audioRendererInfo: audio.AudioRendererInfo = { 407 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 408 rendererFlags : 0 409} 410 411media.createSoundPool(5, audioRendererInfo).then((soundpool_: media.SoundPool) => { 412 if (soundpool_ != null) { 413 soundPool = soundpool_; 414 console.info('Succceeded in creating SoundPool'); 415 } else { 416 console.error('Failed to create SoundPool'); 417 } 418}, (error: BusinessError) => { 419 console.error(`soundpool catchCallback, error message:${error.message}`); 420}); 421``` 422 423## media.createAVScreenCaptureRecorder<sup>12+</sup> 424 425createAVScreenCaptureRecorder(): Promise\<AVScreenCaptureRecorder> 426 427创建屏幕录制实例，通过Promise获取返回值。 428 429**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 430 431**返回值：** 432 433| 类型 | 说明 | 434| ------------------------------------------------------------ | ------------------------------------------------------------ | 435| Promise\<[AVScreenCaptureRecorder](#avscreencapturerecorder12)> | Promise对象。异步返回AVScreenCaptureRecorder实例，失败时返回null。可用于进行屏幕录制。 | 436 437**错误码：** 438 439| 错误码ID | 错误信息 | 440| -------- | ------------------------------ | 441| 5400101 | No memory. Return by promise. | 442 443**示例：** 444 445```ts 446import { BusinessError } from '@kit.BasicServicesKit'; 447 448let avScreenCaptureRecorder: media.AVScreenCaptureRecorder; 449media.createAVScreenCaptureRecorder().then((captureRecorder: media.AVScreenCaptureRecorder) => { 450 if (captureRecorder != null) { 451 avScreenCaptureRecorder = captureRecorder; 452 console.info('Succeeded in createAVScreenCaptureRecorder'); 453 } else { 454 console.error('Failed to createAVScreenCaptureRecorder'); 455 } 456}).catch((error: BusinessError) => { 457 console.error(`createAVScreenCaptureRecorder catchCallback, error message:${error.message}`); 458}); 459``` 460 461## SoundPool<sup>10+</sup> 462 463type SoundPool = _SoundPool 464 465音频池，提供了系统声音的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能。 466 467**系统能力：** SystemCapability.Multimedia.Media.SoundPool 468 469| 类型 | 说明 | 470| -------- | ------------------------------ | 471| [_SoundPool](js-apis-inner-multimedia-soundPool.md#soundpool) | 音频池，提供了系统声音的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能。 | 472 473## PlayParameters<sup>10+</sup> 474 475type PlayParameters = _PlayParameters 476 477表示音频池播放参数设置。 478 479**系统能力：** SystemCapability.Multimedia.Media.SoundPool 480 481| 类型 | 说明 | 482| -------- | ------------------------------ | 483| [_PlayParameters](js-apis-inner-multimedia-soundPool.md#playparameters) | 表示音频池播放参数设置。 | 484 485## AVErrorCode<sup>9+</sup> 486 487[媒体错误码](errorcode-media.md)类型枚举 488 489**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 490 491**系统能力：** SystemCapability.Multimedia.Media.Core 492 493| 名称 | 值 | 说明 | 494| :------------------------------------ | ------- | ------------------------------------ | 495| AVERR_OK | 0 | 表示操作成功。 | 496| AVERR_NO_PERMISSION | 201 | 表示无权限执行此操作。 | 497| AVERR_INVALID_PARAMETER | 401 | 表示传入入参无效。 | 498| AVERR_UNSUPPORT_CAPABILITY | 801 | 表示当前版本不支持该API能力。 | 499| AVERR_NO_MEMORY | 5400101 | 表示系统内存不足或服务数量达到上限。 | 500| AVERR_OPERATE_NOT_PERMIT | 5400102 | 表示当前状态不允许或无权执行此操作。 | 501| AVERR_IO | 5400103 | 表示数据流异常信息。 | 502| AVERR_TIMEOUT | 5400104 | 表示系统或网络响应超时。 | 503| AVERR_SERVICE_DIED | 5400105 | 表示服务进程死亡。 | 504| AVERR_UNSUPPORT_FORMAT | 5400106 | 表示不支持当前媒体资源的格式。 | 505| AVERR_AUDIO_INTERRUPTED<sup>11+</sup> | 5400107 | 表示音频焦点被抢占 | 506| AVERR_IO_HOST_NOT_FOUND<sup>14+</sup> | 5411001 | 表示解析或链接服务端地址错误。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 507| AVERR_IO_CONNECTION_TIMEOUT<sup>14+</sup> | 5411002 | 表示网络连接超时。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 508| AVERR_IO_NETWORK_ABNORMAL<sup>14+</sup> | 5411003 | 表示网络异常导致的数据或链路异常。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 509| AVERR_IO_NETWORK_UNAVAILABLE<sup>14+</sup> | 5411004 | 表示网络被禁用。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 510| AVERR_IO_NO_PERMISSION<sup>14+</sup> | 5411005 | 表示无访问权限。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 511| AVERR_IO_REQUEST_DENIED<sup>14+</sup> | 5411006 | 表示客户端请求参数错误或超出处理能力。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 512| AVERR_IO_RESOURCE_NOT_FOUND<sup>14+</sup> | 5411007 | 表示无可用网络资源。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 513| AVERR_IO_SSL_CLIENT_CERT_NEEDED<sup>14+</sup> | 5411008 | 表示服务端校验客户端证书失败。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 514| AVERR_IO_SSL_CONNECTION_FAILED<sup>14+</sup> | 5411009 | 表示SSL连接失败。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 515| AVERR_IO_SSL_SERVER_CERT_UNTRUSTED<sup>14+</sup> | 5411010 | 表示客户端校验服务端证书失败。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 516| AVERR_IO_UNSUPPORTED_REQUEST<sup>14+</sup> | 5411011 | 表示网络协议的原因导致请求不受支持。 <br> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 517 518## MediaType<sup>8+</sup> 519 520媒体类型枚举。 521 522**系统能力：** SystemCapability.Multimedia.Media.Core 523 524| 名称 | 值 | 说明 | 525| -------------- | --------------------- | ------------------- | 526| MEDIA_TYPE_AUD | 0 | 表示音频。 <br> **原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 | 527| MEDIA_TYPE_VID | 1 | 表示视频。 <br> **原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 | 528| MEDIA_TYPE_SUBTITLE<sup>12+</sup> | 2 | 表示字幕。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 529 530## CodecMimeType<sup>8+</sup> 531 532Codec MIME类型枚举。 533 534**系统能力：** SystemCapability.Multimedia.Media.Core 535 536| 名称 | 值 | 说明 | 537| ------------ | --------------------- | ------------------------ | 538| VIDEO_H263 | 'video/h263' | 表示视频/h263类型。 | 539| VIDEO_AVC | 'video/avc' | 表示视频/avc类型。 | 540| VIDEO_MPEG2 | 'video/mpeg2' | 表示视频/mpeg2类型。 | 541| VIDEO_MPEG4 | 'video/mp4v-es' | 表示视频/mpeg4类型。 | 542| VIDEO_VP8 | 'video/x-vnd.on2.vp8' | 表示视频/vp8类型。 | 543| VIDEO_HEVC<sup>11+</sup> | 'video/hevc' | 表示视频/H265类型。| 544| AUDIO_AAC | 'audio/mp4a-latm' | 表示音频/mp4a-latm类型。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 545| AUDIO_VORBIS | 'audio/vorbis' | 表示音频/vorbis类型。 | 546| AUDIO_FLAC | 'audio/flac' | 表示音频/flac类型。 | 547| AUDIO_MP3<sup>12+</sup> | 'audio/mpeg' | 表示音频/mpeg类型。 | 548| AUDIO_G711MU<sup>12+</sup> | 'audio/g711mu' | 表示音频/G711-mulaw类型。 | 549 550## MediaDescriptionKey<sup>8+</sup> 551 552媒体信息描述枚举。 553 554**系统能力：** SystemCapability.Multimedia.Media.Core 555 556| 名称 | 值 | 说明 | 557| ------------------------ | --------------- | ------------------------------------------------------------ | 558| MD_KEY_TRACK_INDEX | 'track_index' | 表示轨道序号，其对应键值类型为number。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 559| MD_KEY_TRACK_TYPE | 'track_type' | 表示轨道类型，其对应键值类型为number，参考[MediaType](#mediatype8)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 560| MD_KEY_CODEC_MIME | 'codec_mime' | 表示codec_mime类型，其对应键值类型为string。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 561| MD_KEY_DURATION | 'duration' | 表示媒体时长，其对应键值类型为number，单位为毫秒（ms）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 562| MD_KEY_BITRATE | 'bitrate' | 表示比特率，其对应键值类型为number，单位为比特率（bps）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 563| MD_KEY_WIDTH | 'width' | 表示视频宽度，其对应键值类型为number，单位为像素（px）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 564| MD_KEY_HEIGHT | 'height' | 表示视频高度，其对应键值类型为number，单位为像素（px）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 565| MD_KEY_FRAME_RATE | 'frame_rate' | 表示视频帧率，其对应键值类型为number，单位为每100秒的帧数。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 566| MD_KEY_AUD_CHANNEL_COUNT | 'channel_count' | 表示声道数，其对应键值类型为number。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 567| MD_KEY_AUD_SAMPLE_RATE | 'sample_rate' | 表示采样率，其对应键值类型为number，单位为赫兹（Hz）。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 568| MD_KEY_AUD_SAMPLE_DEPTH<sup>12+</sup> | 'sample_depth' | 表示位深，其对应键值类型为number，单位为位（bit）。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 569| MD_KEY_LANGUAGE<sup>12+</sup> | 'language' | 表示字幕语言，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 570| MD_KEY_TRACK_NAME<sup>12+</sup> | 'track_name' | 表示track名称，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 571| MD_KEY_HDR_TYPE<sup>12+</sup> | 'hdr_type' | 表示视频轨类型，其对应键值类型为string。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 572 573## PlaybackInfoKey<sup>12+</sup> 574 575播放信息描述枚举。 576 577**系统能力：** SystemCapability.Multimedia.Media.Core 578 579| 名称 | 值 | 说明 | 580| ------------------------ | --------------- | ------------------------------------------------------------ | 581| SERVER_IP_ADDRESS | 'server_ip_address' | 表示服务器IP地址，其对应键值类型为string。 | 582| AVG_DOWNLOAD_RATE | 'average_download_rate'| 表示平均下载速率，其对应键值类型为number，单位为比特率（bps）。 | 583| DOWNLOAD_RATE | 'download_rate' | 表示1s的下载速率，其对应键值类型为number，单位为比特率（bps）。| 584| IS_DOWNLOADING | 'is_downloading' | 表示下载状态，1表示在下载状态，0表示非下载状态（下载完成），其对应键值类型为number。| 585| BUFFER_DURATION | 'buffer_duration' | 表示缓存数据的可播放时长，其对应键值类型为number，单位为秒（s）。| 586 587## BufferingInfoType<sup>8+</sup> 588 589缓存事件类型枚举。 590 591**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 592 593**系统能力：** SystemCapability.Multimedia.Media.Core 594 595| 名称 | 值 | 说明 | 596| ----------------- | ---- | -------------------------------- | 597| BUFFERING_START | 1 | 表示开始缓冲。当上报BUFFERING_START时，播放器会暂停播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 598| BUFFERING_END | 2 | 表示结束缓冲。当上报BUFFERING_END时，播放器会恢复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 599| BUFFERING_PERCENT | 3 | 表示缓冲百分比。可参考该事件感知缓冲进度。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 600| CACHED_DURATION | 4 | 表示已缓冲数据预估可播放时长，单位为毫秒（ms）。缓冲区中的数据变化量大于500ms，上报一次。可参考该事件做进度条。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 601 602## StateChangeReason<sup>9+</sup> 603 604表示播放或录制实例状态机切换原因的枚举，伴随state一起上报。 605 606**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 607 608**系统能力：** SystemCapability.Multimedia.Media.Core 609 610| 名称 | 值 | 说明 | 611| ---------- | ---- | ------------------------------------------------------------ | 612| USER | 1 | 表示用户行为造成的状态切换，由用户或客户端主动调用接口产生。 | 613| BACKGROUND | 2 | 表示后台系统行为造成的状态切换，比如应用未注册播控中心权限，退到后台时被系统强制暂停或停止。 | 614 615## AVPlayer<sup>9+</sup> 616 617播放管理类，用于管理和播放媒体资源。在调用AVPlayer的方法前，需要先通过[createAVPlayer()](#mediacreateavplayer9)构建一个AVPlayer实例。 618 619Audio/Video播放demo可参考：[音频播放开发指导](../../media/media/using-avplayer-for-playback.md)、[视频播放开发指导](../../media/media/video-playback.md)。 620 621> **说明：** 622> 623> 在使用AVPlayer实例的方法时，建议开发者注册相关回调，主动获取当前状态变化。 624> - [on('stateChange')](#onstatechange9)：监听播放状态机AVPlayerState切换。 625> - [on('error')](#onerror9)：监听错误事件。 626 627### 属性 628 629**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 630 631| 名称 | 类型 | 只读 | 可选 | 说明 | 632| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 633| 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开始，该接口支持在原子化服务中使用。 | 634| 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开始，该接口支持在原子化服务中使用。 | 635| 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开始，该接口支持在原子化服务中使用。 | 636| 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开始，该接口支持在原子化服务中使用。 | 637| loop<sup>9+</sup> | boolean | 否 | 否 | 视频循环播放属性，默认'false'，设置为'true'表示循环播放，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。<br/>直播场景不支持loop设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 638| videoScaleType<sup>9+</sup> | [VideoScaleType](#videoscaletype9) | 否 | 是 | 视频缩放模式，默认VIDEO_SCALE_TYPE_FIT，动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 639| 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开始，该接口支持在原子化服务中使用。| 640| 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开始，该接口支持在原子化服务中使用。| 641| 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开始，该接口支持在原子化服务中使用。| 642| state<sup>9+</sup> | [AVPlayerState](#avplayerstate9) | 是 | 否 | 音视频播放的状态，全状态有效，可查询参数。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 643| currentTime<sup>9+</sup> | number | 是 | 否 | 视频的当前播放位置，单位为毫秒（ms），可查询参数。<br/>返回为(-1)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 644| duration<sup>9+</sup> | number | 是 | 否 | 视频时长，单位为毫秒（ms），可查询参数。<br/>返回为(-1)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 645| width<sup>9+</sup> | number | 是 | 否 | 视频宽，单位为像素（px），可查询参数。<br/>返回为(0)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 646| height<sup>9+</sup> | number | 是 | 否 | 视频高，单位为像素（px），可查询参数。<br/>返回为(0)表示无效值，**prepared**/**playing**/**paused**/**completed**状态下有效。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 647 648### on('stateChange')<sup>9+</sup> 649 650on(type: 'stateChange', callback: OnAVPlayerStateChangeHandle): void 651 652监听播放状态机AVPlayerState切换的事件。 653 654**原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 655 656**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 657 658**参数：** 659 660| 参数名 | 类型 | 必填 | 说明 | 661| -------- | -------- | ---- | ------------------------------------------------------------ | 662| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 663| callback | [OnAVPlayerStateChangeHandle](#onavplayerstatechangehandle12) | 是 | 状态机切换事件回调方法。 | 664 665**示例：** 666 667```ts 668avPlayer.on('stateChange', async (state: string, reason: media.StateChangeReason) => { 669 switch (state) { 670 case 'idle': 671 console.info('state idle called'); 672 break; 673 case 'initialized': 674 console.info('initialized prepared called'); 675 break; 676 case 'prepared': 677 console.info('state prepared called'); 678 break; 679 case 'playing': 680 console.info('state playing called'); 681 break; 682 case 'paused': 683 console.info('state paused called'); 684 break; 685 case 'completed': 686 console.info('state completed called'); 687 break; 688 case 'stopped': 689 console.info('state stopped called'); 690 break; 691 case 'released': 692 console.info('state released called'); 693 break; 694 case 'error': 695 console.info('state error called'); 696 break; 697 default: 698 console.info('unknown state :' + state); 699 break; 700 } 701}) 702``` 703 704### off('stateChange')<sup>9+</sup> 705 706off(type: 'stateChange', callback?: OnAVPlayerStateChangeHandle): void 707 708取消监听播放状态机[AVPlayerState](#avplayerstate9)切换的事件。 709 710**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 711 712**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 713 714**参数：** 715 716| 参数名 | 类型 | 必填 | 说明 | 717| ------ | ------ | ---- | ----------------------------------------------------- | 718| type | string | 是 | 状态机切换事件回调类型，取消注册的事件：'stateChange' | 719| callback | [OnAVPlayerStateChangeHandle](#onavplayerstatechangehandle12) | 否 | 状态机切换事件回调方法。<br/>从API version 12开始支持此参数。 | 720 721**示例：** 722 723```ts 724avPlayer.off('stateChange') 725``` 726 727### on('error')<sup>9+</sup> 728 729on(type: 'error', callback: ErrorCallback): void 730 731监听[AVPlayer](#avplayer9)的错误事件，该事件仅用于错误提示，不需要用户停止播控动作。如果此时[AVPlayerState](#avplayerstate9)也切至error状态，用户需要通过[reset()](#reset9)或者[release()](#release9)退出播放操作。 732 733**原子化服务API：** 从API version 11 开始，该接口支持在原子化服务中使用。 734 735**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 736 737**参数：** 738 739| 参数名 | 类型 | 必填 | 说明 | 740| -------- | -------- | ---- | ------------------------------------------------------------ | 741| type | string | 是 | 错误事件回调类型，支持的事件：'error'，用户操作和系统都会触发此事件。 | 742| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 错误事件回调方法，使用播放器的过程中发生错误，会提供错误码ID和错误信息。 | 743 744**错误码：** 745 746以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 747 748在API version 9-13，针对网络、服务器等数据流异常，接口上报5400103；从API version 14开始，对应错误细化为错误码5411001-5411011。 749 750| 错误码ID | 错误信息 | 751| -------- | --------------------- | 752| 201 | Permission denied. | 753| 401 | The parameter check failed. | 754| 801 | Capability not supported. | 755| 5400101 | No memory. | 756| 5400102 | Operation not allowed.| 757| 5400103 | I/O error. | 758| 5400104 | Time out. | 759| 5400105 | Service died. | 760| 5400106 | Unsupported format. | 761| 5411001 | IO can not find host. | 762| 5411002 | IO connection timeout. | 763| 5411003 | IO network abnormal. | 764| 5411004 | IO network unavailable. | 765| 5411005 | IO no permission. | 766| 5411006 | IO request denied. | 767| 5411007 | IO resource not found. | 768| 5411008 | IO SSL client cert needed. | 769| 5411009 | IO SSL connect fail. | 770| 5411010 | IO SSL server cert untrusted. | 771| 5411011 | IO unsupported request. | 772 773**示例：** 774 775```ts 776import { BusinessError } from '@kit.BasicServicesKit'; 777 778avPlayer.on('error', (error: BusinessError) => { 779 console.info('error happened,and error message is :' + error.message) 780 console.info('error happened,and error code is :' + error.code) 781}) 782``` 783 784### off('error')<sup>9+</sup> 785 786off(type: 'error', callback?: ErrorCallback): void 787 788取消监听播放的错误事件。 789 790**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 791 792**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 793 794**参数：** 795 796| 参数名 | 类型 | 必填 | 说明 | 797| ------ | ------ | ---- | ----------------------------------------- | 798| type | string | 是 | 错误事件回调类型，取消注册的事件：'error' | 799| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 错误事件回调方法，使用播放器的过程中发生错误，会提供错误码ID和错误信息。<br/>从API version 12开始支持此参数。 | 800 801**示例：** 802 803```ts 804avPlayer.off('error') 805``` 806 807### setMediaSource<sup>12+</sup> 808 809setMediaSource(src:MediaSource, strategy?: PlaybackStrategy): Promise\<void> 810 811流媒体预下载资源设置，下载url对应的流媒体数据，并暂存在内存中。[视频播放开发指导](../../media/media/video-playback.md)。通过Promise获取返回值。 812 813**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 814 815**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 816 817**参数：** 818 819| 参数名 | 类型 | 必填 | 说明 | 820| -------- | -------- | ---- | -------------------- | 821| src | [MediaSource](#mediasource12) | 是 | 流媒体预下载媒体来源。 | 822| strategy | [PlaybackStrategy](#playbackstrategy12) | 否 | 流媒体预下载播放策略。 | 823 824**返回值：** 825 826| 类型 | 说明 | 827| -------------- | ------------------------------------------ | 828| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 829 830**错误码：** 831 832以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 833 834| 错误码ID | 错误信息 | 835| -------- | ----------------------------------------- | 836| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 837| 5400102 | Operation not allowed. Return by promise. | 838 839**示例：** 840 841<!--code_no_check--> 842```ts 843let player = await media.createAVPlayer(); 844let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 845let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 846let playStrategy : media.PlaybackStrategy = {preferredWidth: 1, preferredHeight: 2, preferredBufferDuration: 3, preferredHdr: false}; 847player.setMediaSource(mediaSource, playStrategy); 848``` 849 850### setPlaybackStrategy<sup>12+</sup> 851 852setPlaybackStrategy(strategy: PlaybackStrategy): Promise\<void> 853 854设置播放策略，只能在initialized状态下调用。 855 856**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 857 858**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 859 860**参数：** 861 862| 参数名 | 类型 | 必填 | 说明 | 863| -------- | -------- | ---- | -------------------- | 864| strategy | [PlaybackStrategy](#playbackstrategy12) | 是 | 播放策略。 | 865 866**返回值：** 867 868| 类型 | 说明 | 869| -------------- | ------------------------------------ | 870| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 871 872**错误码：** 873 874以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 875 876| 错误码ID | 错误信息 | 877| -------- | ----------------------------------------- | 878| 401 | Parameter error. Possible causes: 1. Incorrect parameter types. 2. Parameter verification failed. | 879| 5400102 | Operation not allowed. Return by promise. | 880 881**示例：** 882 883<!--code_no_check--> 884```ts 885import { common } from '@kit.AbilityKit'; 886 887let player = await media.createAVPlayer(); 888let context = getContext(this) as common.UIAbilityContext 889let fileDescriptor = await context.resourceManager.getRawFd('xxx.mp4') 890player.fdSrc = fileDescriptor 891let playStrategy : media.PlaybackStrategy = {preferredWidth: 1, preferredHeight: 2, preferredBufferDuration: 3, 892 preferredHdr: false, mutedMediaType: media.MediaType.MEDIA_TYPE_AUD}; 893player.setPlaybackStrategy(playStrategy); 894``` 895 896### prepare<sup>9+</sup> 897 898prepare(callback: AsyncCallback\<void>): void 899 900准备播放音频/视频，需在[stateChange](#onstatechange9)事件成功触发至initialized状态后，才能调用。使用callback方式异步获取返回值。 901 902**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 903 904**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 905 906**参数：** 907 908| 参数名 | 类型 | 必填 | 说明 | 909| -------- | -------- | ---- | -------------------- | 910| callback | AsyncCallback\<void> | 是 | 准备播放的回调方法。 | 911 912**错误码：** 913 914以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 915 916| 错误码ID | 错误信息 | 917| -------- | ------------------------------------------ | 918| 5400102 | Operation not allowed. Return by callback. | 919| 5400106 | Unsupported format. Return by callback. | 920 921**示例：** 922 923```ts 924import { BusinessError } from '@kit.BasicServicesKit'; 925 926avPlayer.prepare((err: BusinessError) => { 927 if (err) { 928 console.error('Failed to prepare,error message is :' + err.message) 929 } else { 930 console.info('Succeeded in preparing'); 931 } 932}) 933``` 934 935### prepare<sup>9+</sup> 936 937prepare(): Promise\<void> 938 939准备播放音频/视频，需在[stateChange](#onstatechange9)事件成功触发至initialized状态后，才能调用。通过Promise获取返回值。 940 941**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 942 943**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 944 945**返回值：** 946 947| 类型 | 说明 | 948| -------------- | ------------------------- | 949| Promise\<void> | 准备播放的Promise返回值。 | 950 951**错误码：** 952 953以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 954 955| 错误码ID | 错误信息 | 956| -------- | ----------------------------------------- | 957| 5400102 | Operation not allowed. Return by promise. | 958| 5400106 | Unsupported format. Return by promise. | 959 960**示例：** 961 962```ts 963import { BusinessError } from '@kit.BasicServicesKit'; 964 965avPlayer.prepare().then(() => { 966 console.info('Succeeded in preparing'); 967}, (err: BusinessError) => { 968 console.error('Failed to prepare,error message is :' + err.message) 969}) 970``` 971 972### setMediaMuted<sup>12+</sup> 973 974setMediaMuted(mediaType: MediaType, muted: boolean ): Promise\<void> 975 976设置音频静音/取消音频静音。只能在prepared/playing/paused/completed状态下调用。仅支持设置mediaType为音频格式。 977 978**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 979 980**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 981 982**参数：** 983 984| 参数名 | 类型 | 必填 | 说明 | 985| -------- | -------- | ---- | -------------------- | 986| mediaType | [MediaType](#mediatype8) | 是 | 播放策略。 | 987| muted | boolean | 是 | 是否静音播放。 | 988 989**返回值：** 990 991| 类型 | 说明 | 992| -------------- | ------------------------- | 993| Promise\<void> | 准备播放的Promise返回值。 | 994 995**错误码：** 996 997以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 998 999| 错误码ID | 错误信息 | 1000| -------- | ----------------------------------------- | 1001| 401 | The parameter check failed. Return by promise. | 1002| 5400102 | Operation not allowed. Return by promise. | 1003 1004**示例：** 1005 1006```ts 1007import { BusinessError } from '@kit.BasicServicesKit'; 1008 1009avPlayer.prepare().then(() => { 1010 console.info('Succeeded in preparing'); 1011 avPlayer.setMediaMuted(media.MediaType.MEDIA_TYPE_AUD, true) 1012}, (err: BusinessError) => { 1013 console.error('Failed to prepare,error message is :' + err.message) 1014}) 1015``` 1016 1017### play<sup>9+</sup> 1018 1019play(callback: AsyncCallback\<void>): void 1020 1021开始播放音视频资源，只能在prepared/paused/completed状态调用。使用callback方式异步获取返回值。 1022 1023**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1024 1025**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1026 1027**参数：** 1028 1029| 参数名 | 类型 | 必填 | 说明 | 1030| -------- | -------- | ---- | -------------------- | 1031| callback | AsyncCallback\<void> | 是 | 开始播放的回调方法。 | 1032 1033**错误码：** 1034 1035以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1036 1037| 错误码ID | 错误信息 | 1038| -------- | ------------------------------------------ | 1039| 5400102 | Operation not allowed. Return by callback. | 1040 1041**示例：** 1042 1043```ts 1044import { BusinessError } from '@kit.BasicServicesKit'; 1045 1046avPlayer.play((err: BusinessError) => { 1047 if (err) { 1048 console.error('Failed to play,error message is :' + err.message) 1049 } else { 1050 console.info('Succeeded in playing'); 1051 } 1052}) 1053``` 1054 1055### play<sup>9+</sup> 1056 1057play(): Promise\<void> 1058 1059开始播放音视频资源，只能在prepared/paused/completed状态调用。通过Promise获取返回值。 1060 1061**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1062 1063**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1064 1065**返回值：** 1066 1067| 类型 | 说明 | 1068| -------------- | ------------------------- | 1069| Promise\<void> | 开始播放的Promise返回值。 | 1070 1071**错误码：** 1072 1073以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1074 1075| 错误码ID | 错误信息 | 1076| -------- | ----------------------------------------- | 1077| 5400102 | Operation not allowed. Return by promise. | 1078 1079**示例：** 1080 1081```ts 1082import { BusinessError } from '@kit.BasicServicesKit'; 1083 1084avPlayer.play().then(() => { 1085 console.info('Succeeded in playing'); 1086}, (err: BusinessError) => { 1087 console.error('Failed to play,error message is :' + err.message) 1088}) 1089``` 1090 1091### pause<sup>9+</sup> 1092 1093pause(callback: AsyncCallback\<void>): void 1094 1095暂停播放音视频资源，只能在playing状态调用。使用callback方式异步获取返回值。 1096 1097**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1098 1099**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1100 1101**参数：** 1102 1103| 参数名 | 类型 | 必填 | 说明 | 1104| -------- | -------- | ---- | -------------------- | 1105| callback | AsyncCallback\<void> | 是 | 暂停播放的回调方法。 | 1106 1107**错误码：** 1108 1109以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1110 1111| 错误码ID | 错误信息 | 1112| -------- | ------------------------------------------ | 1113| 5400102 | Operation not allowed. Return by callback. | 1114 1115**示例：** 1116 1117```ts 1118import { BusinessError } from '@kit.BasicServicesKit'; 1119 1120avPlayer.pause((err: BusinessError) => { 1121 if (err) { 1122 console.error('Failed to pause,error message is :' + err.message) 1123 } else { 1124 console.info('Succeeded in pausing'); 1125 } 1126}) 1127``` 1128 1129### pause<sup>9+</sup> 1130 1131pause(): Promise\<void> 1132 1133暂停播放音视频资源，只能在playing状态调用。通过Promise获取返回值。 1134 1135**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1136 1137**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1138 1139**返回值：** 1140 1141| 类型 | 说明 | 1142| -------------- | ------------------------- | 1143| Promise\<void> | 暂停播放的Promise返回值。 | 1144 1145**错误码：** 1146 1147以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1148 1149| 错误码ID | 错误信息 | 1150| -------- | ----------------------------------------- | 1151| 5400102 | Operation not allowed. Return by promise. | 1152 1153**示例：** 1154 1155```ts 1156import { BusinessError } from '@kit.BasicServicesKit'; 1157 1158avPlayer.pause().then(() => { 1159 console.info('Succeeded in pausing'); 1160}, (err: BusinessError) => { 1161 console.error('Failed to pause,error message is :' + err.message) 1162}) 1163``` 1164 1165### stop<sup>9+</sup> 1166 1167stop(callback: AsyncCallback\<void>): void 1168 1169停止播放音视频资源，只能在prepared/playing/paused/completed状态调用。使用callback方式异步获取返回值。 1170 1171**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1172 1173**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1174 1175**参数：** 1176 1177| 参数名 | 类型 | 必填 | 说明 | 1178| -------- | -------- | ---- | -------------------- | 1179| callback | AsyncCallback\<void> | 是 | 停止播放的回调方法。 | 1180 1181**错误码：** 1182 1183以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1184 1185| 错误码ID | 错误信息 | 1186| -------- | ------------------------------------------ | 1187| 5400102 | Operation not allowed. Return by callback. | 1188 1189**示例：** 1190 1191```ts 1192import { BusinessError } from '@kit.BasicServicesKit'; 1193 1194avPlayer.stop((err: BusinessError) => { 1195 if (err) { 1196 console.error('Failed to stop,error message is :' + err.message) 1197 } else { 1198 console.info('Succeeded in stopping'); 1199 } 1200}) 1201``` 1202 1203### stop<sup>9+</sup> 1204 1205stop(): Promise\<void> 1206 1207停止播放音视频资源，只能在prepared/playing/paused/completed状态调用。通过Promise获取返回值。 1208 1209**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1210 1211**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1212 1213**返回值：** 1214 1215| 类型 | 说明 | 1216| -------------- | ------------------------- | 1217| Promise\<void> | 停止播放的Promise返回值。 | 1218 1219**错误码：** 1220 1221以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1222 1223| 错误码ID | 错误信息 | 1224| -------- | ----------------------------------------- | 1225| 5400102 | Operation not allowed. Return by promise. | 1226 1227**示例：** 1228 1229```ts 1230import { BusinessError } from '@kit.BasicServicesKit'; 1231 1232avPlayer.stop().then(() => { 1233 console.info('Succeeded in stopping'); 1234}, (err: BusinessError) => { 1235 console.error('Failed to stop,error message is :' + err.message) 1236}) 1237``` 1238 1239### reset<sup>9+</sup> 1240 1241reset(callback: AsyncCallback\<void>): void 1242 1243重置播放，只能在initialized/prepared/playing/paused/completed/stopped/error状态调用。使用callback方式异步获取返回值。 1244 1245**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1246 1247**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1248 1249**参数：** 1250 1251| 参数名 | 类型 | 必填 | 说明 | 1252| -------- | -------- | ---- | -------------------- | 1253| callback | AsyncCallback\<void> | 是 | 重置播放的回调方法。 | 1254 1255**错误码：** 1256 1257以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1258 1259| 错误码ID | 错误信息 | 1260| -------- | ------------------------------------------ | 1261| 5400102 | Operation not allowed. Return by callback. | 1262 1263**示例：** 1264 1265```ts 1266import { BusinessError } from '@kit.BasicServicesKit'; 1267 1268avPlayer.reset((err: BusinessError) => { 1269 if (err) { 1270 console.error('Failed to reset,error message is :' + err.message) 1271 } else { 1272 console.info('Succeeded in resetting'); 1273 } 1274}) 1275``` 1276 1277### reset<sup>9+</sup> 1278 1279reset(): Promise\<void> 1280 1281重置播放，只能在initialized/prepared/playing/paused/completed/stopped/error状态调用。通过Promise获取返回值。 1282 1283**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1284 1285**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1286 1287**返回值：** 1288 1289| 类型 | 说明 | 1290| -------------- | ------------------------- | 1291| Promise\<void> | 重置播放的Promise返回值。 | 1292 1293**错误码：** 1294 1295以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1296 1297| 错误码ID | 错误信息 | 1298| -------- | ----------------------------------------- | 1299| 5400102 | Operation not allowed. Return by promise. | 1300 1301**示例：** 1302 1303```ts 1304import { BusinessError } from '@kit.BasicServicesKit'; 1305 1306avPlayer.reset().then(() => { 1307 console.info('Succeeded in resetting'); 1308}, (err: BusinessError) => { 1309 console.error('Failed to reset,error message is :' + err.message) 1310}) 1311``` 1312 1313### release<sup>9+</sup> 1314 1315release(callback: AsyncCallback\<void>): void 1316 1317销毁播放资源，除released状态外，均可以调用。使用callback方式异步获取返回值。 1318 1319**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1320 1321**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1322 1323**参数：** 1324 1325| 参数名 | 类型 | 必填 | 说明 | 1326| -------- | -------- | ---- | -------------------- | 1327| callback | AsyncCallback\<void> | 是 | 销毁播放的回调方法。 | 1328 1329**错误码：** 1330 1331以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1332 1333| 错误码ID | 错误信息 | 1334| -------- | ------------------------------------------ | 1335| 5400102 | Operation not allowed. Return by callback. | 1336 1337**示例：** 1338 1339```ts 1340import { BusinessError } from '@kit.BasicServicesKit'; 1341 1342avPlayer.release((err: BusinessError) => { 1343 if (err) { 1344 console.error('Failed to release,error message is :' + err.message) 1345 } else { 1346 console.info('Succeeded in releasing'); 1347 } 1348}) 1349``` 1350 1351### release<sup>9+</sup> 1352 1353release(): Promise\<void> 1354 1355销毁播放资源，除released状态，都可以调用。通过Promise获取返回值。 1356 1357**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1358 1359**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1360 1361**返回值：** 1362 1363| 类型 | 说明 | 1364| -------------- | ------------------------- | 1365| Promise\<void> | 销毁播放的Promise返回值。 | 1366 1367**错误码：** 1368 1369以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1370 1371| 错误码ID | 错误信息 | 1372| -------- | ----------------------------------------- | 1373| 5400102 | Operation not allowed. Return by promise. | 1374 1375**示例：** 1376 1377```ts 1378import { BusinessError } from '@kit.BasicServicesKit'; 1379 1380avPlayer.release().then(() => { 1381 console.info('Succeeded in releasing'); 1382}, (err: BusinessError) => { 1383 console.error('Failed to release,error message is :' + err.message) 1384}) 1385``` 1386 1387### getTrackDescription<sup>9+</sup> 1388 1389getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 1390 1391获取音视频轨道信息，可以在prepared/playing/paused状态调用。获取所有音视轨道信息，应在数据加载回调后调用。使用callback方式异步获取返回值。 1392 1393**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1394 1395**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1396 1397**参数：** 1398 1399| 参数名 | 类型 | 必填 | 说明 | 1400| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1401| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是 | 回调函数，当获取音频轨道信息成功，err为undefined，data为获取到的MediaDescription数组；否则为错误对象。| 1402 1403**错误码：** 1404 1405以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1406 1407| 错误码ID | 错误信息 | 1408| -------- | ------------------------------------------ | 1409| 5400102 | Operation not allowed. Return by callback. | 1410 1411**示例：** 1412 1413```ts 1414import { BusinessError } from '@kit.BasicServicesKit'; 1415 1416avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1417 if ((arrList) != null) { 1418 console.info('Succeeded in doing getTrackDescription'); 1419 } else { 1420 console.error(`Failed to do getTrackDescription, error:${error}`); 1421 } 1422}); 1423``` 1424 1425### getTrackDescription<sup>9+</sup> 1426 1427getTrackDescription(): Promise\<Array\<MediaDescription>> 1428 1429获取音视频轨道信息，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1430 1431**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1432 1433**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1434 1435**返回值：** 1436 1437| 类型 | 说明 | 1438| ------------------------------------------------------ | ------------------------------------------------- | 1439| Promise<Array<[MediaDescription](#mediadescription8)>> | Promise对象，返回音视频轨道信息MediaDescription数组。 | 1440 1441**错误码：** 1442 1443以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1444 1445| 错误码ID | 错误信息 | 1446| -------- | ----------------------------------------- | 1447| 5400102 | Operation not allowed. Return by promise. | 1448 1449**示例：** 1450 1451```ts 1452import { BusinessError } from '@kit.BasicServicesKit'; 1453 1454avPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 1455 console.info('Succeeded in getting TrackDescription'); 1456}).catch((error: BusinessError) => { 1457 console.error(`Failed to get TrackDescription, error:${error}`); 1458}); 1459``` 1460 1461### getSelectedTracks<sup>12+</sup> 1462 1463getSelectedTracks(): Promise\<Array\<number>> 1464 1465获取已选择的音视频轨道索引，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1466 1467**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1468 1469**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1470 1471**返回值：** 1472 1473| 类型 | 说明 | 1474| ------------------------------------------------------ | ------------------------------------------------- | 1475| Promise<Array<[number]>> | Promise对象，返回已选择音视频轨道索引数组。 | 1476 1477**错误码：** 1478 1479以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1480 1481| 错误码ID | 错误信息 | 1482| -------- | ----------------------------------------- | 1483| 5400102 | Operation not allowed. | 1484 1485**示例：** 1486 1487```ts 1488import { BusinessError } from '@kit.BasicServicesKit'; 1489 1490avPlayer.getSelectedTracks().then((arrList: Array<number>) => { 1491 console.info('Succeeded in getting SelectedTracks'); 1492}).catch((error: BusinessError) => { 1493 console.error(`Failed to get SelectedTracks, error:${error}`); 1494}); 1495``` 1496 1497### getPlaybackInfo<sup>12+</sup> 1498 1499getPlaybackInfo(): Promise\<PlaybackInfo> 1500 1501获取播放过程信息，可以在prepared/playing/paused状态调用。通过Promise获取返回值。 1502 1503**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1504 1505**返回值：** 1506 1507| 类型 | 说明 | 1508| ------------------------------------------------------ | ------------------------------------------------- | 1509| Promise<[PlaybackInfo](#playbackinfo12)> | Promise对象，返回播放器信息PlaybackInfo。 | 1510 1511**示例：** 1512 1513```ts 1514import { BusinessError } from '@kit.BasicServicesKit'; 1515 1516let avPlayer: media.AVPlayer | undefined = undefined; 1517let playbackInfo: media.PlaybackInfo | undefined = undefined; 1518media.createAVPlayer(async (err: BusinessError, player: media.AVPlayer) => { 1519 if (player != null) { 1520 avPlayer = player; 1521 console.info(`Succeeded in creating AVPlayer`); 1522 if (avPlayer) { 1523 try { 1524 playbackInfo = await avPlayer.getPlaybackInfo(); 1525 console.info(`AVPlayer getPlaybackInfo = ${JSON.stringify(playbackInfo)}`); // 打印整个PlaybackInfo的值。 1526 } catch (error) { 1527 console.error(`error = ${error}`); 1528 } 1529 } 1530 } else { 1531 console.error(`Failed to create AVPlayer, error message:${err.message}`); 1532 } 1533}); 1534``` 1535 1536### selectTrack<sup>12+</sup> 1537 1538selectTrack(index: number, mode?: SwitchMode): Promise\<void> 1539 1540使用AVPlayer播放多音视频轨资源时，选择指定轨道播放，通过Promise获取返回值。 1541 1542**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1543 1544**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1545 1546**参数：** 1547 1548| 参数名 | 类型 | 必填 | 说明 | 1549| -------- | -------- | ---- | -------------------- | 1550| index | number | 是 | 多音视频资源的轨道索引，可通过[getTrackDescription](#gettrackdescription9-1)接口获取当前资源的所有轨道信息[MediaDescription](#mediadescription8)。 | 1551| mode | [SwitchMode](#switchmode12) | 否 | 切换视频轨道模式，默认为SMOOTH模式，**仅在DASH协议网络流视频轨切换时生效**，其他场景当前暂不支持。 | 1552 1553**返回值：** 1554 1555| 类型 | 说明 | 1556| -------------- | ------------------------- | 1557| Promise\<void> | 选择轨道完成的Promise返回值。 | 1558 1559**错误码：** 1560 1561以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1562 1563| 错误码ID | 错误信息 | 1564| -------- | ----------------------------------------- | 1565| 401 | The parameter check failed. Return by promise. | 1566| 5400102 | Operation not allowed. Return by promise. | 1567 1568**示例：** 1569 1570<!--code_no_check--> 1571```ts 1572import { BusinessError } from '@kit.BasicServicesKit'; 1573 1574let avPlayer: media.AVPlayer = await media.createAVPlayer(); 1575let audioTrackIndex: Object = 0; 1576avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1577 if (arrList != null) { 1578 for (let i = 0; i < arrList.length; i++) { 1579 if (i != 0) { 1580 // 获取音频轨道列表。 1581 audioTrackIndex = arrList[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 1582 } 1583 } 1584 } else { 1585 console.error(`Failed to get TrackDescription, error:${error}`); 1586 } 1587}); 1588 1589// 选择其中一个音频轨道。 1590avPlayer.selectTrack(parseInt(audioTrackIndex.toString())); 1591``` 1592 1593### deselectTrack<sup>12+</sup> 1594 1595deselectTrack(index: number): Promise\<void> 1596 1597使用AVPlayer播放多音轨视频时取消指定音视频轨道播放，通过Promise获取返回值。 1598 1599**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1600 1601**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1602 1603**参数：** 1604 1605| 参数名 | 类型 | 必填 | 说明 | 1606| -------- | -------- | ---- | -------------------- | 1607| index | number | 是 | 多音视频资源的轨道索引，来自[getTrackDescription](#gettrackdescription9-1)接口所获取的轨道信息[MediaDescription](#mediadescription8)。 | 1608 1609**返回值：** 1610 1611| 类型 | 说明 | 1612| -------------- | ------------------------- | 1613| Promise\<void> | 取消选择曲目完成的Promise返回值。 | 1614 1615**错误码：** 1616 1617以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1618 1619| 错误码ID | 错误信息 | 1620| -------- | ----------------------------------------- | 1621| 401 | The parameter check failed. Return by promise. | 1622| 5400102 | Operation not allowed. Return by promise. | 1623 1624**示例：** 1625 1626<!--code_no_check--> 1627```ts 1628import { BusinessError } from '@kit.BasicServicesKit'; 1629 1630let avPlayer: media.AVPlayer = await media.createAVPlayer(); 1631let audioTrackIndex: Object = 0; 1632avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 1633 if (arrList != null) { 1634 for (let i = 0; i < arrList.length; i++) { 1635 if (i != 0) { 1636 // 获取音频轨道列表。 1637 audioTrackIndex = arrList[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 1638 } 1639 } 1640 } else { 1641 console.error(`Failed to get TrackDescription, error:${error}`); 1642 } 1643}); 1644 1645// 选择其中一个音频轨道。 1646avPlayer.selectTrack(parseInt(audioTrackIndex.toString())); 1647// 取消选择上次选中的音频轨道，并恢复到默认音频轨道。 1648avPlayer.deselectTrack(parseInt(audioTrackIndex.toString())); 1649``` 1650 1651### setDecryptionConfig<sup>11+</sup> 1652 1653setDecryptionConfig(mediaKeySession: drm.MediaKeySession, secureVideoPath: boolean): void 1654 1655设置解密配置。当收到[mediaKeySystemInfoUpdate事件](#onmediakeysysteminfoupdate11)时，需根据事件上报的信息创建相关配置并设置解密配置，否则无法播放。 1656 1657**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1658 1659**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1660 1661**参数：** 1662 1663| 参数名 | 类型 | 必填 | 说明 | 1664| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1665| mediaKeySession | [drm.MediaKeySession](../apis-drm-kit/js-apis-drm.md#mediakeysession) | 是 | 解密会话 | 1666| secureVideoPath | boolean | 是 | 安全视频通路，true表示选择安全视频通路，false表示选择非安全视频通路 | 1667 1668**错误码：** 1669 1670以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1671 1672| 错误码ID | 错误信息 | 1673| -------- | ----------------------------------------- | 1674| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 1675 1676**示例：** 1677 1678关于drm模块的示例具体可见[js-apis-drm.md](../apis-drm-kit/js-apis-drm.md)。 1679```ts 1680import { drm } from '@kit.DrmKit'; 1681 1682// 创建MediaKeySystem系统。 1683let keySystem:drm.MediaKeySystem = drm.createMediaKeySystem('com.clearplay.drm'); 1684// 创建MediaKeySession解密会话。 1685let keySession:drm.MediaKeySession = keySystem.createMediaKeySession(drm.ContentProtectionLevel.CONTENT_PROTECTION_LEVEL_SW_CRYPTO); 1686// 生成许可证请求、设置许可证响应等。 1687// 安全视频通路标志。 1688let secureVideoPath:boolean = false; 1689// 设置解密配置。 1690avPlayer.setDecryptionConfig(keySession, secureVideoPath); 1691``` 1692 1693### getMediaKeySystemInfos<sup>11+</sup> 1694 1695getMediaKeySystemInfos(): Array\<drm.MediaKeySystemInfo> 1696 1697获取当前播放的媒体资源的MediaKeySystemInfo。需要在[mediaKeySystemInfoUpdate事件](#onmediakeysysteminfoupdate11)触发成功后才能调用。 1698 1699**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1700 1701**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1702 1703**返回值：** 1704 1705| 类型 | 说明 | 1706| ------------------------------------------------------ | ------------------------------------------------- | 1707| Array<[drm.MediaKeySystemInfo](../apis-drm-kit/js-apis-drm.md#mediakeysysteminfo)> | MediaKeySystemInfo数组，MediaKeySystemInfo具有uuid和pssh两个属性。 | 1708 1709**示例：** 1710 1711```ts 1712import { drm } from '@kit.DrmKit'; 1713 1714const infos = avPlayer.getMediaKeySystemInfos(); 1715console.info('GetMediaKeySystemInfos count: ' + infos.length); 1716for (let i = 0; i < infos.length; i++) { 1717 console.info('GetMediaKeySystemInfos uuid: ' + infos[i]["uuid"]); 1718 console.info('GetMediaKeySystemInfos pssh: ' + infos[i]["pssh"]); 1719} 1720``` 1721 1722### seek<sup>9+</sup> 1723 1724seek(timeMs: number, mode?:SeekMode): void 1725 1726跳转到指定播放位置，只能在prepared/playing/paused/completed状态调用，可以通过[seekDone事件](#onseekdone9)确认是否生效。 1727注：直播场景不支持seek。 1728 1729**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1730 1731**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1732 1733**参数：** 1734 1735| 参数名 | 类型 | 必填 | 说明 | 1736| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 1737| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, [duration](#属性)]。 | 1738| mode | [SeekMode](#seekmode8) | 否 | 基于视频I帧的跳转模式，默认为SEEK_PREV_SYNC模式，**仅在视频资源播放时设置**。 | 1739 1740**示例：** 1741 1742```ts 1743let seekTime: number = 1000 1744avPlayer.seek(seekTime, media.SeekMode.SEEK_PREV_SYNC) 1745``` 1746 1747### on('seekDone')<sup>9+</sup> 1748 1749on(type: 'seekDone', callback: Callback\<number>): void 1750 1751监听seek生效的事件。 1752 1753**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1754 1755**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1756 1757**参数：** 1758 1759| 参数名 | 类型 | 必填 | 说明 | 1760| -------- | -------- | ---- | ------------------------------------------------------------ | 1761| type | string | 是 | seek生效的事件回调类型，支持的事件：'seekDone'，每次调用seek后都会回调此事件。 | 1762| callback | Callback\<number> | 是 | 回调函数。seek生效的事件回调方法，只会上报用户请求的time位置。<br/>**视频播放：**[SeekMode](#seekmode8)会造成实际跳转位置与用户设置产生偏差，精准位置需要通过currentTime获取，事件回调的time仅代表完成用户某一次请求。 | 1763 1764**示例：** 1765 1766```ts 1767avPlayer.on('seekDone', (seekDoneTime:number) => { 1768 console.info('seekDone called,and seek time is:' + seekDoneTime) 1769}) 1770``` 1771 1772### off('seekDone')<sup>9+</sup> 1773 1774off(type: 'seekDone', callback?: Callback\<number>): void 1775 1776取消监听seek生效的事件。 1777 1778**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1779 1780**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1781 1782**参数：** 1783 1784| 参数名 | 类型 | 必填 | 说明 | 1785| ------ | ------ | ---- | ---------------------------------------------------- | 1786| type | string | 是 | seek生效的事件回调类型，取消注册的事件：'seekDone'。 | 1787| callback | Callback\<number> | 否 | 回调函数。seek生效的事件回调方法，只会上报用户请求的time位置。<br/>**视频播放：**[SeekMode](#seekmode8)会造成实际跳转位置与用户设置产生偏差，精准位置需要通过currentTime获取，事件回调的time仅代表完成用户某一次请求。<br/>从API version 12开始支持此参数。 | 1788 1789**示例：** 1790 1791```ts 1792avPlayer.off('seekDone') 1793``` 1794 1795### setSpeed<sup>9+</sup> 1796 1797setSpeed(speed: PlaybackSpeed): void 1798 1799设置倍速模式，只能在prepared/playing/paused/completed状态调用，可以通过[speedDone事件](#onspeeddone9)确认是否生效。 1800注：直播场景不支持setSpeed。 1801 1802**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1803 1804**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1805 1806**参数：** 1807 1808| 参数名 | 类型 | 必填 | 说明 | 1809| ------ | -------------------------------- | ---- | ------------------ | 1810| speed | [PlaybackSpeed](#playbackspeed8) | 是 | 指定播放倍速模式。 | 1811 1812**示例：** 1813 1814```ts 1815avPlayer.setSpeed(media.PlaybackSpeed.SPEED_FORWARD_2_00_X) 1816``` 1817 1818### on('speedDone')<sup>9+</sup> 1819 1820on(type: 'speedDone', callback: Callback\<number>): void 1821 1822监听setSpeed生效的事件 1823 1824**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1825 1826**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1827 1828**参数：** 1829 1830| 参数名 | 类型 | 必填 | 说明 | 1831| -------- | -------- | ---- | ------------------------------------------------------------ | 1832| type | string | 是 | setSpeed生效的事件回调类型，支持的事件：'speedDone'，每次调用setSpeed后都会回调此事件。 | 1833| callback | Callback\<number> | 是 | 回调函数。当setSpeed成功，上报生效的倍速模式，具体见[PlaybackSpeed](#playbackspeed8)。 | 1834 1835**示例：** 1836 1837```ts 1838avPlayer.on('speedDone', (speed:number) => { 1839 console.info('speedDone called,and speed value is:' + speed) 1840}) 1841``` 1842 1843### off('speedDone')<sup>9+</sup> 1844 1845off(type: 'speedDone', callback?: Callback\<number>): void 1846 1847取消监听setSpeed生效的事件。 1848 1849**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1850 1851**参数：** 1852 1853| 参数名 | 类型 | 必填 | 说明 | 1854| ------ | ------ | ---- | --------------------------------------------------------- | 1855| type | string | 是 | setSpeed生效的事件回调类型，取消注册的事件：'speedDone'。 | 1856| callback | Callback\<number> | 否 | 回调函数。当setSpeed成功，上报生效的倍速模式，具体见[PlaybackSpeed](#playbackspeed8)。<br/>从API version 12开始支持此参数。 | 1857 1858**示例：** 1859 1860```ts 1861avPlayer.off('speedDone') 1862``` 1863 1864### setBitrate<sup>9+</sup> 1865 1866setBitrate(bitrate: number): void 1867 1868设置比特率，以播放所指定比特率的流媒体资源，当前仅对**HLS/DASH协议网络流**有效。默认情况下，AVPlayer会根据网络连接速度选择合适的比特率。只能在prepared/playing/paused/completed状态调用，可以通过[bitrateDone](#onbitratedone9)事件确认是否生效。 1869 1870**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1871 1872**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1873 1874**参数：** 1875 1876| 参数名 | 类型 | 必填 | 说明 | 1877| ------- | ------ | ---- | ------------------------------------------------------------ | 1878| bitrate | number | 是 | 指定比特率，须通过[availableBitrates](#onavailablebitrates9)事件获得当前HLS/DASH协议网络流可用的比特率列表，如果用户指定的比特率不在此列表中，则播放器将从可用比特率列表中选择最接近的比特率。如果通过availableBitrates事件获得的比特率列表长度为0，则不支持指定比特率，也不会产生bitrateDone回调。 | 1879 1880**示例：** 1881 1882```ts 1883let bitrate: number = 96000 1884avPlayer.setBitrate(bitrate) 1885``` 1886 1887### on('bitrateDone')<sup>9+</sup> 1888 1889on(type: 'bitrateDone', callback: Callback\<number>): void 1890 1891监听setBitrate生效的事件。 1892 1893**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1894 1895**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1896 1897**参数：** 1898 1899| 参数名 | 类型 | 必填 | 说明 | 1900| -------- | -------- | ---- | ------------------------------------------------------------ | 1901| type | string | 是 | setBitrate生效的事件回调类型，支持的事件：'bitrateDone'，每次调用setBitrate后都会回调此事件。 | 1902| callback | Callback\<number> | 是 | setBitrate生效的事件回调方法，上报生效的比特率。 | 1903 1904**示例：** 1905 1906```ts 1907avPlayer.on('bitrateDone', (bitrate:number) => { 1908 console.info('bitrateDone called,and bitrate value is:' + bitrate) 1909}) 1910``` 1911 1912### off('bitrateDone')<sup>9+</sup> 1913 1914off(type: 'bitrateDone', callback?: Callback\<number>): void 1915 1916取消监听setBitrate生效的事件。 1917 1918**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1919 1920**参数：** 1921 1922| 参数名 | 类型 | 必填 | 说明 | 1923| ------ | ------ | ---- | ------------------------------------------------------------ | 1924| type | string | 是 | setBitrate生效的事件回调类型，取消注册的事件：'bitrateDone'。 | 1925| callback | Callback\<number> | 否 | setBitrate生效的事件回调方法，上报生效的比特率。<br/>从API version 12开始支持此参数。 | 1926 1927**示例：** 1928 1929```ts 1930avPlayer.off('bitrateDone') 1931``` 1932 1933### on('availableBitrates')<sup>9+</sup> 1934 1935on(type: 'availableBitrates', callback: Callback\<Array\<number>>): void 1936 1937监听HLS/DASH协议网络流可用的比特率列表，只会在切换prepared状态后上报。 1938 1939**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1940 1941**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1942 1943**参数：** 1944 1945| 参数名 | 类型 | 必填 | 说明 | 1946| -------- | -------- | ---- | ------------------------------------------------------------ | 1947| type | string | 是 | HLS/DASH协议网络流可用比特率上报事件回调类型，支持的事件：'availableBitrates'，只会在prepared之后上报一次。 | 1948| callback | Callback\<Array\<number>> | 是 | HLS/DASH协议网络流可用比特率上报事件回调方法，使用数组存放支持的比特率。如果数组长度为0，则不支持指定比特率。 | 1949 1950**示例：** 1951 1952```ts 1953avPlayer.on('availableBitrates', (bitrates: Array<number>) => { 1954 console.info('availableBitrates called,and availableBitrates length is:' + bitrates.length) 1955}) 1956``` 1957 1958### off('availableBitrates')<sup>9+</sup> 1959 1960off(type: 'availableBitrates', callback?: Callback\<Array\<number>>): void 1961 1962取消监听HLS/DASH协议网络流可用的比特率列表，调用[prepare](#prepare9)后，上报此事件。 1963 1964**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1965 1966**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1967 1968**参数：** 1969 1970| 参数名 | 类型 | 必填 | 说明 | 1971| ------ | ------ | ---- | ------------------------------------------------------------ | 1972| type | string | 是 | HLS/DASH协议网络流可用比特率上报事件回调类型，取消注册的事件：'availableBitrates'。 | 1973| callback | Callback\<Array\<number>> | 否 | HLS/DASH协议网络流可用比特率上报事件回调方法，使用数组存放支持的比特率。如果数组长度为0，则不支持指定比特率。<br/>从API version 12开始支持此参数。 | 1974 1975**示例：** 1976 1977```ts 1978avPlayer.off('availableBitrates') 1979``` 1980 1981 1982### on('mediaKeySystemInfoUpdate')<sup>11+</sup> 1983 1984on(type: 'mediaKeySystemInfoUpdate', callback: Callback\<Array\<drm.MediaKeySystemInfo>>): void 1985 1986监听mediaKeySystemInfoUpdate事件。 1987 1988**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1989 1990**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 1991 1992**参数：** 1993 1994| 参数名 | 类型 | 必填 | 说明 | 1995| -------- | -------- | ---- | ------------------------------------------------------------ | 1996| type | string | 是 | 版权保护信息更新上报事件回调类型，支持的事件：'mediaKeySystemInfoUpdate'，当播放内容的版权保护信息更新时上报事件。 | 1997| callback | Callback\<Array\<drm.[MediaKeySystemInfo](../apis-drm-kit/js-apis-drm.md#mediakeysysteminfo)>> | 是 | 版权保护信息更新上报事件回调方法，上报MediaKeySystemInfo数组。 | 1998 1999**示例：** 2000 2001```ts 2002import { drm } from '@kit.DrmKit'; 2003 2004avPlayer.on('mediaKeySystemInfoUpdate', (mediaKeySystemInfo: Array<drm.MediaKeySystemInfo>) => { 2005 for (let i = 0; i < mediaKeySystemInfo.length; i++) { 2006 console.info('mediaKeySystemInfoUpdate happened uuid: ' + mediaKeySystemInfo[i]["uuid"]); 2007 console.info('mediaKeySystemInfoUpdate happened pssh: ' + mediaKeySystemInfo[i]["pssh"]); 2008 } 2009}) 2010``` 2011 2012### off('mediaKeySystemInfoUpdate')<sup>11+</sup> 2013 2014off(type: 'mediaKeySystemInfoUpdate', callback?: Callback\<Array\<drm.MediaKeySystemInfo>>): void; 2015 2016取消监听mediaKeySystemInfoUpdate事件。 2017 2018**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2019 2020**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2021 2022**参数：** 2023 2024| 参数名 | 类型 | 必填 | 说明 | 2025| ------ | ------ | ---- | ------------------------------------------------------------ | 2026| type | string | 是 | 版权保护信息更新上报事件回调类型，取消注册的事件：'mediaKeySystemInfoUpdate'。 | 2027| callback | Callback\<Array\<drm.[MediaKeySystemInfo](../apis-drm-kit/js-apis-drm.md#mediakeysysteminfo)>> | 否 | 版权保护信息更新上报事件回调方法，上报版权保护信息数组。如填写该参数，则仅取消注册此回调方法，否则取消注册mediaKeySystemInfoUpdate事件的所有回调方法。 | 2028 2029**示例：** 2030 2031```ts 2032avPlayer.off('mediaKeySystemInfoUpdate') 2033``` 2034 2035### setVolume<sup>9+</sup> 2036 2037setVolume(volume: number): void 2038 2039设置媒体播放音量，只能在prepared/playing/paused/completed状态调用，可以通过[volumeChange事件](#onvolumechange9)确认是否生效。 2040 2041**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2042 2043**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2044 2045**参数：** 2046 2047| 参数名 | 类型 | 必填 | 说明 | 2048| ------ | ------ | ---- | ------------------------------------------------------------ | 2049| volume | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 2050 2051**示例：** 2052 2053```ts 2054let volume: number = 1.0 2055avPlayer.setVolume(volume) 2056``` 2057 2058### on('volumeChange')<sup>9+</sup> 2059 2060on(type: 'volumeChange', callback: Callback\<number>): void 2061 2062监听setVolume生效的事件。 2063 2064**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2065 2066**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2067 2068**参数：** 2069 2070| 参数名 | 类型 | 必填 | 说明 | 2071| -------- | -------- | ---- | ------------------------------------------------------------ | 2072| type | string | 是 | setVolume生效的事件回调类型，支持的事件：'volumeChange'，每次调用setVolume后都会回调此事件。 | 2073| callback | Callback\<number> | 是 | setVolume生效的事件回调方法，上报生效的媒体音量。 | 2074 2075**示例：** 2076 2077```ts 2078avPlayer.on('volumeChange', (vol: number) => { 2079 console.info('volumeChange called,and new volume is :' + vol) 2080}) 2081``` 2082 2083### off('volumeChange')<sup>9+</sup> 2084 2085off(type: 'volumeChange', callback?: Callback\<number>): void 2086 2087取消监听setVolume生效的事件。 2088 2089**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2090 2091**参数：** 2092 2093| 参数名 | 类型 | 必填 | 说明 | 2094| ------ | ------ | ---- | ------------------------------------------------------------ | 2095| type | string | 是 | setVolume生效的事件回调类型，取消注册的事件：'volumeChange'。 | 2096| callback | Callback\<number> | 否 | setVolume生效的事件回调方法，上报生效的媒体音量。<br/>从API version 12开始支持此参数。 | 2097 2098**示例：** 2099 2100```ts 2101avPlayer.off('volumeChange') 2102``` 2103 2104### on('endOfStream')<sup>9+</sup> 2105 2106on(type: 'endOfStream', callback: Callback\<void>): void 2107 2108监听资源播放至结尾的事件；如果用户设置[loop](#属性)=true，播放会跳转至开头重播；如果用户没有设置loop，会通过[stateChange](#onstatechange9)上报completed状态。 2109 2110**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2111 2112**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2113 2114**参数：** 2115 2116| 参数名 | 类型 | 必填 | 说明 | 2117| -------- | -------- | ---- | ------------------------------------------------------------ | 2118| type | string | 是 | 资源播放至结尾的事件回调类型，支持的事件：'endOfStream'，当播放至结尾时会上报此事件。 | 2119| callback | Callback\<void> | 是 | 资源播放至结尾的事件回调方法。 | 2120 2121**示例：** 2122 2123```ts 2124avPlayer.on('endOfStream', () => { 2125 console.info('endOfStream called') 2126}) 2127``` 2128 2129### off('endOfStream')<sup>9+</sup> 2130 2131off(type: 'endOfStream', callback?: Callback\<void>): void 2132 2133取消监听资源播放至结尾的事件。 2134 2135**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2136 2137**参数：** 2138 2139| 参数名 | 类型 | 必填 | 说明 | 2140| ------ | ------ | ---- | ------------------------------------------------------------ | 2141| type | string | 是 | 资源播放至结尾的事件回调类型，取消注册的事件：'endOfStream'。 | 2142| callback | Callback\<void> | 否 | 资源播放至结尾的事件回调方法。<br/>从API version 12开始支持此参数。 | 2143 2144**示例：** 2145 2146```ts 2147avPlayer.off('endOfStream') 2148``` 2149 2150### on('timeUpdate')<sup>9+</sup> 2151 2152on(type: 'timeUpdate', callback: Callback\<number>): void 2153 2154监听资源播放当前时间，单位为毫秒（ms），用于刷新进度条当前位置，默认间隔100ms时间上报，因用户操作(seek)产生的时间变化会立刻上报。 2155 2156注：直播场景不支持timeUpdate上报。 2157 2158**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2159 2160**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2161 2162**参数：** 2163 2164| 参数名 | 类型 | 必填 | 说明 | 2165| -------- | -------- | ---- | ---------------------------------------------- | 2166| type | string | 是 | 时间更新的回调类型，支持的事件：'timeUpdate'。 | 2167| callback | Callback\<number> | 是 | 回调函数。返回当前时间。 | 2168 2169**示例：** 2170 2171```ts 2172avPlayer.on('timeUpdate', (time:number) => { 2173 console.info('timeUpdate called,and new time is :' + time) 2174}) 2175``` 2176 2177### off('timeUpdate')<sup>9+</sup> 2178 2179off(type: 'timeUpdate', callback?: Callback\<number>): void 2180 2181取消监听资源播放当前时间。 2182 2183**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2184 2185**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2186 2187**参数：** 2188 2189| 参数名 | 类型 | 必填 | 说明 | 2190| ------ | ------ | ---- | -------------------------------------------------- | 2191| type | string | 是 | 时间更新的回调类型，取消注册的事件：'timeUpdate'。 | 2192| callback | Callback\<number> | 否 | 回调函数。返回当前时间。<br/>从API version 12开始支持此参数。 | 2193 2194**示例：** 2195 2196```ts 2197avPlayer.off('timeUpdate') 2198``` 2199 2200### on('durationUpdate')<sup>9+</sup> 2201 2202 2203on(type: 'durationUpdate', callback: Callback\<number>): void 2204 2205监听资源播放资源的时长，单位为毫秒（ms），用于刷新进度条长度，默认只在prepared上报一次，同时允许一些特殊码流刷新多次时长。 2206注：直播场景不支持durationUpdate上报。 2207 2208**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2209 2210**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2211 2212**参数：** 2213 2214| 参数名 | 类型 | 必填 | 说明 | 2215| -------- | -------- | ---- | -------------------------------------------------- | 2216| type | string | 是 | 时长更新的回调类型，支持的事件：'durationUpdate'。 | 2217| callback | Callback\<number> | 是 | 回调函数。返回资源时长。 | 2218 2219**示例：** 2220 2221```ts 2222avPlayer.on('durationUpdate', (duration: number) => { 2223 console.info('durationUpdate called,new duration is :' + duration) 2224}) 2225``` 2226 2227### off('durationUpdate')<sup>9+</sup> 2228 2229off(type: 'durationUpdate', callback?: Callback\<number>): void 2230 2231取消监听资源播放资源的时长。 2232 2233**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2234 2235**参数：** 2236 2237| 参数名 | 类型 | 必填 | 说明 | 2238| ------ | ------ | ---- | ------------------------------------------------------ | 2239| type | string | 是 | 时长更新的回调类型，取消注册的事件：'durationUpdate'。 | 2240| callback | Callback\<number> | 否 | 回调函数。返回资源时长。<br/>从API version 12开始支持此参数。 | 2241 2242**示例：** 2243 2244```ts 2245avPlayer.off('durationUpdate') 2246``` 2247 2248### on('bufferingUpdate')<sup>9+</sup> 2249 2250on(type: 'bufferingUpdate', callback: OnBufferingUpdateHandler): void 2251 2252订阅音视频缓存更新事件，仅网络播放支持该订阅事件。 2253 2254**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2255 2256**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2257 2258**参数：** 2259 2260| 参数名 | 类型 | 必填 | 说明 | 2261| -------- | -------- | ---- | ------------------------------------------------------------ | 2262| type | string | 是 | 播放缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 2263| callback | [OnBufferingUpdateHandler](#onbufferingupdatehandler12) | 是 | 播放缓存事件回调方法。 | 2264 2265**示例：** 2266 2267```ts 2268avPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 2269 console.info('bufferingUpdate called,and infoType value is:' + infoType + ', value is :' + value) 2270}) 2271``` 2272 2273### off('bufferingUpdate')<sup>9+</sup> 2274 2275off(type: 'bufferingUpdate', callback?: OnBufferingUpdateHandler): void 2276 2277取消监听音视频缓存更新事件。 2278 2279**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2280 2281**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2282 2283**参数：** 2284 2285| 参数名 | 类型 | 必填 | 说明 | 2286| ------ | ------ | ---- | --------------------------------------------------------- | 2287| type | string | 是 | 播放缓存事件回调类型，取消注册的事件：'bufferingUpdate'。 | 2288| callback | [OnBufferingUpdateHandler](#onbufferingupdatehandler12) | 否 | 播放缓存事件回调方法。 | 2289 2290**示例：** 2291 2292```ts 2293avPlayer.off('bufferingUpdate') 2294``` 2295 2296### on('startRenderFrame')<sup>9+</sup> 2297 2298on(type: 'startRenderFrame', callback: Callback\<void>): void 2299 2300订阅视频播放开始首帧渲染的更新事件，仅视频播放支持该订阅事件，该事件仅代表播放服务将第一帧画面送显示模块，实际效果依赖显示服务渲染性能。 2301 2302**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2303 2304**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2305 2306**参数：** 2307 2308| 参数名 | 类型 | 必填 | 说明 | 2309| -------- | -------- | ---- | ------------------------------------------------------------ | 2310| type | string | 是 | 视频播放开始首帧渲染事件回调类型，支持的事件：'startRenderFrame'。 | 2311| callback | Callback\<void> | 是 | 视频播放开始首帧渲染事件回调方法。 | 2312 2313**示例：** 2314 2315```ts 2316avPlayer.on('startRenderFrame', () => { 2317 console.info('startRenderFrame called') 2318}) 2319``` 2320 2321### off('startRenderFrame')<sup>9+</sup> 2322 2323off(type: 'startRenderFrame', callback?: Callback\<void>): void 2324 2325取消监听视频播放开始首帧渲染的更新事件。 2326 2327**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2328 2329**参数：** 2330 2331| 参数名 | 类型 | 必填 | 说明 | 2332| ------ | ------ | ---- | ------------------------------------------------------------ | 2333| type | string | 是 | 视频播放开始首帧渲染事件回调类型，取消注册的事件：'startRenderFrame'。 | 2334| callback | Callback\<void> | 否 | 视频播放开始首帧渲染事件回调方法。<br/>从API version 12开始支持此参数。 | 2335 2336**示例：** 2337 2338```ts 2339avPlayer.off('startRenderFrame') 2340``` 2341 2342### on('videoSizeChange')<sup>9+</sup> 2343 2344on(type: 'videoSizeChange', callback: OnVideoSizeChangeHandler): void 2345 2346监听视频播放宽高变化事件，仅视频播放支持该订阅事件，默认只在prepared状态上报一次，但HLS协议码流会在切换分辨率时上报。 2347 2348**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2349 2350**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2351 2352**参数：** 2353 2354| 参数名 | 类型 | 必填 | 说明 | 2355| -------- | -------- | ---- | ------------------------------------------------------------ | 2356| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChange'。 | 2357| callback | [OnVideoSizeChangeHandler](#onvideosizechangehandler12) | 是 | 视频播放宽高变化事件回调方法。 | 2358 2359**示例：** 2360 2361```ts 2362avPlayer.on('videoSizeChange', (width: number, height: number) => { 2363 console.info('videoSizeChange called,and width is:' + width + ', height is :' + height) 2364}) 2365``` 2366 2367### off('videoSizeChange')<sup>9+</sup> 2368 2369off(type: 'videoSizeChange', callback?: OnVideoSizeChangeHandler): void 2370 2371取消监听视频播放宽高变化事件。 2372 2373**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2374 2375**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2376 2377**参数：** 2378 2379| 参数名 | 类型 | 必填 | 说明 | 2380| ------ | ------ | ---- | ------------------------------------------------------------ | 2381| type | string | 是 | 视频播放宽高变化事件回调类型，取消注册的事件：'videoSizeChange'。 | 2382| callback | [OnVideoSizeChangeHandler](#onvideosizechangehandler12) | 否 | 视频播放宽高变化事件回调方法。<br/>从API version 12开始支持此参数。 | 2383 2384**示例：** 2385 2386```ts 2387avPlayer.off('videoSizeChange') 2388``` 2389 2390### on('audioInterrupt')<sup>9+</sup> 2391 2392on(type: 'audioInterrupt', callback: Callback\<audio.InterruptEvent>): void 2393 2394监听音频焦点变化事件，多个音视频资源同时播放时，会根据音频焦点模型[audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9)触发此事件。应用需根据不同焦点变化事件作相应处理。具体可参考[处理音频焦点事件](../../media/audio/audio-playback-concurrency.md)。 2395 2396**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2397 2398**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2399 2400**参数：** 2401 2402| 参数名 | 类型 | 必填 | 说明 | 2403| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 2404| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 2405| callback | Callback\<[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)> | 是 | 音频焦点变化事件回调方法。 | 2406 2407**示例：** 2408 2409```ts 2410import { audio } from '@kit.AudioKit'; 2411 2412avPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 2413 console.info('audioInterrupt called,and InterruptEvent info is:' + info) 2414}) 2415``` 2416 2417### off('audioInterrupt')<sup>9+</sup> 2418 2419off(type: 'audioInterrupt', callback?: Callback<audio.InterruptEvent>): void 2420 2421取消监听音频焦点变化事件。 2422 2423**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2424 2425**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2426 2427**参数：** 2428 2429| 参数名 | 类型 | 必填 | 说明 | 2430| ------ | ------ | ---- | ------------------------------------------------------------ | 2431| type | string | 是 | 音频焦点变化事件回调类型，取消注册的事件：'audioInterrupt'。 | 2432| callback | Callback\<[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)> | 否 | 音频焦点变化事件回调方法。<br/>从API version 12开始支持此参数。 | 2433 2434**示例：** 2435 2436```ts 2437avPlayer.off('audioInterrupt') 2438``` 2439 2440### on('audioOutputDeviceChangeWithInfo')<sup>11+</sup> 2441 2442on(type: 'audioOutputDeviceChangeWithInfo', callback: Callback\<audio.AudioStreamDeviceChangeInfo>): void 2443 2444订阅监听音频流输出设备变化及原因，使用callback方式返回结果。 2445 2446在订阅此监听时，建议参考[响应音频流输出设备变更](../../media/audio/audio-output-device-change.md)自行实现设备连接或者断开时的播放器行为。 2447 2448**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2449 2450**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2451 2452**参数：** 2453 2454| 参数名 | 类型 | 必填 | 说明 | 2455| :------- | :------------------------- | :--- | :------------------------------------------ | 2456| type | string | 是 | 事件回调类型，支持的事件为：'outputDeviceChangeWithInfo'。 | 2457| callback | Callback\<[audio.AudioStreamDeviceChangeInfo](../apis-audio-kit/js-apis-audio.md#audiostreamdevicechangeinfo11)> | 是 | 回调函数，返回当前音频流的输出设备描述信息及变化原因。 | 2458 2459**错误码：** 2460 2461| 错误码ID | 错误信息 | 2462| -------- | ------------------------------------------ | 2463| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2464 2465**示例：** 2466 2467```ts 2468import { audio } from '@kit.AudioKit'; 2469 2470avPlayer.on('audioOutputDeviceChangeWithInfo', (data: audio.AudioStreamDeviceChangeInfo) => { 2471 console.info(`${JSON.stringify(data)}`); 2472}); 2473``` 2474 2475### off('audioOutputDeviceChangeWithInfo')<sup>11+</sup> 2476 2477off(type: 'audioOutputDeviceChangeWithInfo', callback?: Callback\<audio.AudioStreamDeviceChangeInfo>): void 2478 2479取消订阅监听音频流输出设备变化及原因，使用callback方式返回结果。 2480 2481**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2482 2483**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2484 2485**参数：** 2486 2487| 参数名 | 类型 | 必填 | 说明 | 2488| :------- | :------------------------- | :--- | :------------------------------------------ | 2489| type | string | 是 | 事件回调类型，支持的事件为：'outputDeviceChange'。 | 2490| callback | Callback\<[audio.AudioStreamDeviceChangeInfo](../apis-audio-kit/js-apis-audio.md#audiostreamdevicechangeinfo11)> | 否 | 回调函数，返回当前音频流的输出设备描述信息及变化原因。 | 2491 2492**错误码：** 2493 2494| 错误码ID | 错误信息 | 2495| -------- | ------------------------------------------ | 2496| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 2497 2498**示例：** 2499 2500```ts 2501avPlayer.off('audioOutputDeviceChangeWithInfo'); 2502``` 2503 2504### addSubtitleFromFd<sup>12+</sup> 2505 2506addSubtitleFromFd(fd: number, offset?: number, length?: number): Promise\<void> 2507 2508依据fd为视频添加外挂字幕，当前仅支持与视频资源同时设置（在avplayer设置fdSrc视频资源后设置外挂字幕）。使用Promise方式返回结果。 2509 2510**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2511 2512**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2513 2514**参数：** 2515 2516| 参数名 | 类型 | 必填 | 说明 | 2517| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 2518| fd | number | 是 | 资源句柄，通过[resourceManager.getRawFd](../apis-localization-kit/js-apis-resource-manager.md#getrawfd9)获取。 | 2519| offset | number | 否 | 资源偏移量，需要基于预置资源的信息输入，非法值会造成字幕频资源解析错误。 | 2520| length | number | 否 | 资源长度，默认值为文件中从偏移量开始的剩余字节，需要基于预置资源的信息输入，非法值会造成字幕频资源解析错误。 | 2521 2522**返回值：** 2523 2524| 类型 | 说明 | 2525| -------------- | ------------------------------------------ | 2526| Promise\<void> | 添加外挂字幕addSubtitleFromFd方法的Promise返回值。 | 2527 2528**错误码：** 2529 2530| 错误码ID | 错误信息 | 2531| -------- | ------------------------------------------ | 2532| 401 | The parameter check failed. Return by promise. | 2533| 5400102 | Operation not allowed. Return by promise. | 2534 2535**示例：** 2536 2537<!--code_no_check--> 2538```ts 2539import { common } from '@kit.AbilityKit' 2540 2541let context = getContext(this) as common.UIAbilityContext 2542let fileDescriptor = await context.resourceManager.getRawFd('xxx.srt') 2543 2544avPlayer.addSubtitleFromFd(fileDescriptor.fd, fileDescriptor.offset, fileDescriptor.length) 2545``` 2546 2547### addSubtitleFromUrl<sup>12+</sup> 2548 2549addSubtitleFromUrl(url: string): Promise\<void> 2550 2551依据url为视频添加外挂字幕，当前仅支持与视频资源同时设置（在avplayer设置fdSrc视频资源后设置外挂字幕）。使用Promise方式返回结果。 2552 2553**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2554 2555**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2556 2557**参数：** 2558 2559| 参数名 | 类型 | 必填 | 说明 | 2560| ------ | ------ | ---- | ------------------------------------------------------------ | 2561| url | string | 是 | 外挂字幕文件地址。 | 2562 2563**返回值：** 2564 2565| 类型 | 说明 | 2566| -------------- | ------------------------------------------ | 2567| Promise\<void> | 添加外挂字幕addSubtitleFromUrl方法的Promise返回值。 | 2568 2569**错误码：** 2570 2571| 错误码ID | 错误信息 | 2572| -------- | ------------------------------------------ | 2573| 401 | The parameter check failed. Return by promise. | 2574| 5400102 | Operation not allowed. Return by promise. | 2575 2576**示例：** 2577 2578<!--code_no_check--> 2579```ts 2580let fdUrl:string = 'http://xxx.xxx.xxx/xx/index.srt' 2581 2582let avPlayer: media.AVPlayer = await media.createAVPlayer() 2583avPlayer.addSubtitleFromUrl(fdUrl) 2584``` 2585 2586### on('subtitleUpdate')<sup>12+</sup> 2587 2588on(type: 'subtitleUpdate', callback: Callback\<SubtitleInfo>): void 2589 2590订阅获取外挂字幕的事件，当有外挂字幕时，会通过订阅的回调方法通知用户。用户只能订阅一个外挂字幕事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2591 2592**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2593 2594**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2595 2596**参数：** 2597 2598| 参数名 | 类型 | 必填 | 说明 | 2599| -------- | -------- | ---- | ------------------------------------------------------------ | 2600| type | string | 是 | 事件回调类型，支持的事件为：'subtitleUpdate'。 | 2601| callback | function | 是 | 外挂字幕事件回调方法。 | 2602 2603**示例：** 2604 2605```ts 2606avPlayer.on('subtitleUpdate', async (info: media.SubtitleInfo) => { 2607 if (info) { 2608 let text = (!info.text) ? '' : info.text 2609 let startTime = (!info.startTime) ? 0 : info.startTime 2610 let duration = (!info.duration) ? 0 : info.duration 2611 console.info('subtitleUpdate info: text=' + text + ' startTime=' + startTime +' duration=' + duration) 2612 } else { 2613 console.info('subtitleUpdate info is null') 2614 } 2615}) 2616``` 2617 2618### off('subtitleUpdate')<sup>12+</sup> 2619 2620off(type: 'subtitleUpdate', callback?: Callback\<SubtitleInfo>): void 2621 2622取消订阅获取外挂字幕的事件。 2623 2624**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2625 2626**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2627 2628**参数：** 2629 2630| 参数名 | 类型 | 必填 | 说明 | 2631| -------- | -------- | ---- | ------------------------------------------------------------ | 2632| type | string | 是 | 事件回调类型，支持的事件为：'subtitleUpdate'。 | 2633| callback | function | 否 | 取消外挂字幕事件的回调方法。 | 2634 2635**示例：** 2636 2637```ts 2638avPlayer.off('subtitleUpdate') 2639``` 2640 2641### on('trackChange')<sup>12+</sup> 2642 2643on(type: 'trackChange', callback: OnTrackChangeHandler): void 2644 2645订阅获取轨道变更的事件，当播放的轨道变更时，会通过订阅的回调方法通知用户。用户只能订阅一个轨道变更事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2646 2647**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2648 2649**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2650 2651**参数：** 2652 2653| 参数名 | 类型 | 必填 | 说明 | 2654| -------- | -------- | ---- | ------------------------------------------------------------ | 2655| type | string | 是 | 事件回调类型，支持的事件为：'trackChange'。 | 2656| callback | [OnTrackChangeHandler](#ontrackchangehandler12) | 是 | 轨道变更事件回调方法。 | 2657 2658**示例：** 2659 2660```ts 2661avPlayer.on('trackChange', (index: number, isSelect: boolean) => { 2662 console.info('trackChange info: index=' + index + ' isSelect=' + isSelect) 2663}) 2664``` 2665 2666### off('trackChange')<sup>12+</sup> 2667 2668off(type: 'trackChange', callback?: OnTrackChangeHandler): void 2669 2670取消订阅获取轨道变更的事件。 2671 2672**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2673 2674**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2675 2676**参数：** 2677 2678| 参数名 | 类型 | 必填 | 说明 | 2679| -------- | -------- | ---- | ------------------------------------------------------------ | 2680| type | string | 是 | 事件回调类型，支持的事件为：'trackChange'。 | 2681| callback | [OnTrackChangeHandler](#ontrackchangehandler12) | 否 | 取消轨道变更事件的回调方法。 | 2682 2683**示例：** 2684 2685```ts 2686avPlayer.off('trackChange') 2687``` 2688 2689### on('trackInfoUpdate')<sup>12+</sup> 2690 2691on(type: 'trackInfoUpdate', callback: Callback\<Array\<MediaDescription>>): void 2692 2693订阅获取轨道信息更新的事件，当播放的轨道有更新时，会通过订阅的回调方法通知用户。用户只能订阅一个轨道变更事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 2694 2695**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2696 2697**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2698 2699**参数：** 2700 2701| 参数名 | 类型 | 必填 | 说明 | 2702| -------- | -------- | ---- | ------------------------------------------------------------ | 2703| type | string | 是 | 事件回调类型，支持的事件为：'trackInfoUpdate'。 | 2704| callback | Callback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 轨道信息更新事件回调方法。 | 2705 2706**示例：** 2707 2708```ts 2709avPlayer.on('trackInfoUpdate', (info: Array<media.MediaDescription>) => { 2710 if (info) { 2711 for (let i = 0; i < info.length; i++) { 2712 let propertyIndex: Object = info[i][media.MediaDescriptionKey.MD_KEY_TRACK_INDEX]; 2713 let propertyType: Object = info[i][media.MediaDescriptionKey.MD_KEY_TRACK_TYPE]; 2714 console.info('track info: index=' + propertyIndex + ' tracktype=' + propertyType) 2715 } 2716 } else { 2717 console.info('track info is null') 2718 } 2719}) 2720``` 2721 2722### off('trackInfoUpdate')<sup>12+</sup> 2723 2724off(type: 'trackInfoUpdate', callback?: Callback\<Array\<MediaDescription>>): void 2725 2726取消订阅获取轨道变更的事件。 2727 2728**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2729 2730**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2731 2732**参数：** 2733 2734| 参数名 | 类型 | 必填 | 说明 | 2735| -------- | -------- | ---- | ------------------------------------------------------------ | 2736| type | string | 是 | 事件回调类型，支持的事件为：'trackInfoUpdate'。 | 2737| callback | Callback\<Array\<[MediaDescription](#mediadescription8)>> | 否 | 取消轨道信息更新事件的回调方法。 | 2738 2739**示例：** 2740 2741```ts 2742avPlayer.off('trackInfoUpdate') 2743``` 2744 2745### on('amplitudeUpdate')<sup>13+</sup> 2746 2747on(type: 'amplitudeUpdate', callback: Callback\<Array\<number>>): void 2748 2749订阅音频最大电平值，音频资源播放时定时上报。 2750 2751**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2752 2753**参数：** 2754 2755| 参数名 | 类型 | 必填 | 说明 | 2756| -------- | -------- | ---- | ------------------------------------------------------------ | 2757| type | string | 是 | 事件回调类型，支持的事件为：'amplitudeUpdate'。 | 2758| callback | Callback\<Array\<number>> | 是 | 音频最大电平值更新事件回调方法。 | 2759 2760**示例：** 2761 2762```ts 2763avPlayer.on('amplitudeUpdate', (value: Array<number>) => { 2764 console.info('amplitudeUpdate called,and amplitudeUpdate = ${value}') 2765}) 2766``` 2767 2768### off('amplitudeUpdate')<sup>13+</sup> 2769 2770off(type: 'amplitudeUpdate', callback?: Callback\<Array\<number>>): void 2771 2772取消订阅获取音频最大电平值事件。 2773 2774**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2775 2776**参数：** 2777 2778| 参数名 | 类型 | 必填 | 说明 | 2779| ------ | ------ | ---- | ------------------------------------------------------------ | 2780| type | string | 是 | 事件回调类型，支持的事件为：'amplitudeUpdate'。 | 2781| callback | Callback\<Array\<number>> | 否 | 取消音频最大电平值更新事件回调方法。 | 2782 2783**示例：** 2784 2785```ts 2786avPlayer.off('amplitudeUpdate') 2787``` 2788 2789## AVPlayerState<sup>9+</sup> 2790 2791type AVPlayerState = 'idle' | 'initialized' | 'prepared' | 'playing' | 'paused' | 'completed' | 'stopped' | 'released' | 'error' 2792 2793[AVPlayer](#avplayer9)的状态机，可通过state属性主动获取当前状态，也可通过监听[stateChange](#onstatechange9)事件上报当前状态，状态机之间的切换规则，可参考[音频播放开发指导](../../media/media/using-avplayer-for-playback.md)。 2794 2795**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2796 2797**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2798 2799| 类型 | 说明 | 2800| :-----------------------------: | :----------------------------------------------------------- | 2801| '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属性会被重置，其他用户设置的属性将被保留。 | 2802| 'initialized' | 资源初始化，在idle 状态设置 url<sup>9+</sup> 或 fdSrc<sup>9+</sup>属性，AVPlayer会进入initialized状态，此时可以配置窗口、音频等静态属性。 | 2803| 'prepared' | 已准备状态，在initialized状态调用[prepare()](#prepare9)方法，AVPlayer会进入prepared状态，此时播放引擎的资源已准备就绪。 | 2804| 'playing' | 正在播放状态，在prepared/paused/completed状态调用[play()](#play9)方法，AVPlayer会进入playing状态。 | 2805| 'paused' | 暂停状态，在playing状态调用pause方法，AVPlayer会进入paused状态。 | 2806| 'completed' | 播放至结尾状态，当媒体资源播放至结尾时，如果用户未设置循环播放（loop = true），AVPlayer会进入completed状态，此时调用[play()](#play9)会进入playing状态和重播，调用[stop()](#stop9)会进入stopped状态。 | 2807| 'stopped' | 停止状态，在prepared/playing/paused/completed状态调用[stop()](#stop9)方法，AVPlayer会进入stopped状态，此时播放引擎只会保留属性，但会释放内存资源，可以调用[prepare()](#prepare9)重新准备，也可以调用[reset()](#reset9)重置，或者调用[release()](#release9)彻底销毁。 | 2808| 'released' | 销毁状态，销毁与当前AVPlayer关联的播放引擎，无法再进行状态转换，调用[release()](#release9)方法后，会进入released状态，结束流程。 | 2809| '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：播放过程发现码流问题，导致容器、解码短暂异常，不影响连续播放和播控操作的，不需要客户端设计容错机制。 | 2810 2811## OnTrackChangeHandler<sup>12+</sup> 2812 2813type OnTrackChangeHandler = (index: number, isSelected: boolean) => void 2814 2815track变更事件回调方法。 2816 2817**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2818 2819**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2820 2821| 参数名 | 类型 | 必填 | 说明 | 2822| ------ | ------ | ------ | ---------------------------------------------------------- | 2823| index | number | 是 | 当前选中的track索引。 | 2824| isSelected | boolean | 是 | 当前索引的选中状态。 | 2825 2826## OnAVPlayerStateChangeHandle<sup>12+</sup> 2827 2828type OnAVPlayerStateChangeHandle = (state: AVPlayerState, reason: StateChangeReason) => void 2829 2830状态机切换事件回调方法。 2831 2832**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2833 2834**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2835 2836| 参数名 | 类型 | 必填 | 说明 | 2837| ------ | ------ | ------ | ---------------------------------------------------------- | 2838| state | [AVPlayerState](#avplayerstate9) | 是 | 当前播放状态。 | 2839| reason | [StateChangeReason](#statechangereason9) | 是 | 当前播放状态的切换原因。 | 2840 2841## OnBufferingUpdateHandler<sup>12+</sup> 2842 2843type OnBufferingUpdateHandler = (infoType: BufferingInfoType, value: number) => void 2844 2845播放缓存事件回调方法。 2846 2847**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2848 2849**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2850 2851| 参数名 | 类型 | 必填 | 说明 | 2852| ------ | ------ | ------ | ------------------------------------------------------------ | 2853| infoType | [BufferingInfoType](#bufferinginfotype8) | 是 | 缓存时间类型。 | 2854| value | number | 是 | value值固定为0。 | 2855 2856## OnVideoSizeChangeHandler<sup>12+</sup> 2857 2858type OnVideoSizeChangeHandler = (width: number, height: number) => void 2859 2860视频播放宽高变化事件回调方法。 2861 2862**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2863 2864**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2865 2866| 参数名 | 类型 | 必填 | 说明 | 2867| ------ | ------ | ------ | ------------------------------------------------------------ | 2868| width | number | 是 | 视频宽度。 | 2869| height | number | 是 | 视频高度。 | 2870 2871## AVFileDescriptor<sup>9+</sup> 2872 2873音视频文件资源描述，一种特殊资源的播放方式，使用场景：应用中的音频资源被连续存储在同一个文件中，需要根据偏移量和长度进行播放。 2874 2875**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2876 2877**系统能力：** SystemCapability.Multimedia.Media.Core 2878 2879| 名称 | 类型 | 必填 | 说明 | 2880| ------ | ------ | ---- | ------------------------------------------------------------ | 2881| 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)获取。 | 2882| offset | number | 否 | 资源偏移量，默认值为0，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 2883| length | number | 否 | 资源长度，默认值为文件中从偏移量开始的剩余字节，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 2884 2885## AVDataSrcDescriptor<sup>10+</sup> 2886 2887音视频文件资源描述，用于DataSource播放方式，使用场景：应用在未获取完整音视频资源时，允许用户创建播放实例并开始播放，达到提前播放的目的。 2888 2889**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2890 2891**系统能力：** SystemCapability.Multimedia.Media.AVPlayer 2892 2893| 名称 | 类型 | 必填 | 说明 | 2894| ------ | ------ | ---- | ------------------------------------------------------------ | 2895| fileSize | number | 是 | 待播放文件大小（字节），-1代表大小未知。如果fileSize设置为-1, 播放模式类似于直播，不能进行seek及setSpeed操作，不能设置loop属性，因此不能重新播放。 | 2896| callback | (buffer: ArrayBuffer, length: number, pos?: number) => number | 是 | 用户设置的回调函数，用于填写数据。<br>- 函数列式：callback: (buffer: ArrayBuffer, length: number, pos?:number) => number;<br>- buffer，ArrayBuffer类型，表示被填写的内存，必选。<br>- length，number类型，表示被填写内存的最大长度，必选。<br>- pos，number类型，表示填写的数据在资源文件中的位置，可选，当fileSize设置为-1时，该参数禁止被使用。 <br>- 返回值，number类型，返回填充数据的长度，返回-1表示到达流的末尾，返回-2表示遇到不可恢复的错误。| 2897 2898## SubtitleInfo<sup>12+</sup> 2899 2900外挂字幕信息，使用场景：订阅外挂字幕事件，回调返回外挂字幕详细信息。 2901 2902**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2903 2904**系统能力：** SystemCapability.Multimedia.Media.Core 2905 2906| 名称 | 类型 | 必填 | 说明 | 2907| ------ | ------ | ---- | ------------------------------------------------------------ | 2908| text | string | 否 | 字幕文本信息。 | 2909| startTime | number | 否 | 显示当前字幕文本的开始时间（单位：毫秒）。 | 2910| duration | number | 否 | 显示当前字幕文本的持续时间（单位：毫秒）。 | 2911 2912## SeekMode<sup>8+</sup> 2913 2914视频播放的Seek模式枚举，可通过seek方法作为参数传递下去。 2915 2916**系统能力：** SystemCapability.Multimedia.Media.Core 2917 2918| 名称 | 值 | 说明 | 2919| -------------- | ---- | ------------------------------------------------------------ | 2920| SEEK_NEXT_SYNC | 0 | 表示跳转到指定时间点的下一个关键帧，建议向后快进的时候用这个枚举值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2921| SEEK_PREV_SYNC | 1 | 表示跳转到指定时间点的上一个关键帧，建议向前快进的时候用这个枚举值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 2922| SEEK_CLOSEST<sup>12+</sup> | 2 | 表示跳转到距离指定时间点最近的帧，建议精准跳转进度的时候用这个枚举值。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2923 2924## SwitchMode<sup>12+</sup> 2925 2926视频播放的selectTrack模式枚举，可通过selectTrack方法作为参数传递下去，当前仅DASH协议视频轨支持该扩展参数。 2927 2928**系统能力：** SystemCapability.Multimedia.Media.Core 2929 2930| 名称 | 值 | 说明 | 2931| -------------- | ---- | ------------------------------------------------------------ | 2932| SMOOTH | 0 | 表示切换后视频平滑播放，该模式切换存在延迟，不会立即生效。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2933| SEGMENT | 1 | 表示切换后从当前分片开始位置播放，该模式立即切换，会有重复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2934| CLOSEST | 2 | 表示从距离当前播放时间点最近的帧开始播放，该模式立即切换，切换后会卡住3到5s，然后恢复播放。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2935 2936## PlaybackSpeed<sup>8+</sup> 2937 2938视频播放的倍速枚举，可通过setSpeed方法作为参数传递下去。 2939 2940**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2941 2942**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 2943 2944| 名称 | 值 | 说明 | 2945| -------------------- | ---- | ------------------------------ | 2946| SPEED_FORWARD_0_75_X | 0 | 表示视频播放正常播速的0.75倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2947| SPEED_FORWARD_1_00_X | 1 | 表示视频播放正常播速。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2948| SPEED_FORWARD_1_25_X | 2 | 表示视频播放正常播速的1.25倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2949| SPEED_FORWARD_1_75_X | 3 | 表示视频播放正常播速的1.75倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2950| SPEED_FORWARD_2_00_X | 4 | 表示视频播放正常播速的2.00倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2951| SPEED_FORWARD_0_50_X<sup>12+</sup> | 5 | 表示视频播放正常播速的0.50倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2952| SPEED_FORWARD_1_50_X<sup>12+</sup> | 6 | 表示视频播放正常播速的1.50倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2953| SPEED_FORWARD_3_00_X<sup>13+</sup> | 7 | 表示视频播放正常播速的3.00倍。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 2954| SPEED_FORWARD_0_25_X<sup>12+</sup> | 8 | 表示视频播放正常播速的0.25倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2955| SPEED_FORWARD_0_125_X<sup>12+</sup> | 9 | 表示视频播放正常播速的0.125倍。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 2956 2957## VideoScaleType<sup>9+</sup> 2958 2959枚举，视频缩放模式。 2960 2961**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2962 2963**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 2964 2965| 名称 | 值 | 说明 | 2966| ------------------------- | ---- | ------------------------------------------------ | 2967| VIDEO_SCALE_TYPE_FIT | 0 | 默认比例类型，视频拉伸至与窗口等大。 | 2968| VIDEO_SCALE_TYPE_FIT_CROP | 1 | 保持视频宽高比拉伸至填满窗口，内容可能会有裁剪。 | 2969 2970## MediaDescription<sup>8+</sup> 2971 2972通过key-value方式获取媒体信息。 2973 2974**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 2975 2976**系统能力：** SystemCapability.Multimedia.Media.Core 2977 2978| 名称 | 类型 | 必填 | 说明 | 2979| ------------- | ------ | ---- | ------------------------------------------------------------ | 2980| [key: string] | Object | 是 | 该键值对支持的key取值范围，请参考[MediaDescriptionKey](#mediadescriptionkey8);每个key值的Object类型和范围，请参考[MediaDescriptionKey](#mediadescriptionkey8)对应Key值的说明 | 2981 2982**示例：** 2983 2984```ts 2985import { BusinessError } from '@kit.BasicServicesKit'; 2986 2987function printfItemDescription(obj: media.MediaDescription, key: string) { 2988 let property: Object = obj[key]; 2989 console.info('audio key is ' + key); // 通过key值获取对应的value。key值具体可见[MediaDescriptionKey]。 2990 console.info('audio value is ' + property); //对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[MediaDescriptionKey]。 2991} 2992 2993let avPlayer: media.AVPlayer | undefined = undefined; 2994media.createAVPlayer((err: BusinessError, player: media.AVPlayer) => { 2995 if(player != null) { 2996 avPlayer = player; 2997 console.info(`Succeeded in creating AVPlayer`); 2998 avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 2999 if (arrList != null) { 3000 for (let i = 0; i < arrList.length; i++) { 3001 printfItemDescription(arrList[i], media.MediaDescriptionKey.MD_KEY_TRACK_TYPE); //打印出每条轨道MD_KEY_TRACK_TYPE的值。 3002 } 3003 } else { 3004 console.error(`Failed to get TrackDescription, error:${error}`); 3005 } 3006 }); 3007 } else { 3008 console.error(`Failed to create AVPlayer, error message:${err.message}`); 3009 } 3010}); 3011``` 3012 3013## PlaybackInfo<sup>12+</sup> 3014 3015通过key-value方式获取播放信息。 3016 3017**系统能力：** SystemCapability.Multimedia.Media.Core 3018 3019| 名称 | 类型 | 必填 | 说明 | 3020| ------------- | ------ | ---- | ------------------------------------------------------------ | 3021| [key: string] | Object | 是 | 该键值对支持的key取值范围，请参考[PlaybackInfoKey](#playbackinfokey12);每个key值的Object类型和范围，请参考[PlaybackInfoKey](#playbackinfokey12)对应Key值的说明。 | 3022 3023**示例：** 3024 3025```ts 3026import { BusinessError } from '@kit.BasicServicesKit'; 3027 3028function printfPlaybackInfo(obj: media.PlaybackInfo, key: string) { 3029 let property: Object = obj[key]; 3030 console.info('key is ' + key); // 通过key值获取对应的value。key值具体可见[PlaybackInfoKey]。 3031 console.info('value is ' + property); //对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[PlaybackInfoKey]。 3032} 3033 3034let avPlayer: media.AVPlayer | undefined = undefined; 3035let playbackInfo: media.PlaybackInfo | undefined = undefined; 3036media.createAVPlayer(async (err: BusinessError, player: media.AVPlayer) => { 3037 if (player != null) { 3038 avPlayer = player; 3039 console.info(`Succeeded in creating AVPlayer`); 3040 if (avPlayer) { 3041 try { 3042 playbackInfo = await avPlayer.getPlaybackInfo(); 3043 console.info(`AVPlayer getPlaybackInfo = ${JSON.stringify(playbackInfo)}`); // 打印整个PlaybackInfo的值。 3044 printfPlaybackInfo(playbackInfo, media.PlaybackInfoKey.SERVER_IP_ADDRESS); // 打印ip的值。 3045 } catch (error) { 3046 console.error(`error = ${error}`); 3047 } 3048 } 3049 } else { 3050 console.error(`Failed to create AVPlayer, error message:${err.message}`); 3051 } 3052}); 3053``` 3054 3055## AVRecorder<sup>9+</sup> 3056 3057音视频录制管理类，用于音视频媒体录制。在调用AVRecorder的方法前，需要先通过[createAVRecorder()](#mediacreateavrecorder9)构建一个AVRecorder实例。 3058 3059音视频录制demo可参考：[音频录制开发指导](../../media/media/using-avrecorder-for-recording.md)、[视频录制开发指导](../../media/media/video-recording.md)。 3060 3061> **说明：** 3062> 3063> 使用相机进行视频录制时，需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/js-apis-camera.md)。 3064 3065### 属性 3066 3067**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3068 3069| 名称 | 类型 | 只读 | 可选 | 说明 | 3070| ------- | ------------------------------------ | ---- | ---- | ------------------ | 3071| state9+ | [AVRecorderState](#avrecorderstate9) | 是 | 否 | 音视频录制的状态。<br>**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 3072 3073### prepare<sup>9+</sup> 3074 3075prepare(config: AVRecorderConfig, callback: AsyncCallback\<void>): void 3076 3077异步方式进行音视频录制的参数设置。通过注册回调函数获取返回值。 3078 3079**需要权限：** ohos.permission.MICROPHONE 3080 3081不涉及音频录制时，可以不需要获取ohos.permission.MICROPHONE权限。 3082 3083使用相机视频录制还需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/js-apis-camera.md)。 3084 3085**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3086 3087**参数：** 3088 3089| 参数名 | 类型 | 必填 | 说明 | 3090| -------- | -------------------------------------- | ---- | ------------------------------------- | 3091| config | [AVRecorderConfig](#avrecorderconfig9) | 是 | 配置音视频录制的相关参数。 | 3092| callback | AsyncCallback\<void> | 是 | 回调函数。当prepare方法成功，err为undefined，否则为错误对象。 | 3093 3094**错误码：** 3095 3096以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3097 3098| 错误码ID | 错误信息 | 3099| -------- | --------------------------------------- | 3100| 201 | Permission denied. Return by callback. | 3101| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3102| 5400102 | Operate not permit. Return by callback. | 3103| 5400105 | Service died. Return by callback. | 3104 3105**示例：** 3106 3107```ts 3108import { BusinessError } from '@kit.BasicServicesKit'; 3109 3110// 配置参数以实际硬件设备支持的范围为准。 3111let avRecorderProfile: media.AVRecorderProfile = { 3112 audioBitrate : 48000, 3113 audioChannels : 2, 3114 audioCodec : media.CodecMimeType.AUDIO_AAC, 3115 audioSampleRate : 48000, 3116 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 3117 videoBitrate : 2000000, 3118 videoCodec : media.CodecMimeType.VIDEO_AVC, 3119 videoFrameWidth : 640, 3120 videoFrameHeight : 480, 3121 videoFrameRate : 30 3122} 3123let avRecorderConfig: media.AVRecorderConfig = { 3124 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 3125 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 3126 profile : avRecorderProfile, 3127 url : 'fd://', // 文件需先由调用者创建，赋予读写权限，将文件fd传给此参数，eg.fd://45 3128 rotation : 0, // 合理值0、90、180、270，非合理值prepare接口将报错。 3129 location : { latitude : 30, longitude : 130 } 3130} 3131 3132avRecorder.prepare(avRecorderConfig, (err: BusinessError) => { 3133 if (err) { 3134 console.error('Failed to prepare and error is ' + err.message); 3135 } else { 3136 console.info('Succeeded in preparing'); 3137 } 3138}) 3139``` 3140 3141### prepare<sup>9+</sup> 3142 3143prepare(config: AVRecorderConfig): Promise\<void> 3144 3145异步方式进行音视频录制的参数设置。通过Promise获取返回值。 3146 3147**需要权限：** ohos.permission.MICROPHONE 3148 3149不涉及音频录制时，可以不需要获ohos.permission.MICROPHONE权限。 3150 3151使用相机视频录制还需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/js-apis-camera.md)。 3152 3153**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3154 3155**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3156 3157**参数：** 3158 3159| 参数名 | 类型 | 必填 | 说明 | 3160| ------ | -------------------------------------- | ---- | -------------------------- | 3161| config | [AVRecorderConfig](#avrecorderconfig9) | 是 | 配置音视频录制的相关参数。 | 3162 3163**返回值：** 3164 3165| 类型 | 说明 | 3166| -------------- | ------------------------------------------ | 3167| Promise\<void> | 异步音视频录制prepare方法的Promise返回值。 | 3168 3169**错误码：** 3170 3171以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3172 3173| 错误码ID | 错误信息 | 3174| -------- | -------------------------------------- | 3175| 201 | Permission denied. Return by promise. | 3176| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3177| 5400102 | Operate not permit. Return by promise. | 3178| 5400105 | Service died. Return by promise. | 3179 3180**示例：** 3181 3182```ts 3183import { BusinessError } from '@kit.BasicServicesKit'; 3184 3185// 配置参数以实际硬件设备支持的范围为准。 3186let avRecorderProfile: media.AVRecorderProfile = { 3187 audioBitrate : 48000, 3188 audioChannels : 2, 3189 audioCodec : media.CodecMimeType.AUDIO_AAC, 3190 audioSampleRate : 48000, 3191 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 3192 videoBitrate : 2000000, 3193 videoCodec : media.CodecMimeType.VIDEO_AVC, 3194 videoFrameWidth : 640, 3195 videoFrameHeight : 480, 3196 videoFrameRate : 30 3197} 3198let avRecorderConfig: media.AVRecorderConfig = { 3199 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 3200 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 3201 profile : avRecorderProfile, 3202 url : 'fd://', // 文件需先由调用者创建，赋予读写权限，将文件fd传给此参数，eg.fd://45 3203 rotation : 0, // 合理值0、90、180、270，非合理值prepare接口报错。 3204 location : { latitude : 30, longitude : 130 } 3205} 3206 3207avRecorder.prepare(avRecorderConfig).then(() => { 3208 console.info('Succeeded in preparing'); 3209}).catch((err: BusinessError) => { 3210 console.error('Failed to prepare and catch error is ' + err.message); 3211}); 3212``` 3213 3214### getInputSurface<sup>9+</sup> 3215 3216getInputSurface(callback: AsyncCallback\<string>): void 3217 3218异步方式获得录制需要的surface。通过注册回调函数获取返回值。此surface提供给调用者，调用者从此surface中获取surfaceBuffer，填入相应的视频数据。 3219 3220应当注意，填入的视频数据需要携带时间戳（单位ns）和buffersize。时间戳的起始时间请以系统启动时间为基准。 3221 3222需在[prepare()](#prepare9-2)事件成功触发后，才能调用getInputSurface()方法。 3223 3224**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3225 3226**参数：** 3227 3228| 参数名 | 类型 | 必填 | 说明 | 3229| -------- | ---------------------- | ---- | --------------------------- | 3230| callback | AsyncCallback\<string> | 是 | 回调函数。当获取surface成功，err为undefined，data为获取到的surfaceId，否则为错误对象。 | 3231 3232**错误码：** 3233 3234以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3235 3236| 错误码ID | 错误信息 | 3237| -------- | --------------------------------------- | 3238| 5400102 | Operate not permit. Return by callback. | 3239| 5400103 | IO error. Return by callback. | 3240| 5400105 | Service died. Return by callback. | 3241 3242**示例：** 3243 3244```ts 3245import { BusinessError } from '@kit.BasicServicesKit'; 3246let surfaceID: string; // 该surfaceID用于传递给相机接口创造videoOutput。 3247 3248avRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 3249 if (err) { 3250 console.error('Failed to do getInputSurface and error is ' + err.message); 3251 } else { 3252 console.info('Succeeded in doing getInputSurface'); 3253 surfaceID = surfaceId; 3254 } 3255}); 3256 3257``` 3258 3259### getInputSurface<sup>9+</sup> 3260 3261getInputSurface(): Promise\<string> 3262 3263异步方式获得录制需要的surface。通过Promise获取返回值。此surface提供给调用者，调用者从此surface中获取surfaceBuffer，填入相应的视频数据。 3264 3265应当注意，填入的视频数据需要携带时间戳（单位ns）和buffersize。时间戳的起始时间请以系统启动时间为基准。 3266 3267需在[prepare()](#prepare9-3)事件成功触发后，才能调用getInputSurface方法。 3268 3269**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3270 3271**返回值：** 3272 3273| 类型 | 说明 | 3274| ---------------- | -------------------------------- | 3275| Promise\<string> | 异步获得surface的Promise返回值。 | 3276 3277**错误码：** 3278 3279以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3280 3281| 错误码ID | 错误信息 | 3282| -------- | -------------------------------------- | 3283| 5400102 | Operate not permit. Return by promise. | 3284| 5400103 | IO error. Return by promise. | 3285| 5400105 | Service died. Return by promise. | 3286 3287**示例：** 3288 3289```ts 3290import { BusinessError } from '@kit.BasicServicesKit'; 3291let surfaceID: string; // 该surfaceID用于传递给相机接口创造videoOutput。 3292 3293avRecorder.getInputSurface().then((surfaceId: string) => { 3294 console.info('Succeeded in getting InputSurface'); 3295 surfaceID = surfaceId; 3296}).catch((err: BusinessError) => { 3297 console.error('Failed to get InputSurface and catch error is ' + err.message); 3298}); 3299``` 3300 3301### updateRotation<sup>12+</sup> 3302 3303updateRotation(rotation: number): Promise\<void> 3304 3305更新视频旋转角度。通过Promise获取返回值。 3306 3307当且仅当[prepare()](#prepare9-3)事件成功触发后，且在[start()](#start9)之前，才能调用updateRotation方法。 3308 3309**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3310 3311**参数：** 3312 3313| 参数名 | 类型 | 必填 | 说明 | 3314| -------- | -------------------- | ---- | --------------------------- | 3315| rotation | number | 是 | 旋转角度，取值仅支持0、90、180、270度。 | 3316 3317**返回值：** 3318 3319| 类型 | 说明 | 3320| ---------------- | -------------------------------- | 3321| Promise\<void> | 异步返回函数执行结果。 | 3322 3323**错误码：** 3324 3325以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 3326 3327| 错误码ID | 错误信息 | 3328| -------- | -------------------------------------- | 3329| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 3330| 5400102 | Operation not allowed. Return by promise. | 3331| 5400103 | IO error. Return by promise. | 3332| 5400105 | Service died. Return by promise. | 3333 3334**示例：** 3335 3336```ts 3337import { BusinessError } from '@kit.BasicServicesKit'; 3338 3339let rotation = 90 3340 3341avRecorder.updateRotation(rotation).then(() => { 3342 console.info('Succeeded in updateRotation'); 3343}).catch((err: BusinessError) => { 3344 console.error('Failed to updateRotation and catch error is ' + err.message); 3345}); 3346``` 3347 3348### start<sup>9+</sup> 3349 3350start(callback: AsyncCallback\<void>): void 3351 3352异步方式开始视频录制。通过注册回调函数获取返回值。 3353 3354纯音频录制需在[prepare()](#prepare9-2)事件成功触发后，才能调用start方法。纯视频录制，音视频录制需在[getInputSurface()](#getinputsurface9)事件成功触发后，才能调用start方法。 3355 3356**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3357 3358**参数：** 3359 3360| 参数名 | 类型 | 必填 | 说明 | 3361| -------- | -------------------- | ---- | ---------------------------- | 3362| callback | AsyncCallback\<void> | 是 |回调函数。当开始录制视频成功，err为undefined，否则为错误对象。 | 3363 3364**错误码：** 3365 3366以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3367 3368| 错误码ID | 错误信息 | 3369| -------- | --------------------------------------- | 3370| 5400102 | Operate not permit. Return by callback. | 3371| 5400103 | IO error. Return by callback. | 3372| 5400105 | Service died. Return by callback. | 3373 3374**示例：** 3375 3376```ts 3377import { BusinessError } from '@kit.BasicServicesKit'; 3378 3379avRecorder.start((err: BusinessError) => { 3380 if (err) { 3381 console.error('Failed to start AVRecorder and error is ' + err.message); 3382 } else { 3383 console.info('Succeeded in starting AVRecorder'); 3384 } 3385}); 3386``` 3387 3388### start<sup>9+</sup> 3389 3390start(): Promise\<void> 3391 3392异步方式开始视频录制。通过Promise获取返回值。 3393 3394纯音频录制需在[prepare()](#prepare9-3)事件成功触发后，才能调用start方法。纯视频录制，音视频录制需在[getInputSurface()](#getinputsurface9-1)事件成功触发后，才能调用start方法。 3395 3396**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3397 3398**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3399 3400**返回值：** 3401 3402| 类型 | 说明 | 3403| -------------- | ------------------------------------- | 3404| Promise\<void> | 异步开始视频录制方法的Promise返回值。 | 3405 3406**错误码：** 3407 3408以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3409 3410| 错误码ID | 错误信息 | 3411| -------- | -------------------------------------- | 3412| 5400102 | Operate not permit. Return by promise. | 3413| 5400103 | IO error. Return by promise. | 3414| 5400105 | Service died. Return by promise. | 3415 3416**示例：** 3417 3418```ts 3419import { BusinessError } from '@kit.BasicServicesKit'; 3420 3421avRecorder.start().then(() => { 3422 console.info('Succeeded in starting AVRecorder'); 3423}).catch((err: BusinessError) => { 3424 console.error('Failed to start AVRecorder and catch error is ' + err.message); 3425}); 3426``` 3427 3428### pause<sup>9+</sup> 3429 3430pause(callback: AsyncCallback\<void>): void 3431 3432异步方式暂停视频录制。通过注册回调函数获取返回值。 3433 3434需要[start()](#start9)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume9)接口来恢复录制。 3435 3436**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3437 3438**参数：** 3439 3440| 参数名 | 类型 | 必填 | 说明 | 3441| -------- | -------------------- | ---- | --------------------------- | 3442| callback | AsyncCallback\<void> | 是 | 回调函数。当暂停视频录制成功，err为undefined，否则为错误对象。 | 3443 3444**错误码：** 3445 3446以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3447 3448| 错误码ID | 错误信息 | 3449| -------- | --------------------------------------- | 3450| 5400102 | Operate not permit. Return by callback. | 3451| 5400103 | IO error. Return by callback. | 3452| 5400105 | Service died. Return by callback. | 3453 3454**示例：** 3455 3456```ts 3457import { BusinessError } from '@kit.BasicServicesKit'; 3458 3459avRecorder.pause((err: BusinessError) => { 3460 if (err) { 3461 console.error('Failed to pause AVRecorder and error is ' + err.message); 3462 } else { 3463 console.info('Succeeded in pausing'); 3464 } 3465}); 3466``` 3467 3468### pause<sup>9+</sup> 3469 3470pause(): Promise\<void> 3471 3472异步方式暂停视频录制。通过Promise获取返回值。 3473 3474需要[start()](#start9-1)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume9-1)接口来恢复录制。 3475 3476**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3477 3478**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3479 3480**返回值：** 3481 3482| 类型 | 说明 | 3483| -------------- | ------------------------------------- | 3484| Promise\<void> | 异步暂停视频录制方法的Promise返回值。 | 3485 3486**错误码：** 3487 3488以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3489 3490| 错误码ID | 错误信息 | 3491| -------- | -------------------------------------- | 3492| 5400102 | Operate not permit. Return by promise. | 3493| 5400103 | IO error. Return by promise. | 3494| 5400105 | Service died. Return by promise. | 3495 3496**示例：** 3497 3498```ts 3499import { BusinessError } from '@kit.BasicServicesKit'; 3500 3501avRecorder.pause().then(() => { 3502 console.info('Succeeded in pausing'); 3503}).catch((err: BusinessError) => { 3504 console.error('Failed to pause AVRecorder and catch error is ' + err.message); 3505}); 3506``` 3507 3508### resume<sup>9+</sup> 3509 3510resume(callback: AsyncCallback\<void>): void 3511 3512异步方式恢复视频录制。通过注册回调函数获取返回值。 3513 3514需要在[pause()](#pause9-2)事件成功触发后，才能调用resume方法。 3515 3516**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3517 3518**参数：** 3519 3520| 参数名 | 类型 | 必填 | 说明 | 3521| -------- | -------------------- | ---- | ---------------------------- | 3522| callback | AsyncCallback\<void> | 是 | 回调函数。当恢复视频录制成功，err为undefined，否则为错误对象。 | 3523 3524**错误码：** 3525 3526以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3527 3528| 错误码ID | 错误信息 | 3529| -------- | --------------------------------------- | 3530| 5400102 | Operate not permit. Return by callback. | 3531| 5400103 | IO error. Return by callback. | 3532| 5400105 | Service died. Return by callback. | 3533 3534**示例：** 3535 3536```ts 3537import { BusinessError } from '@kit.BasicServicesKit'; 3538 3539avRecorder.resume((err: BusinessError) => { 3540 if (err) { 3541 console.error('Failed to resume AVRecorder and error is ' + err.message); 3542 } else { 3543 console.info('Succeeded in resuming AVRecorder'); 3544 } 3545}); 3546``` 3547 3548### resume<sup>9+</sup> 3549 3550resume(): Promise\<void> 3551 3552异步方式恢复视频录制。通过Promise获取返回值。 3553 3554需要在[pause()](#pause9-3)事件成功触发后，才能调用resume方法。 3555 3556**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3557 3558**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3559 3560**返回值：** 3561 3562| 类型 | 说明 | 3563| -------------- | ------------------------------------- | 3564| Promise\<void> | 异步恢复视频录制方法的Promise返回值。 | 3565 3566**错误码：** 3567 3568以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3569 3570| 错误码ID | 错误信息 | 3571| -------- | -------------------------------------- | 3572| 5400102 | Operate not permit. Return by promise. | 3573| 5400103 | IO error. Return by promise. | 3574| 5400105 | Service died. Return by promise. | 3575 3576**示例：** 3577 3578```ts 3579import { BusinessError } from '@kit.BasicServicesKit'; 3580 3581avRecorder.resume().then(() => { 3582 console.info('Succeeded in resuming AVRecorder'); 3583}).catch((err: BusinessError) => { 3584 console.error('Failed to resume AVRecorder failed and catch error is ' + err.message); 3585}); 3586``` 3587 3588### stop<sup>9+</sup> 3589 3590stop(callback: AsyncCallback\<void>): void 3591 3592异步方式停止视频录制。通过注册回调函数获取返回值。 3593 3594需要在[start()](#start9)或[pause()](#pause9-2)事件成功触发后，才能调用stop方法。 3595 3596纯音频录制时，需要重新调用[prepare()](#prepare9-2)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-2)和[getInputSurface()](#getinputsurface9)接口才能重新录制。 3597 3598**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3599 3600**参数：** 3601 3602| 参数名 | 类型 | 必填 | 说明 | 3603| -------- | -------------------- | ---- | ---------------------------- | 3604| callback | AsyncCallback\<void> | 是 | 回调函数。当停止视频录制成功，err为undefined，否则为错误对象。 | 3605 3606**错误码：** 3607 3608以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3609 3610| 错误码ID | 错误信息 | 3611| -------- | --------------------------------------- | 3612| 5400102 | Operate not permit. Return by callback. | 3613| 5400103 | IO error. Return by callback. | 3614| 5400105 | Service died. Return by callback. | 3615 3616**示例：** 3617 3618```ts 3619import { BusinessError } from '@kit.BasicServicesKit'; 3620 3621avRecorder.stop((err: BusinessError) => { 3622 if (err) { 3623 console.error('Failed to stop AVRecorder and error is ' + err.message); 3624 } else { 3625 console.info('Succeeded in stopping AVRecorder'); 3626 } 3627}); 3628``` 3629 3630### stop<sup>9+</sup> 3631 3632stop(): Promise\<void> 3633 3634异步方式停止视频录制。通过Promise获取返回值。 3635 3636需要在[start()](#start9-1)或[pause()](#pause9-3)事件成功触发后，才能调用stop方法。 3637 3638纯音频录制时，需要重新调用[prepare()](#prepare9-3)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-3)和[getInputSurface()](#getinputsurface9-1)接口才能重新录制。 3639 3640**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3641 3642**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3643 3644**返回值：** 3645 3646| 类型 | 说明 | 3647| -------------- | ------------------------------------- | 3648| Promise\<void> | 异步停止视频录制方法的Promise返回值。 | 3649 3650**错误码：** 3651 3652以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3653 3654| 错误码ID | 错误信息 | 3655| -------- | -------------------------------------- | 3656| 5400102 | Operate not permit. Return by promise. | 3657| 5400103 | IO error. Return by promise. | 3658| 5400105 | Service died. Return by promise. | 3659 3660**示例：** 3661 3662```ts 3663import { BusinessError } from '@kit.BasicServicesKit'; 3664 3665avRecorder.stop().then(() => { 3666 console.info('Succeeded in stopping AVRecorder'); 3667}).catch((err: BusinessError) => { 3668 console.error('Failed to stop AVRecorder and catch error is ' + err.message); 3669}); 3670``` 3671 3672### reset<sup>9+</sup> 3673 3674reset(callback: AsyncCallback\<void>): void 3675 3676异步方式重置音视频录制。通过注册回调函数获取返回值。 3677 3678纯音频录制时，需要重新调用[prepare()](#prepare9-2)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-2)和[getInputSurface()](#getinputsurface9)接口才能重新录制。 3679 3680**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3681 3682**参数：** 3683 3684| 参数名 | 类型 | 必填 | 说明 | 3685| -------- | -------------------- | ---- | ------------------------------ | 3686| callback | AsyncCallback\<void> | 是 | 回调函数。当重置音视频录制成功，err为undefined，否则为错误对象。 | 3687 3688**错误码：** 3689 3690以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3691 3692| 错误码ID | 错误信息 | 3693| -------- | --------------------------------- | 3694| 5400103 | IO error. Return by callback. | 3695| 5400105 | Service died. Return by callback. | 3696 3697**示例：** 3698 3699```ts 3700import { BusinessError } from '@kit.BasicServicesKit'; 3701 3702avRecorder.reset((err: BusinessError) => { 3703 if (err) { 3704 console.error('Failed to reset AVRecorder and error is ' + err.message); 3705 } else { 3706 console.info('Succeeded in resetting AVRecorder'); 3707 } 3708}); 3709``` 3710 3711### reset<sup>9+</sup> 3712 3713reset(): Promise\<void> 3714 3715异步方式重置音视频录制。通过Promise获取返回值。 3716 3717纯音频录制时，需要重新调用[prepare()](#prepare9-3)接口才能重新录制。纯视频录制，音视频录制时，需要重新调用[prepare()](#prepare9-3)和[getInputSurface()](#getinputsurface9-1)接口才能重新录制。 3718 3719**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3720 3721**返回值：** 3722 3723| 类型 | 说明 | 3724| -------------- | --------------------------------------- | 3725| Promise\<void> | 异步重置音视频录制方法的Promise返回值。 | 3726 3727**错误码：** 3728 3729以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3730 3731| 错误码ID | 错误信息 | 3732| -------- | -------------------------------- | 3733| 5400103 | IO error. Return by promise. | 3734| 5400105 | Service died. Return by promise. | 3735 3736**示例：** 3737 3738```ts 3739import { BusinessError } from '@kit.BasicServicesKit'; 3740 3741avRecorder.reset().then(() => { 3742 console.info('Succeeded in resetting AVRecorder'); 3743}).catch((err: BusinessError) => { 3744 console.error('Failed to reset and catch error is ' + err.message); 3745}); 3746``` 3747 3748### release<sup>9+</sup> 3749 3750release(callback: AsyncCallback\<void>): void 3751 3752异步方式释放音视频录制资源。通过注册回调函数获取返回值。 3753 3754释放音视频录制资源之后，该AVRecorder实例不能再进行任何操作。 3755 3756**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3757 3758**参数：** 3759 3760| 参数名 | 类型 | 必填 | 说明 | 3761| -------- | -------------------- | ---- | ---------------------------------- | 3762| callback | AsyncCallback\<void> | 是 | 回调函数。当释放音视频录制资源成功，err为undefined，否则为错误对象。 | 3763 3764**错误码：** 3765 3766以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3767 3768| 错误码ID | 错误信息 | 3769| -------- | --------------------------------- | 3770| 5400105 | Service died. Return by callback. | 3771 3772**示例：** 3773 3774```ts 3775import { BusinessError } from '@kit.BasicServicesKit'; 3776 3777avRecorder.release((err: BusinessError) => { 3778 if (err) { 3779 console.error('Failed to release AVRecorder and error is ' + err.message); 3780 } else { 3781 console.info('Succeeded in releasing AVRecorder'); 3782 } 3783}); 3784``` 3785 3786### release<sup>9+</sup> 3787 3788release(): Promise\<void> 3789 3790异步方式释放音视频录制资源。通过Promise获取返回值。 3791 3792释放音视频录制资源之后，该AVRecorder实例不能再进行任何操作。 3793 3794**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 3795 3796**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 3797 3798**返回值：** 3799 3800| 类型 | 说明 | 3801| -------------- | ------------------------------------------- | 3802| Promise\<void> | 异步释放音视频录制资源方法的Promise返回值。 | 3803 3804**错误码：** 3805 3806以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3807 3808| 错误码ID | 错误信息 | 3809| -------- | --------------------------------- | 3810| 5400105 | Service died. Return by callback. | 3811 3812**示例：** 3813 3814```ts 3815import { BusinessError } from '@kit.BasicServicesKit'; 3816 3817avRecorder.release().then(() => { 3818 console.info('Succeeded in releasing AVRecorder'); 3819}).catch((err: BusinessError) => { 3820 console.error('Failed to release AVRecorder and catch error is ' + err.message); 3821}); 3822``` 3823 3824### getCurrentAudioCapturerInfo<sup>11+</sup> 3825 3826getCurrentAudioCapturerInfo(callback: AsyncCallback\<audio.AudioCapturerChangeInfo>): void 3827 3828异步方式获取当前音频采集参数。通过注册回调函数获取返回值。 3829 3830在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 3831 3832**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3833 3834**参数**： 3835 3836| 参数名 | 类型 | 必填 | 说明 | 3837| -------- | ------------------------------------------------------------ | ---- | ------------------------------------ | 3838| callback | AsyncCallback\<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 是 | 回调函数。当获取音频采集参数成功时，err为undefined，data为获取到的audio.AudioCapturerChangeInfo，否则为错误对象。 | 3839 3840**错误码**： 3841 3842以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3843 3844| 错误码ID | 错误信息 | 3845| -------- | ------------------------------------------ | 3846| 5400102 | Operation not allowed. | 3847| 5400103 | I/O error. | 3848| 5400105 | Service died. Return by callback. | 3849 3850**示例**： 3851 3852```ts 3853import { audio } from '@kit.AudioKit'; 3854 3855let currentCapturerInfo: audio.AudioCapturerChangeInfo; 3856 3857avRecorder.getCurrentAudioCapturerInfo((err: BusinessError, capturerInfo: audio.AudioCapturerChangeInfo) => { 3858 if (err) { 3859 console.error('Failed to get CurrentAudioCapturerInfo and error is ' + err.message); 3860 } else { 3861 console.info('Succeeded in getting CurrentAudioCapturerInfo'); 3862 currentCapturerInfo = capturerInfo; 3863 } 3864}); 3865``` 3866 3867### getCurrentAudioCapturerInfo<sup>11+</sup> 3868 3869getCurrentAudioCapturerInfo(): Promise\<audio.AudioCapturerChangeInfo> 3870 3871异步方式获取当前音频采集参数。通过Promise获取返回值。 3872 3873在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 3874 3875**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3876 3877**返回值**： 3878 3879| 类型 | 说明 | 3880| ------------------------------------------------------------ | ------------------------------------------------- | 3881| Promise\<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | Promise对象，返回获取的当前音频采集参数。 | 3882 3883**错误码**： 3884 3885以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3886 3887| 错误码ID | 错误信息 | 3888| -------- | -------------------------------- | 3889| 5400102 | Operation not allowed. | 3890| 5400103 | I/O error. | 3891| 5400105 | Service died. Return by promise. | 3892 3893**示例**： 3894 3895```ts 3896import { audio } from '@kit.AudioKit'; 3897 3898let currentCapturerInfo: audio.AudioCapturerChangeInfo; 3899 3900avRecorder.getCurrentAudioCapturerInfo().then((capturerInfo: audio.AudioCapturerChangeInfo) => { 3901 console.info('Succeeded in getting CurrentAudioCapturerInfo'); 3902 currentCapturerInfo = capturerInfo; 3903}).catch((err: BusinessError) => { 3904 console.error('Failed to get CurrentAudioCapturerInfo and catch error is ' + err.message); 3905}); 3906``` 3907 3908### getAudioCapturerMaxAmplitude<sup>11+</sup> 3909 3910getAudioCapturerMaxAmplitude(callback: AsyncCallback\<number>): void 3911 3912异步方式获取当前音频最大振幅。通过注册回调函数获取返回值。 3913 3914在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 3915 3916调用接口时，获取到的返回值是上一次获取最大振幅的时刻到当前这段区间内的音频最大振幅。即，如果在1s的时刻获取了一次最大振幅，在2s时再获取到的最大振幅时1-2s这个区间里面的最大值。 3917 3918**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3919 3920**参数**： 3921 3922| 参数名 | 类型 | 必填 | 说明 | 3923| -------- | ---------------------- | ---- | ------------------------------------ | 3924| callback | AsyncCallback\<number> | 是 | 回调函数。获取当前音频最大振幅成功时，err为undefined，data为获取到的最大振幅，否则为错误对象。 | 3925 3926**错误码**： 3927 3928以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3929 3930| 错误码ID | 错误信息 | 3931| -------- | ------------------------------------------ | 3932| 5400102 | Operation not allowed. | 3933| 5400105 | Service died. Return by callback. | 3934 3935**示例**： 3936 3937```ts 3938let maxAmplitude: number; 3939 3940avRecorder.getAudioCapturerMaxAmplitude((err: BusinessError, amplitude: number) => { 3941 if (err) { 3942 console.error('Failed to get AudioCapturerMaxAmplitude and error is ' + err.message); 3943 } else { 3944 console.info('Succeeded in getting AudioCapturerMaxAmplitude'); 3945 maxAmplitude = amplitude; 3946 } 3947}); 3948``` 3949 3950### getAudioCapturerMaxAmplitude<sup>11+</sup> 3951 3952getAudioCapturerMaxAmplitude(): Promise\<number> 3953 3954异步方式获取当前音频最大振幅参数。通过Promise获取返回值。 3955 3956在prepare()成功触发后，才能调用此方法。在stop()成功触发后，调用此方法会报错。 3957 3958调用接口时，获取到的返回值是上一次获取最大振幅的时刻到当前这段区间内的音频最大振幅。即，如果在1s的时刻获取了一次最大振幅，在2s时再获取到的最大振幅时1-2s这个区间里面的最大值。 3959 3960**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3961 3962**返回值**： 3963 3964| 类型 | 说明 | 3965| ---------------- | ------------------------------------------------- | 3966| Promise\<number> | Promise对象，返回获取的当前音频最大振幅。 | 3967 3968**错误码**： 3969 3970以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 3971 3972| 错误码ID | 错误信息 | 3973| -------- | -------------------------------- | 3974| 5400102 | Operation not allowed. | 3975| 5400105 | Service died. Return by promise. | 3976 3977**示例**： 3978 3979```ts 3980let maxAmplitude: number; 3981 3982avRecorder.getAudioCapturerMaxAmplitude().then((amplitude: number) => { 3983 console.info('Succeeded in getting AudioCapturerMaxAmplitude'); 3984 maxAmplitude = amplitude; 3985}).catch((err: BusinessError) => { 3986 console.error('Failed to get AudioCapturerMaxAmplitude and catch error is ' + err.message); 3987}); 3988``` 3989 3990### getAvailableEncoder<sup>11+</sup> 3991 3992getAvailableEncoder(callback: AsyncCallback\<Array\<EncoderInfo>>): void 3993 3994异步方式获取可用的编码器参数。通过注册回调函数获取返回值。 3995 3996**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 3997 3998**参数**： 3999 4000| 参数名 | 类型 | 必填 | 说明 | 4001| -------- | ----------------------------------------------------- | ---- | ------------------------------------ | 4002| callback | AsyncCallback\<Array\<[EncoderInfo](#encoderinfo11)>> | 是 | 回调函数。获取可用的编码器参数成功时，err为undefined，data为获取到的编码器参数，否则为错误对象。 | 4003 4004**错误码**： 4005 4006以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4007 4008| 错误码ID | 错误信息 | 4009| -------- | ------------------------------------------ | 4010| 5400102 | Operation not allowed. | 4011| 5400105 | Service died. Return by callback. | 4012 4013**示例**： 4014 4015```ts 4016let encoderInfo: media.EncoderInfo; 4017 4018avRecorder.getAvailableEncoder((err: BusinessError, info: media.EncoderInfo[]) => { 4019 if (err) { 4020 console.error('Failed to get AvailableEncoder and error is ' + err.message); 4021 } else { 4022 console.info('Succeeded in getting AvailableEncoder'); 4023 encoderInfo = info[0]; 4024 } 4025}); 4026``` 4027 4028### getAvailableEncoder<sup>11+</sup> 4029 4030getAvailableEncoder(): Promise\<Array\<EncoderInfo>> 4031 4032异步方式获取可用的编码器参数。通过注册回调函数获取返回值。 4033 4034**系统能力**：SystemCapability.Multimedia.Media.AVRecorder 4035 4036**返回值**： 4037 4038| 类型 | 说明 | 4039| ----------------------------------------------- | ----------------------------------------------- | 4040| Promise\<Array\<[EncoderInfo](#encoderinfo11)>> | Promise对象，返回获取的可用的编码器参数。 | 4041 4042**错误码**： 4043 4044以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4045 4046| 错误码ID | 错误信息 | 4047| -------- | -------------------------------- | 4048| 5400102 | Operation not allowed. | 4049| 5400105 | Service died. Return by promise. | 4050 4051**示例**： 4052 4053```ts 4054let encoderInfo: media.EncoderInfo; 4055 4056avRecorder.getAvailableEncoder().then((info: media.EncoderInfo[]) => { 4057 console.info('Succeeded in getting AvailableEncoder'); 4058 encoderInfo = info[0]; 4059}).catch((err: BusinessError) => { 4060 console.error('Failed to get AvailableEncoder and catch error is ' + err.message); 4061}); 4062``` 4063 4064### getAVRecorderConfig<sup>11+</sup> 4065 4066getAVRecorderConfig(callback: AsyncCallback\<AVRecorderConfig>): void 4067 4068异步方式获取实时的配置参数。通过注册回调函数获取返回值。 4069 4070只能在[prepare()](#prepare9-2)接口调用后调用。 4071 4072**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4073 4074**参数：** 4075 4076| 参数名 | 类型 | 必填 | 说明 | 4077| -------- | ---------------------- | ---- | --------------------------- | 4078| callback | AsyncCallback\<[AVRecorderConfig](#avrecorderconfig9)> | 是 | 回调函数。获取实时配置的参数成功时，err为undefined，data为获取到的配置参数，否则为错误对象。 | 4079 4080**错误码：** 4081 4082以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 4083 4084| 错误码ID | 错误信息 | 4085| -------- | ------------------------------------------ | 4086| 5400102 | Operate not permit. Return by callback. | 4087| 5400103 | IO error. Return by callback. | 4088| 5400105 | Service died. Return by callback. | 4089 4090**示例：** 4091 4092```ts 4093import { BusinessError } from '@kit.BasicServicesKit'; 4094 4095let avConfig: media.AVRecorderConfig; 4096 4097avRecorder.getAVRecorderConfig((err: BusinessError, config: media.AVRecorderConfig) => { 4098 if (err) { 4099 console.error('Failed to get avConfig and error is ' + err.message); 4100 } else { 4101 console.info('Succeeded in getting AVRecorderConfig'); 4102 avConfig = config; 4103 } 4104}); 4105``` 4106 4107### getAVRecorderConfig<sup>11+</sup> 4108 4109getAVRecorderConfig(): Promise\<AVRecorderConfig>; 4110 4111异步方式获取实时的配置参数。通过Promise获取返回值。 4112 4113只能在[prepare()](#prepare9-3)接口调用后调用。 4114 4115**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4116 4117**返回值：** 4118 4119| 类型 | 说明 | 4120| ---------------- | -------------------------------- | 4121| Promise\<[AVRecorderConfig](#avrecorderconfig9)> | 异步获得实时配置参数的回调方法。 | 4122 4123**错误码：** 4124 4125以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 4126 4127| 错误码ID | 错误信息 | 4128| -------- | ----------------------------------------- | 4129| 5400102 | Operate not permit. Return by promise. | 4130| 5400103 | IO error. Return by promise. | 4131| 5400105 | Service died. Return by promise. | 4132 4133**示例：** 4134 4135```ts 4136import { BusinessError } from '@kit.BasicServicesKit'; 4137 4138let avConfig: media.AVRecorderConfig; 4139 4140avRecorder.getAVRecorderConfig().then((config: media.AVRecorderConfig) => { 4141 console.info('Succeeded in getting AVRecorderConfig'); 4142 avConfig = config; 4143}).catch((err: BusinessError) => { 4144 console.error('Failed to get AVRecorderConfig and catch error is ' + err.message); 4145}); 4146``` 4147 4148### on('stateChange')<sup>9+</sup> 4149 4150on(type: 'stateChange', callback: OnAVRecorderStateChangeHandler): void 4151 4152订阅录制状态机AVRecorderState切换的事件，当 AVRecorderState状态机发生变化时，会通过订阅的回调方法通知用户。用户只能订阅一个状态机切换事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 4153 4154**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4155 4156**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4157 4158**参数：** 4159 4160| 参数名 | 类型 | 必填 | 说明 | 4161| -------- | -------- | ---- | ------------------------------------------------------------ | 4162| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 4163| callback | [OnAVRecorderStateChangeHandler](#onavrecorderstatechangehandler12) | 是 | 状态机切换事件回调方法。 | 4164 4165**错误码：** 4166 4167以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4168 4169| 错误码ID | 错误信息 | 4170| -------- | --------------------------------- | 4171| 5400103 | IO error. Return by callback. | 4172| 5400105 | Service died. Return by callback. | 4173 4174**示例：** 4175 4176```ts 4177avRecorder.on('stateChange', async (state: media.AVRecorderState, reason: media.StateChangeReason) => { 4178 console.info('case state has changed, new state is :' + state + ',and new reason is : ' + reason); 4179}); 4180``` 4181 4182### off('stateChange')<sup>9+</sup> 4183 4184off(type: 'stateChange', callback?: OnAVRecorderStateChangeHandler): void 4185 4186取消订阅播放状态机[AVRecorderState](#avrecorderstate9)切换的事件。 4187 4188**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4189 4190**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4191 4192**参数：** 4193 4194| 参数名 | 类型 | 必填 | 说明 | 4195| ------ | ------ | ---- | ------------------------------------------------------------ | 4196| type | string | 是 | 状态机切换事件回调类型，支持的事件：'stateChange'，用户操作和系统都会触发此事件。 | 4197| callback | [OnAVRecorderStateChangeHandler](#onavrecorderstatechangehandler12) | 否 | 状态机切换事件回调方法。<br/>从API version 12开始支持此参数。 | 4198 4199**示例：** 4200 4201```ts 4202avRecorder.off('stateChange'); 4203``` 4204 4205### on('error')<sup>9+</sup> 4206 4207on(type: 'error', callback: ErrorCallback): void 4208 4209订阅AVRecorder的错误事件，该事件仅用于错误提示，不需要用户停止播控动作。如果此时[AVRecorderState](#avrecorderstate9)也切至error状态，用户需要通过[reset()](#reset9-2)或者[release()](#release9-2)退出录制操作。 4210 4211用户只能订阅一个错误事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 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) | 是 | 录制错误事件回调方法。 | 4223 4224**错误码：** 4225 4226以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4227 4228| 错误码ID | 错误信息 | 4229| -------- | ------------------------------------------ | 4230| 201 | Permission denied. | 4231| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 4232| 801 | Capability not supported. | 4233| 5400101 | No memory. | 4234| 5400102 | Operation not allowed. | 4235| 5400103 | I/O error. | 4236| 5400104 | Time out. | 4237| 5400105 | Service died. | 4238| 5400106 | Unsupported format. | 4239| 5400107 | Audio interrupted. | 4240 4241**示例：** 4242 4243```ts 4244import { BusinessError } from '@kit.BasicServicesKit'; 4245 4246avRecorder.on('error', (err: BusinessError) => { 4247 console.info('case avRecorder.on(error) called, errMessage is ' + err.message); 4248}); 4249``` 4250 4251### off('error')<sup>9+</sup> 4252 4253off(type: 'error', callback?: ErrorCallback): void 4254 4255取消订阅录制错误事件，取消后不再接收到AVRecorder的错误事件。 4256 4257**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4258 4259**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4260 4261**参数：** 4262 4263| 参数名 | 类型 | 必填 | 说明 | 4264| ------ | ------ | ---- | ------------------------------------------------------------ | 4265| type | string | 是 | 录制错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 4266| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 录制错误事件回调方法。<br/>从API version 12开始支持此参数。 | 4267 4268**示例：** 4269 4270```ts 4271avRecorder.off('error'); 4272``` 4273 4274### on('audioCapturerChange')<sup>11+</sup> 4275 4276on(type: 'audioCapturerChange', callback: Callback<audio.AudioCapturerChangeInfo>): void 4277 4278订阅录音配置变化的回调，任意录音配置的变化会触发变化后的录音配置全量信息回调。 4279 4280当用户重复订阅时，以最后一次订阅的回调接口为准。 4281 4282**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4283 4284**参数：** 4285 4286| 参数名 | 类型 | 必填 | 说明 | 4287| -------- | -------- | ---- | ------------------------------------------------------------ | 4288| type | string | 是 |录音配置变化的回调类型，支持的事件：'audioCapturerChange'。 | 4289| callback | Callback<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 是 | 变化后的录音配置全量信息。| 4290 4291**错误码：** 4292 4293| 错误码ID | 错误信息 | 4294| -------- | ------------------------------------------ | 4295| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 4296 4297**示例：** 4298 4299```ts 4300import { audio } from '@kit.AudioKit' 4301 4302let capturerChangeInfo: audio.AudioCapturerChangeInfo; 4303 4304avRecorder.on('audioCapturerChange', (audioCapturerChangeInfo: audio.AudioCapturerChangeInfo) => { 4305 console.info('audioCapturerChange called'); 4306 capturerChangeInfo = audioCapturerChangeInfo; 4307}); 4308``` 4309 4310### off('audioCapturerChange')<sup>11+</sup> 4311 4312off(type: 'audioCapturerChange', callback?: Callback<audio.AudioCapturerChangeInfo>): void 4313 4314取消订阅录音变化的回调事件。 4315 4316**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4317 4318**参数：** 4319 4320| 参数名 | 类型 | 必填 | 说明 | 4321| ------ | ------ | ---- | ------------------------------------------------------------ | 4322| type | string | 是 | 录音配置变化的回调类型，支持的事件：'audioCapturerChange'。 | 4323| callback | Callback<[audio.AudioCapturerChangeInfo](../apis-audio-kit/js-apis-audio.md#audiocapturerchangeinfo9)> | 否 | 变化后的录音配置全量信息。<br/>从API version 12开始支持此参数。| 4324 4325**示例：** 4326 4327```ts 4328avRecorder.off('audioCapturerChange'); 4329``` 4330 4331### on('photoAssetAvailable')<sup>12+</sup> 4332 4333on(type: 'photoAssetAvailable', callback: Callback\<photoAccessHelper.PhotoAsset>): void 4334 4335订阅媒体资源回调事件，当[FileGenerationMode](#filegenerationmode12)枚举设置为系统创建媒体文件时，会在[stop](#stop9-2)操作结束后把[PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)对象回调给应用。 4336 4337当用户重复订阅时，以最后一次订阅的回调接口为准。 4338 4339**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4340 4341**参数：** 4342 4343| 参数名 | 类型 | 必填 | 说明 | 4344| -------- | -------- | ---- | ------------------------------------------------------------ | 4345| type | string | 是 |录像资源的回调类型，支持的事件：'photoAssetAvailable'。 | 4346| callback | Callback<[photoAccessHelper.PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)> | 是 | 系统创建的资源文件对应的PhotoAsset对象。| 4347 4348**错误码：** 4349 4350| 错误码ID | 错误信息 | 4351| -------- | ------------------------------------------ | 4352| 5400103 | IO error. Return by callback. | 4353| 5400105 | Service died. Return by callback. | 4354 4355**示例：** 4356 4357<!--code_no_check--> 4358```ts 4359import { photoAccessHelper } from '@kit.MediaLibraryKit'; 4360import { common } from '@kit.AbilityKit' 4361let photoAsset: photoAccessHelper.PhotoAsset; 4362let context = getContext(this) as common.UIAbilityContext 4363 4364// 例:处理photoAsset回调，保存video。 4365async function saveVideo(asset: photoAccessHelper.PhotoAsset) { 4366 console.info("saveVideo called"); 4367 try { 4368 let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context); 4369 let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset); 4370 assetChangeRequest.saveCameraPhoto(); 4371 await phAccessHelper.applyChanges(assetChangeRequest); 4372 console.info('apply saveVideo successfully'); 4373 } catch (err) { 4374 console.error(`apply saveVideo failed with error: ${err.code}, ${err.message}`); 4375 } 4376} 4377// 注册photoAsset监听。 4378avRecorder.on('photoAssetAvailable', (asset: photoAccessHelper.PhotoAsset) => { 4379 console.info('photoAssetAvailable called'); 4380 if (asset != undefined) { 4381 photoAsset = asset; 4382 // 处理photoAsset回调。 4383 // 例: this.saveVideo(asset); 4384 } else { 4385 console.error('photoAsset is undefined'); 4386 } 4387}); 4388``` 4389 4390### off('photoAssetAvailable')<sup>12+</sup> 4391 4392off(type: 'photoAssetAvailable', callback?: Callback<photoAccessHelper.PhotoAsset>): void 4393 4394取消订阅媒体资源的回调类型。 4395 4396**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4397 4398**参数：** 4399 4400| 参数名 | 类型 | 必填 | 说明 | 4401| ------ | ------ | ---- | ------------------------------------------------------------ | 4402| type | string | 是 | 录音配置变化的回调类型，支持的事件：'photoAssetAvailable'。 | 4403| callback | Callback<[photoAccessHelper.PhotoAsset](../apis-media-library-kit/js-apis-photoAccessHelper.md#photoasset)> | 否 | 系统创建的资源文件对应的PhotoAsset对象。| 4404 4405**示例：** 4406 4407```ts 4408avRecorder.off('photoAssetAvailable'); 4409``` 4410 4411## AVRecorderState<sup>9+</sup> 4412 4413type AVRecorderState = 'idle' | 'prepared' | 'started' | 'paused' | 'stopped' | 'released' | 'error' 4414 4415音视频录制的状态机。可通过state属性获取当前状态。 4416 4417**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 4418 4419**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4420 4421| 类型 | 说明 | 4422| -------- | ------------------------------------------------------------ | 4423| 'idle' | 闲置状态。此时可以调用[AVRecorder.prepare()](#prepare9-2)方法设置录制参数，进入prepared状态。AVRecorder刚被创建，或者在任何非released状态下调用[AVRecorder.reset()](#reset9-2)方法，均进入idle状态。 | 4424| 'prepared' | 参数设置完成。此时可以调用[AVRecorder.start()](#start9)方法开始录制，进入started状态。 | 4425| 'started' | 正在录制。此时可以调用[AVRecorder.pause()](#pause9-2)方法暂停录制，进入paused状态。也可以调用[AVRecorder.stop()](#stop9-2)方法结束录制，进入stopped状态。 | 4426| 'paused' | 录制暂停。此时可以调用[AVRecorder.resume()](#resume9)方法继续录制，进入started状态。也可以调用[AVRecorder.stop()](#stop9-2)方法结束录制，进入stopped状态。 | 4427| 'stopped' | 录制停止。此时可以调用[AVRecorder.prepare()](#prepare9-2)方法设置录制参数，重新进入prepared状态。 | 4428| 'released' | 录制资源释放。此时不能再进行任何操作。在任何其他状态下，均可以通过调用[AVRecorder.release()](#release9-2)方法进入released状态。 | 4429| 'error' | 错误状态。当AVRecorder实例发生不可逆错误，会转换至当前状态。切换至error状态时会伴随[AVRecorder.on('error')事件](#onerror9-1)，该事件会上报详细错误原因。在error状态时，用户需要调用[AVRecorder.reset()](#reset9-2)方法重置AVRecorder实例，或者调用[AVRecorder.release()](#release9-2)方法释放资源。 | 4430 4431## OnAVRecorderStateChangeHandler<sup>12+</sup> 4432 4433type OnAVRecorderStateChangeHandler = (state: AVRecorderState, reason: StateChangeReason) => void 4434 4435状态机切换事件回调方法。 4436 4437**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 4438 4439**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4440 4441| 参数名 | 类型 | 必填 | 说明 | 4442| ------ | ------ | ------ | ------------------------------------------------------------ | 4443| state | [AVRecorderState](#avrecorderstate9) | 必填 | 当前录制状态。 | 4444| reason | [StateChangeReason](#statechangereason9) | 必填 | 当前录制状态的切换原因。 | 4445 4446## AVRecorderConfig<sup>9+</sup> 4447 4448表示音视频录制的参数设置。 4449 4450通过audioSourceType和videoSourceType区分纯音频录制、纯视频录制或音视频录制。纯音频录制时，仅需要设置audioSourceType；纯视频录制时，仅需要设置videoSourceType；音视频录制时，audioSourceType和videoSourceType均需要设置。 4451 4452**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4453 4454| 名称 | 类型 | 必填 | 说明 | 4455| --------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 4456| audioSourceType | [AudioSourceType](#audiosourcetype9) | 否 | 选择录制的音频源类型。选择音频录制时必填。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4457| videoSourceType | [VideoSourceType](#videosourcetype9) | 否 | 选择录制的视频源类型。选择视频录制时必填。 | 4458| profile | [AVRecorderProfile](#avrecorderprofile9) | 是 | 录制的profile，必要参数。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4459| url | string | 是 | 录制输出URL：fd://xx (fd number) ，必要参数。 <br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4460|fileGenerationMode<sup>12+</sup> | [FileGenerationMode](#filegenerationmode12) | 否 | 创建媒体文件的模式，配合[on('photoAssetAvailable')](#onphotoassetavailable12)监听使用。| 4461| rotation<sup>(deprecated)</sup> | number | 否 | 录制的视频旋转角度，mp4格式支持0，90，180，270，默认值为0。<br>从API version 6开始支持，从API version 12开始废弃。建议使用[AVMetadata](#avmetadata11).videoOrientation替代。如果同时设置两个值，将会采用[AVMetadata](#avmetadata11).videoOrientation。 | 4462| location<sup>(deprecated)</sup> | [Location](#location) | 否 | 录制的地理位置，默认不记录地理位置信息。<br>从API version 6开始支持，从API version 12开始废弃。建议使用 [AVMetadata](#avmetadata11).location。如果同时设置两个值，将会采用[AVMetadata](#avmetadata11).location。 | 4463| metadata<sup>12+</sup> | [AVMetadata](#avmetadata11) | 否 | 设置元数据信息。详情见 [AVMetadata](#avmetadata11)。 | 4464 4465## AVRecorderProfile<sup>9+</sup> 4466 4467音视频录制的配置文件。 4468 4469**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4470 4471| 名称 | 类型 | 必填 | 说明 | 4472| ---------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 4473| audioBitrate | number | 否 | 音频编码比特率，选择音频录制时必填。<br>支持范围：<br>- AAC编码格式支持比特率范围[32000 - 500000]。<br>- G711-mulaw编码格式支持比特率范围[64000]。<br>- MP3编码格式支持范围[8000, 16000, 32000, 40000, 48000, 56000, 64000, 80000, 96000, 112000, 128000, 160000, 192000, 224000, 256000, 320000]。<br>当使用MP3编码格式时，采样率和比特率的映射关系： <br>- 采样率使用16K以下时，对应比特率范围为[8000 - 64000]。<br>- 采样率使用16K~32K时对应的比特率范围为[8000 - 160000]。<br>- 采样率使用32K以上时对应的比特率范围为[32000 - 320000]。<br>- AMR_NB编码格式支持比特率范围[4750, 5150, 5900, 6700, 7400, 7950, 10200, 12200]。<br>- AMR_WB编码格式支持比特率范围[6600, 8850, 12650, 14250, 15850, 18250, 19850, 23050, 23850]。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4474| audioChannels | number | 否 | 音频采集声道数，选择音频录制时必填。<br>- AAC编码格式支持范围[1 - 8]。<br>- G711-mulaw编码格式支持范围[1]。<br>- MP3编码格式支持范围[1 - 2]。<br>- AMR-NB、AMR-WB编码格式支持范围[1]。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4475| audioCodec | [CodecMimeType](#codecmimetype8) | 否 | 音频编码格式，选择音频录制时必填。当前支持AUDIO_AAC，AUDIO_MP3，AUDIO_G711MU。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4476| audioSampleRate | number | 否 | 音频采样率，选择音频录制时必填。<br>支持范围：<br>- AAC编码支持采样率范围[8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000, 64000, 88200, 96000]。<br>- G711-mulaw编码支持采样率范围[8000]。<br>- MP3编码支持采样率范围[8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000]。<br>- AMR_NB编码支持采样率范围[8000]。<br>- AMR_WB编码支持采样率范围[16000]。<br>可变比特率模式，码率仅作参考。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4477| fileFormat | [ContainerFormatType](#containerformattype8) | 是 | 文件的容器格式，必要参数。当前支持MP4、M4A、MP3、WAV封装格式，不支持在MP4封装格式下使用AUDIO_MP3编码格式。<br>**原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。| 4478| videoBitrate | number | 否 | 视频编码比特率，选择视频录制时必填，支持范围[10000 - 100000000]。 | 4479| videoCodec | [CodecMimeType](#codecmimetype8) | 否 | 视频编码格式，选择视频录制时必填。当前支持VIDEO_AVC。| 4480| videoFrameWidth | number | 否 | 视频帧的宽，选择视频录制时必填，支持范围[176 - 4096]。 | 4481| videoFrameHeight | number | 否 | 视频帧的高，选择视频录制时必填，支持范围[144 - 4096]。 | 4482| videoFrameRate | number | 否 | 视频帧率，选择视频录制时必填，支持范围[1 - 60]。 | 4483| isHdr<sup>11+</sup> | boolean | 否 | HDR编码，选择视频录制时选填，isHdr默认为false，对应编码格式没有要求，isHdr为true时，对应的编码格式必须为video/hevc。| 4484| enableTemporalScale<sup>12+</sup> | boolean | 否 | 视频录制是否支持时域分层编码功能，选择视频录制时选填，enableTemporalScale默认为false。设置为true时，编码输出的码流中部分帧可以支持跳过不编码。| 4485 4486## AudioSourceType<sup>9+</sup> 4487 4488表示视频录制中音频源类型的枚举。 4489 4490**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4491 4492| 名称 | 值 | 说明 | 4493| ------------------------- | ---- | ---------------------- | 4494| AUDIO_SOURCE_TYPE_DEFAULT | 0 | 默认的音频输入源类型。 | 4495| AUDIO_SOURCE_TYPE_MIC | 1 | 表示MIC的音频输入源。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4496| AUDIO_SOURCE_TYPE_VOICE_RECOGNITION<sup>12+</sup> | 2 | 表示语音识别场景的音频源。 | 4497| AUDIO_SOURCE_TYPE_VOICE_COMMUNICATION<sup>12+</sup> | 7 | 表示语音通话场景的音频源。 | 4498| AUDIO_SOURCE_TYPE_VOICE_MESSAGE<sup>12+</sup> | 10 | 表示短语音消息的音频源。 | 4499| AUDIO_SOURCE_TYPE_CAMCORDER<sup>12+</sup> | 13 | 表示相机录像的音频源。 | 4500 4501## VideoSourceType<sup>9+</sup> 4502 4503表示视频录制中视频源类型的枚举。 4504 4505**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4506 4507| 名称 | 值 | 说明 | 4508| ----------------------------- | ---- | ------------------------------- | 4509| VIDEO_SOURCE_TYPE_SURFACE_YUV | 0 | 输入surface中携带的是raw data。 | 4510| VIDEO_SOURCE_TYPE_SURFACE_ES | 1 | 输入surface中携带的是ES data。 | 4511 4512## ContainerFormatType<sup>8+</sup> 4513 4514表示容器格式类型的枚举，缩写为CFT。 4515 4516**系统能力：** SystemCapability.Multimedia.Media.Core 4517 4518| 名称 | 值 | 说明 | 4519| ----------- | ----- | --------------------- | 4520| CFT_MPEG_4 | 'mp4' | 视频的容器格式，MP4。 | 4521| CFT_MPEG_4A | 'm4a' | 音频的容器格式，M4A。<br> **原子化服务API：** 从API version 12 开始，该接口支持在原子化服务中使用。 | 4522| CFT_MP3<sup>12+</sup> | 'mp3' | 音频的容器格式，MP3。 | 4523| CFT_WAV<sup>12+</sup> | 'wav' | 音频的容器格式，WAV。 | 4524 4525## Location 4526 4527视频录制的地理位置。 4528 4529**系统能力：** SystemCapability.Multimedia.Media.Core 4530 4531| 名称 | 类型 | 必填 | 说明 | 4532| --------- | ------ | ---- | ---------------- | 4533| latitude | number | 是 | 地理位置的纬度，取值范围为[-90, 90]。 | 4534| longitude | number | 是 | 地理位置的经度，取值范围为[-180, 180]。 | 4535 4536## EncoderInfo<sup>11+</sup> 4537 4538编码器和规格参数 4539 4540系统能力：SystemCapability.Multimedia.Media.AVRecorder 4541 4542| 名称 | 类型 | 可读 | 可写 | 说明 | 4543| ---------- | -------------------------------- | ---- | ---- | ------------------------------------------------------------ | 4544| mimeType | [CodecMimeType](#codecmimetype8) | 是 | 否 | 编码器MIME类型名称。 | 4545| type | string | 是 | 否 | 编码器类型，audio表示音频编码器，video表示视频编码器。 | 4546| bitRate | [Range](#range11) | 是 | 否 | 比特率，包含该编码器的最大和最小值。 | 4547| frameRate | [Range](#range11) | 是 | 否 | 视频帧率，包含帧率的最大和最小值，仅视频编码器拥有。 | 4548| width | [Range](#range11) | 是 | 否 | 视频帧的宽度，包含宽度的最大和最小值，仅视频编码器拥有。 | 4549| height | [Range](#range11) | 是 | 否 | 视频帧的高度，包含高度的最大和最小值，仅视频编码器拥有。 | 4550| channels | [Range](#range11) | 是 | 否 | 音频采集声道数，包含声道数的最大和最小值，仅音频编码器拥有。 | 4551| sampleRate | Array\<number> | 是 | 否 | 音频采样率，包含所有可以使用的音频采样率值数组，具体数值依赖编码器类型，仅音频编码器拥有。 | 4552 4553## Range<sup>11+</sup> 4554 4555表示一个类型的范围 4556 4557系统能力：SystemCapability.Multimedia.Media.AVRecorder 4558 4559| 名称 | 类型 | 可读 | 可写 | 说明 | 4560| ---- | ------ | ---- | ---- | ------------ | 4561| min | number | 是 | 否 | 范围的最小值。 | 4562| max | number | 是 | 否 | 范围的最大值。 | 4563 4564## FileGenerationMode<sup>12+</sup> 4565 4566表示创建媒体文件模式的枚举。 4567 4568**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 4569 4570| 名称 | 值 | 说明 | 4571| ----------------------------- | ---- | ------------------------------- | 4572| APP_CREATE | 0 | 由应用自行在沙箱创建媒体文件。 | 4573| AUTO_CREATE_CAMERA_SCENE | 1 | 由系统创建媒体文件，当前仅在相机录制场景下生效，会忽略应用设置的url。 | 4574 4575## AVTranscoder<sup>12+</sup> 4576 4577视频转码管理类，用于视频转码。在调用AVTranscoder的方法前，需要先通过createAVTranscoder()构建一个AVTranscoder实例。 4578 4579视频转码demo可参考：[视频转码开发指导](../../media/media/using-avtranscoder-for-transcodering.md) 4580 4581### 属性 4582 4583**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4584 4585| 名称 | 类型 | 只读 | 可选 | 说明 | 4586| ------- | ------------------------------------ | ---- | ---- | ------------------ | 4587| fdSrc<sup>12+</sup> | [AVFileDescriptor](#avfiledescriptor9) | 否 | 否 | 源媒体文件描述，通过该属性设置数据源。<br/> **使用示例**：<br/>假设一个连续存储的媒体文件，地址偏移:0，字节长度:100。其文件描述为 AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVTranscoder 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。 | 4588| fdDst<sup>12+</sup> | number | 否 | 否 | 目标媒体文件描述，通过该属性设置数据输出。在创建AVTranscoder实例后，必须设置fdSrc和fdDst属性。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVTranscoder 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。 | 4589 4590### prepare<sup>12+</sup> 4591 4592prepare(config: AVTranscoderConfig): Promise\<void> 4593 4594异步方式进行视频转码的参数设置。通过Promise获取返回值。 4595 4596**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4597 4598**参数：** 4599 4600| 参数名 | 类型 | 必填 | 说明 | 4601| ------ | -------------------------------------- | ---- | -------------------------- | 4602| config | [AVTranscoderConfig](#avtranscoderconfig12) | 是 | 配置视频转码的相关参数。 | 4603 4604**返回值：** 4605 4606| 类型 | 说明 | 4607| -------------- | ------------------------------------------ | 4608| Promise\<void> | 异步视频转码prepare方法的Promise返回值。 | 4609 4610**错误码：** 4611 4612以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4613 4614| 错误码ID | 错误信息 | 4615| -------- | -------------------------------------- | 4616| 401 | The parameter check failed. Return by promise. | 4617| 5400102 | Operation not allowed. Return by promise. | 4618| 5400105 | Service died. Return by promise. | 4619| 5400106 | Unsupported format. Returned by promise. | 4620 4621**示例：** 4622 4623```ts 4624import { BusinessError } from '@kit.BasicServicesKit'; 4625 4626// 配置参数以实际硬件设备支持的范围为准。 4627let avTranscoderConfig: media.AVTranscoderConfig = { 4628 audioBitrate : 200000, 4629 audioCodec : media.CodecMimeType.AUDIO_AAC, 4630 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 4631 videoBitrate : 3000000, 4632 videoCodec : media.CodecMimeType.VIDEO_AVC, 4633 videoFrameWidth : 1280, 4634 videoFrameHeight : 720, 4635} 4636 4637avTranscoder.prepare(avTranscoderConfig).then(() => { 4638 console.info('prepare success'); 4639}).catch((err: BusinessError) => { 4640 console.error('prepare failed and catch error is ' + err.message); 4641}); 4642``` 4643 4644### start<sup>12+</sup> 4645 4646start(): Promise\<void> 4647 4648异步方式开始视频转码。通过Promise获取返回值。 4649 4650需要[prepare()](#prepare12)事件成功触发后，才能调用start方法。 4651 4652**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4653 4654**返回值：** 4655 4656| 类型 | 说明 | 4657| -------------- | ------------------------------------- | 4658| Promise\<void> | 异步开始视频转码方法的Promise返回值。 | 4659 4660**错误码：** 4661 4662以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4663 4664| 错误码ID | 错误信息 | 4665| -------- | -------------------------------------- | 4666| 5400102 | Operation not allowed. Return by promise. | 4667| 5400103 | IO error. Return by promise. | 4668| 5400105 | Service died. Return by promise. | 4669 4670**示例：** 4671 4672```ts 4673import { BusinessError } from '@kit.BasicServicesKit'; 4674 4675avTranscoder.start().then(() => { 4676 console.info('start AVTranscoder success'); 4677}).catch((err: BusinessError) => { 4678 console.error('start AVTranscoder failed and catch error is ' + err.message); 4679}); 4680``` 4681 4682### pause<sup>12+</sup> 4683 4684pause(): Promise\<void> 4685 4686异步方式暂停视频转码。通过Promise获取返回值。 4687 4688需要[start()](#start12)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume12)接口来恢复转码。 4689 4690**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4691 4692**返回值：** 4693 4694| 类型 | 说明 | 4695| -------------- | ------------------------------------- | 4696| Promise\<void> | 异步暂停视频转码方法的Promise返回值。 | 4697 4698**错误码：** 4699 4700以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4701 4702| 错误码ID | 错误信息 | 4703| -------- | -------------------------------------- | 4704| 5400102 | Operation not allowed. Return by promise. | 4705| 5400103 | IO error. Return by promise. | 4706| 5400105 | Service died. Return by promise. | 4707 4708**示例：** 4709 4710```ts 4711import { BusinessError } from '@kit.BasicServicesKit'; 4712 4713avTranscoder.pause().then(() => { 4714 console.info('pause AVTranscoder success'); 4715}).catch((err: BusinessError) => { 4716 console.error('pause AVTranscoder failed and catch error is ' + err.message); 4717}); 4718``` 4719 4720### resume<sup>12+</sup> 4721 4722resume(): Promise\<void> 4723 4724异步方式恢复视频转码。通过Promise获取返回值。 4725 4726需要在[pause()](#pause12)事件成功触发后，才能调用resume方法。 4727 4728**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4729 4730**返回值：** 4731 4732| 类型 | 说明 | 4733| -------------- | ------------------------------------- | 4734| Promise\<void> | 异步恢复视频转码方法的Promise返回值。 | 4735 4736**错误码：** 4737 4738以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4739 4740| 错误码ID | 错误信息 | 4741| -------- | -------------------------------------- | 4742| 5400102 | Operation not allowed. Return by promise. | 4743| 5400103 | IO error. Return by promise. | 4744| 5400105 | Service died. Return by promise. | 4745 4746**示例：** 4747 4748```ts 4749import { BusinessError } from '@kit.BasicServicesKit'; 4750 4751avTranscoder.resume().then(() => { 4752 console.info('resume AVTranscoder success'); 4753}).catch((err: BusinessError) => { 4754 console.error('resume AVTranscoder failed and catch error is ' + err.message); 4755}); 4756``` 4757 4758### cancel<sup>12+</sup> 4759 4760cancel(): Promise\<void> 4761 4762异步方式取消视频转码。通过Promise获取返回值。 4763 4764需要在[prepare()](#prepare12)、[start()](#start12)、[pause()](#pause12)或[resume()](#resume12)事件成功触发后，才能调用cancel方法。 4765 4766**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4767 4768**返回值：** 4769 4770| 类型 | 说明 | 4771| -------------- | ------------------------------------- | 4772| Promise\<void> | 异步取消视频转码方法的Promise返回值。 | 4773 4774**错误码：** 4775 4776以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4777 4778| 错误码ID | 错误信息 | 4779| -------- | -------------------------------------- | 4780| 5400102 | Operation not allowed. Return by promise. | 4781| 5400103 | IO error. Return by promise. | 4782| 5400105 | Service died. Return by promise. | 4783 4784**示例：** 4785 4786```ts 4787import { BusinessError } from '@kit.BasicServicesKit'; 4788 4789avTranscoder.cancel().then(() => { 4790 console.info('cancel AVTranscoder success'); 4791}).catch((err: BusinessError) => { 4792 console.error('cancel AVTranscoder failed and catch error is ' + err.message); 4793}); 4794``` 4795 4796### release<sup>12+</sup> 4797 4798release(): Promise\<void> 4799 4800异步方式释放视频转码资源。通过Promise获取返回值。 4801 4802释放视频转码资源之后，该AVTranscoder实例不能再进行任何操作。 4803 4804**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4805 4806**返回值：** 4807 4808| 类型 | 说明 | 4809| -------------- | ------------------------------------------- | 4810| Promise\<void> | 异步释放视频转码资源方法的Promise返回值。 | 4811 4812**错误码：** 4813 4814以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4815 4816| 错误码ID | 错误信息 | 4817| -------- | --------------------------------- | 4818| 5400102 | Operation not allowed. Return by promise. | 4819| 5400105 | Service died. Return by promise. | 4820 4821**示例：** 4822 4823```ts 4824import { BusinessError } from '@kit.BasicServicesKit'; 4825 4826avTranscoder.release().then(() => { 4827 console.info('release AVTranscoder success'); 4828}).catch((err: BusinessError) => { 4829 console.error('release AVTranscoder failed and catch error is ' + err.message); 4830}); 4831``` 4832 4833### on('progressUpdate')<sup>12+</sup> 4834 4835on(type: 'progressUpdate', callback: Callback\<number>): void 4836 4837注册转码进度更新事件，并通过注册的回调方法通知用户。用户只能注册一个进度更新事件的回调方法，当用户重复注册时，以最后一次注册的回调接口为准。 4838 4839**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4840 4841**参数：** 4842 4843| 参数名 | 类型 | 必填 | 说明 | 4844| -------- | -------- | ---- | ------------------------------------------------------------ | 4845| type | string | 是 | 进度更新事件回调类型，支持的事件：'progressUpdate'，在转码过程中系统会自动触发此事件。 | 4846| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback) | 是 | 进度更新事件回调方法，progress: number，表示当前转码进度 | 4847 4848**示例：** 4849 4850```ts 4851avTranscoder.on('progressUpdate', (progress: number) => { 4852 console.info('avTranscoder progressUpdate = ' + progress); 4853}); 4854``` 4855 4856### off('progressUpdate')<sup>12+</sup> 4857 4858off(type:'progressUpdate', callback?: Callback\<number>): void 4859 4860取消注册转码进度更新事件。 4861 4862**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4863 4864**参数：** 4865 4866| 参数名 | 类型 | 必填 | 说明 | 4867| ------ | ------ | ---- | ------------------------------------------------------------ | 4868| type | string | 是 | 进度更新事件回调类型，支持的事件：'progressUpdate'，用户操作和系统都会触发此事件。 | 4869| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback) | 否 | 已注册的进度更新事件回调。由于当前回调注册时，仅会保留最后一次注册的回调，建议此参数缺省。 | 4870 4871**示例：** 4872 4873```ts 4874avTranscoder.off('progressUpdate'); 4875``` 4876 4877### on('error')<sup>12+</sup> 4878 4879on(type: 'error', callback: ErrorCallback): void 4880 4881注册AVtranscoder的错误事件，该事件仅用于错误提示。如果AVTranscoder上报error事件，用户需要通过[release()](#release12)退出转码操作。 4882 4883用户只能订阅一个错误事件的回调方法，当用户重复订阅时，以最后一次订阅的回调接口为准。 4884 4885**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4886 4887**参数：** 4888 4889| 参数名 | 类型 | 必填 | 说明 | 4890| -------- | ------------- | ---- | ------------------------------------------------------------ | 4891| type | string | 是 | 转码错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 | 4892| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 转码错误事件回调方法。 | 4893 4894**错误码：** 4895 4896以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 4897 4898| 错误码ID | 错误信息 | 4899| -------- | ------------------------------------------ | 4900| 401 | The parameter check failed. | 4901| 801 | Capability not supported. | 4902| 5400101 | No memory. | 4903| 5400102 | Operation not allowed. | 4904| 5400103 | I/O error. | 4905| 5400104 | Time out. | 4906| 5400105 | Service died. | 4907| 5400106 | Unsupported format. | 4908 4909**示例：** 4910 4911```ts 4912import { BusinessError } from '@kit.BasicServicesKit'; 4913 4914avTranscoder.on('error', (err: BusinessError) => { 4915 console.info('case avTranscoder.on(error) called, errMessage is ' + err.message); 4916}); 4917``` 4918 4919### off('error')<sup>12+</sup> 4920 4921off(type:'error', callback?: ErrorCallback): void 4922 4923取消注册转码错误事件，取消后不再接收到AVTranscoder的错误事件。 4924 4925**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4926 4927**参数：** 4928 4929| 参数名 | 类型 | 必填 | 说明 | 4930| ------ | ------ | ---- | ------------------------------------------------------------ | 4931| type | string | 是 | 转码错误事件回调类型'error'。 <br>- 'error'：转码过程中发生错误，触发该事件。 | 4932| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 错误事件回调方法。 | 4933 4934**示例：** 4935 4936```ts 4937avTranscoder.off('error'); 4938``` 4939 4940### on('complete')<sup>12+</sup> 4941 4942on(type: 'complete', callback: Callback\<void>): void 4943 4944注册转码完成事件，并通过注册的回调方法通知用户。用户只能注册一个进度更新事件的回调方法，当用户重复注册时，以最后一次注册的回调接口为准。 4945 4946当AVTranscoder上报complete事件时，当前转码操作已完成，用户可通过[release()](#release12)退出转码操作。 4947 4948**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4949 4950**参数：** 4951 4952| 参数名 | 类型 | 必填 | 说明 | 4953| -------- | -------- | ---- | ------------------------------------------------------------ | 4954| type | string | 是 | 完成事件回调类型，支持的事件：'complete'，在转码过程中系统会自动触发此事件。 | 4955| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback) | 是 | 完成事件回调方法。 | 4956 4957**示例：** 4958 4959```ts 4960avTranscoder.on('complete', () => { 4961 console.info('avTranscoder complete'); 4962}); 4963``` 4964 4965### off('complete')<sup>12+</sup> 4966 4967off(type:'complete', callback?: Callback\<void>): void 4968 4969取消注册转码完成事件。 4970 4971**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4972 4973**参数：** 4974 4975| 参数名 | 类型 | 必填 | 说明 | 4976| ------ | ------ | ---- | ------------------------------------------------------------ | 4977| type | string | 是 | 转码完成事件回调类型，支持的事件：'complete'，用户操作和系统都会触发此事件。 | 4978| callback | [Callback](../apis-basic-services-kit/js-apis-base.md#callback) | 否 | 完成事件回调方法。 | 4979 4980**示例：** 4981 4982```ts 4983avTranscoder.off('complete'); 4984``` 4985 4986## AVTranscoderConfig<sup>12+</sup> 4987 4988表示视频转码的参数设置。 4989 4990**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder 4991 4992| 名称 | 类型 | 只读 | 可选 | 说明 | 4993| --------------- | ---------------------------------------- |---- | ---- | ------------------------------------------------------------ | 4994| audioBitrate | number | 否 | 是 | 输出音频的码率，单位为比特率（bps）。用户不设置，则默认设置为48Kbps。| 4995| audioCodec | [CodecMimeType](#codecmimetype8) | 否 | 是 | 输出音频的编码格式，当前仅支持AAC。 | 4996| fileFormat | [ContainerFormatType](#containerformattype8) | 否 | 否 | 输出视频文件的封装格式，当前视频文件仅支持MP4。| 4997| videoBitrate | number | 否 | 是 | 输出视频的码率，单位为比特率（bps）。用户不设置，则默认码率按输出视频的分辨率设置，[240p，480P]默认码率值为1Mbps，(480P,720P]默认码率值为2Mbps，(720P,1080P]默认码率值为4Mbps，1080P及以上默认值为8Mbps。| 4998| videoCodec | [CodecMimeType](#codecmimetype8) | 否 | 是 | 输出视频的编码格式，当前仅支持AVC和HEVC。| 4999| videoFrameWidth | number | 否 | 是 | 输出视频帧的宽，单位为像素（px）。用户不设置，则默认设置为源视频帧的宽。| 5000| videoFrameHeight | number | 否 | 是 | 输出视频帧的高，单位为像素（px）。用户不设置，则默认设置为源视频帧的高。| 5001 5002 5003 5004## AVMetadataExtractor<sup>11+</sup> 5005 5006元数据获取类，用于从媒体资源中获取元数据。在调用AVMetadataExtractor的方法前，需要先通过[createAVMetadataExtractor()](#mediacreateavmetadataextractor11)构建一个AVMetadataExtractor实例。 5007 5008获取音频或视频元数据的demo可参考：[获取音视频元数据开发指导](../../media/media/avmetadataextractor.md)。 5009 5010### 属性 5011 5012**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5013 5014| 名称 | 类型 | 可读 | 可写 | 说明 | 5015| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 5016| 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。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致音视频元数据获取异常。 | 5017| dataSrc<sup>11+</sup> | [AVDataSrcDescriptor](#avdatasrcdescriptor10) | 是 | 是 | 流式媒体资源描述，通过该属性设置数据源。在获取元数据之前，必须设置数据源属性，只能设置fdSrc和dataSrc的其中一个。<br/> 当应用从远端获取音视频媒体文件，在应用未下载完整音视频资源时，可以设置dataSrc提前获取该资源的元数据。| 5018 5019### fetchMetadata<sup>11+</sup> 5020 5021fetchMetadata(callback: AsyncCallback\<AVMetadata>): void 5022 5023异步方式获取媒体元数据。通过注册回调函数获取返回值。 5024 5025**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5026 5027**参数：** 5028 5029| 参数名 | 类型 | 必填 | 说明 | 5030| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5031| callback | AsyncCallback\<[AVMetadata](#avmetadata11)> | 是 | 回调函数。异步返回音视频元数据对象（AVMetadata）。| 5032 5033**错误码：** 5034 5035以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5036 5037| 错误码ID | 错误信息 | 5038| -------- | ------------------------------------------ | 5039| 5400102 | Operation not allowed. Returned by callback. | 5040| 5400106 | Unsupported format. Returned by callback. | 5041 5042**示例：** 5043 5044```ts 5045import { BusinessError } from '@kit.BasicServicesKit'; 5046 5047avMetadataExtractor.fetchMetadata((error: BusinessError, metadata: media.AVMetadata) => { 5048 if (error) { 5049 console.error(`Failed to fetch Metadata, err = ${JSON.stringify(error)}`); 5050 return; 5051 } 5052 console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`); 5053}); 5054``` 5055 5056### fetchMetadata<sup>11+</sup> 5057 5058fetchMetadata(): Promise\<AVMetadata> 5059 5060异步方式获取媒体元数据。通过Promise获取返回值。 5061 5062**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5063 5064**返回值：** 5065 5066| 类型 | 说明 | 5067| -------------- | ---------------------------------------- | 5068| Promise\<[AVMetadata](#avmetadata11)> | Promise对象。异步返回音视频元数据对象（AVMetadata）。 | 5069 5070**错误码：** 5071 5072以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5073 5074| 错误码ID | 错误信息 | 5075| -------- | ----------------------------------------- | 5076| 5400102 | Operation not allowed. Returned by promise. | 5077| 5400106 | Unsupported format. Returned by promise. | 5078 5079**示例：** 5080 5081```ts 5082import { BusinessError } from '@kit.BasicServicesKit'; 5083 5084avMetadataExtractor.fetchMetadata().then((metadata: media.AVMetadata) => { 5085 console.info(`Succeeded in fetching Metadata, genre: ${metadata.genre}`) 5086}).catch((error: BusinessError) => { 5087 console.error(`Failed to fetch Metadata, error message:${error.message}`); 5088}); 5089``` 5090 5091### fetchAlbumCover<sup>11+</sup> 5092 5093fetchAlbumCover(callback: AsyncCallback\<image.PixelMap>): void 5094 5095异步方式获取音频专辑封面。通过注册回调函数获取返回值。 5096 5097**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5098 5099**参数：** 5100 5101| 参数名 | 类型 | 必填 | 说明 | 5102| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5103| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | 回调函数。异步返回专辑封面。 | 5104 5105**错误码：** 5106 5107以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5108 5109| 错误码ID | 错误信息 | 5110| -------- | ------------------------------------------ | 5111| 5400102 | Operation not allowed. Return by callback. | 5112| 5400106 | Unsupported format. Returned by callback. | 5113 5114**示例：** 5115 5116```ts 5117import { BusinessError } from '@kit.BasicServicesKit'; 5118import { image } from '@kit.ImageKit'; 5119 5120let pixel_map : image.PixelMap | undefined = undefined; 5121 5122avMetadataExtractor.fetchAlbumCover((error: BusinessError, pixelMap: image.PixelMap) => { 5123 if (error) { 5124 console.error(`Failed to fetch AlbumCover, error = ${JSON.stringify(error)}`); 5125 return; 5126 } 5127 pixel_map = pixelMap; 5128}); 5129``` 5130 5131### fetchAlbumCover<sup>11+</sup> 5132 5133fetchAlbumCover(): Promise\<image.PixelMap> 5134 5135异步方式获取专辑封面。通过Promise获取返回值。 5136 5137**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5138 5139**返回值：** 5140 5141| 类型 | 说明 | 5142| -------------- | ---------------------------------------- | 5143| Promise\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise对象。异步返回专辑封面。 | 5144 5145**错误码：** 5146 5147以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5148 5149| 错误码ID | 错误信息 | 5150| -------- | ----------------------------------------- | 5151| 5400102 | Operation not allowed. Returned by promise. | 5152| 5400106 | Unsupported format. Returned by promise. | 5153 5154**示例：** 5155 5156```ts 5157import { BusinessError } from '@kit.BasicServicesKit'; 5158import { image } from '@kit.ImageKit'; 5159 5160let pixel_map : image.PixelMap | undefined = undefined; 5161 5162avMetadataExtractor.fetchAlbumCover().then((pixelMap: image.PixelMap) => { 5163 pixel_map = pixelMap; 5164}).catch((error: BusinessError) => { 5165 console.error(`Failed to fetch AlbumCover, error message:${error.message}`); 5166}); 5167``` 5168 5169### release<sup>11+</sup> 5170 5171release(callback: AsyncCallback\<void>): void 5172 5173异步方式释放资源。通过注册回调函数获取返回值。 5174 5175**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5176 5177**参数：** 5178 5179| 参数名 | 类型 | 必填 | 说明 | 5180| -------- | -------------------------------------------- | ---- | ----------------------------------- | 5181| callback | AsyncCallback\<void> | 是 |回调函数。当释放资源成功，err为undefined，否则为错误对象。 | 5182 5183**错误码：** 5184 5185以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5186 5187| 错误码ID | 错误信息 | 5188| -------- | ------------------------------------------ | 5189| 5400102 | Operation not allowed. Returned by callback. | 5190 5191**示例：** 5192 5193```ts 5194import { BusinessError } from '@kit.BasicServicesKit'; 5195 5196avMetadataExtractor.release((error: BusinessError) => { 5197 if (error) { 5198 console.error(`Failed to release, err = ${JSON.stringify(error)}`); 5199 return; 5200 } 5201 console.info(`Succeeded in releasing.`); 5202}); 5203``` 5204 5205### release<sup>11+</sup> 5206 5207release(): Promise\<void> 5208 5209异步方式释放资源。通过Promise获取返回值。 5210 5211**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5212 5213**返回值：** 5214 5215| 类型 | 说明 | 5216| -------------- | ---------------------------------------- | 5217| Promise\<void> | 异步方式释放资源release方法的Promise返回值。 | 5218 5219**错误码：** 5220 5221以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 5222 5223| 错误码ID | 错误信息 | 5224| -------- | ----------------------------------------- | 5225| 5400102 | Operation not allowed. Returned by promise. | 5226 5227**示例：** 5228 5229```ts 5230import { BusinessError } from '@kit.BasicServicesKit'; 5231 5232avMetadataExtractor.release().then(() => { 5233 console.info(`Succeeded in releasing.`); 5234}).catch((error: BusinessError) => { 5235 console.error(`Failed to release, error message:${error.message}`); 5236}); 5237``` 5238 5239## AVMetadata<sup>11+</sup> 5240 5241音视频元数据，包含各个元数据字段。在[AVRecorderConfig](#avrecorderconfig9)中使用时未声明为当前版本只读的参数可以作为使用[AVRecorder](#avrecorder9)录制时的入参。 5242 5243**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 5244 5245| 名称 | 类型 | 必填 | 说明 | 5246| ------ | ------ | ---- | ------------------------------------------------------------ | 5247| album | string | 否 | 专辑的标题。当前版本为只读参数。 | 5248| albumArtist | string | 否 | 专辑的艺术家。当前版本为只读参数。 | 5249| artist | string | 否 | 媒体资源的艺术家。当前版本为只读参数。 | 5250| author | string | 否 | 媒体资源的作者。当前版本为只读参数。 | 5251| dateTime | string | 否 | 媒体资源的创建时间。当前版本为只读参数。 | 5252| dateTimeFormat | string | 否 | 媒体资源的创建时间，按YYYY-MM-DD HH:mm:ss格式输出。当前版本为只读参数。 | 5253| composer | string | 否 | 媒体资源的作曲家。当前版本为只读参数。 | 5254| duration | string | 否 | 媒体资源的时长。当前版本为只读参数。 | 5255| genre | string | 否 | 媒体资源的类型或体裁。| 5256| hasAudio | string | 否 | 媒体资源是否包含音频。当前版本为只读参数。 | 5257| hasVideo | string | 否 | 媒体资源是否包含视频。当前版本为只读参数。 | 5258| mimeType | string | 否 | 媒体资源的mime类型。当前版本为只读参数。 | 5259| trackCount | string | 否 | 媒体资源的轨道数量。当前版本为只读参数。 | 5260| sampleRate | string | 否 | 音频的采样率，单位为赫兹（Hz）。当前版本为只读参数。 | 5261| title | string | 否 | 媒体资源的标题。当前版本为只读参数。当前版本为只读参数。 | 5262| videoHeight | string | 否 | 视频的高度，单位为像素。当前版本为只读参数。 | 5263| videoWidth | string | 否 | 视频的宽度，单位为像素。当前版本为只读参数。 | 5264| videoOrientation | string | 否 | 视频的旋转方向，单位为度（°）。| 5265| hdrType<sup>12+</sup> | [HdrType](#hdrtype12) | 否 | 媒体资源的HDR类型。当前版本为只读参数。 | 5266| location<sup>12+</sup> | [Location](#location) | 否 | 视频的地理位置信息。 | 5267| customInfo<sup>12+</sup> | Record<string, string> | 否 | 从moov.meta.list 获取的自定义参数键值映射。| 5268 5269## HdrType<sup>12+</sup> 5270 5271表示视频HDR类型的枚举。 5272 5273**系统能力：** SystemCapability.Multimedia.Media.Core 5274 5275| 名称 | 值 | 说明 | 5276| ------------------------- | ---- | ---------------------- | 5277| AV_HDR_TYPE_NONE | 0 | 表示无HDR类型。 | 5278| AV_HDR_TYPE_VIVID | 1 | 表示为HDR VIVID类型。 | 5279 5280## media.createAudioPlayer<sup>(deprecated)</sup> 5281 5282createAudioPlayer(): AudioPlayer 5283 5284同步方式创建音频播放实例。 5285 5286> **说明：** 5287> 从API version 6开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9)替代。 5288 5289**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5290 5291**返回值：** 5292 5293| 类型 | 说明 | 5294| --------------------------- | ------------------------------------------------------------ | 5295| [AudioPlayer](#audioplayerdeprecated) | 返回AudioPlayer类实例，失败时返回null。可用于音频播放、暂停、停止等操作。 | 5296 5297**示例：** 5298 5299```ts 5300let audioPlayer: media.AudioPlayer = media.createAudioPlayer(); 5301``` 5302 5303## media.createVideoPlayer<sup>(deprecated)</sup> 5304 5305createVideoPlayer(callback: AsyncCallback\<VideoPlayer>): void 5306 5307异步方式创建视频播放实例，通过注册回调函数获取返回值。 5308 5309> **说明：** 5310> 从API version 8开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9)替代。 5311 5312**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5313 5314**参数：** 5315 5316| 参数名 | 类型 | 必填 | 说明 | 5317| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 5318| callback | AsyncCallback<[VideoPlayer](#videoplayerdeprecated)> | 是 | 回调函数。创建VideoPlayer实例成功时，err为undefined，data为获取到的VideoPlayer实例，否则为错误对象。 | 5319 5320**示例：** 5321 5322```ts 5323import { BusinessError } from '@kit.BasicServicesKit'; 5324 5325let videoPlayer: media.VideoPlayer; 5326media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 5327 if (video != null) { 5328 videoPlayer = video; 5329 console.info('Succeeded in creating VideoPlayer'); 5330 } else { 5331 console.error(`Failed to create VideoPlayer, error:${error}`); 5332 } 5333}); 5334``` 5335 5336## media.createVideoPlayer<sup>(deprecated)</sup> 5337 5338createVideoPlayer(): Promise\<VideoPlayer> 5339 5340异步方式创建视频播放实例，通过Promise获取返回值。 5341 5342> **说明：** 5343> 从API version 8开始支持，从API version 9开始废弃，建议使用[createAVPlayer](#mediacreateavplayer9-1)替代。 5344 5345**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5346 5347**返回值：** 5348 5349| 类型 | 说明 | 5350| ------------------------------------ | ------------------------------------------------------------ | 5351| Promise<[VideoPlayer](#videoplayerdeprecated)> | Promise对象。异步返回VideoPlayer实例，失败时返回null。可用于管理和播放视频媒体。 | 5352 5353**示例：** 5354 5355```ts 5356import { BusinessError } from '@kit.BasicServicesKit'; 5357 5358let videoPlayer: media.VideoPlayer; 5359media.createVideoPlayer().then((video: media.VideoPlayer) => { 5360 if (video != null) { 5361 videoPlayer = video; 5362 console.info('Succeeded in creating VideoPlayer'); 5363 } else { 5364 console.error('Failed to create VideoPlayer'); 5365 } 5366}).catch((error: BusinessError) => { 5367 console.error(`Failed to create VideoPlayer, error:${error}`); 5368}); 5369``` 5370 5371## media.createAudioRecorder<sup>(deprecated)</sup> 5372 5373createAudioRecorder(): AudioRecorder 5374 5375创建音频录制的实例来控制音频的录制。 5376一台设备只允许创建一个录制实例。 5377 5378> **说明：** 5379> 从API version 6开始支持，从API version 9开始废弃，建议使用[createAVRecorder](#mediacreateavrecorder9)替代。 5380 5381**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 5382 5383**返回值:** 5384 5385| 类型 | 说明 | 5386| ------------------------------- | ------------------------------------------------------------ | 5387| [AudioRecorder](#audiorecorderdeprecated) | 返回AudioRecorder类实例，失败时返回null。可用于录制音频媒体。 | 5388 5389**示例：** 5390 5391```ts 5392let audioRecorder: media.AudioRecorder = media.createAudioRecorder(); 5393``` 5394 5395## MediaErrorCode<sup>(deprecated)</sup> 5396 5397媒体服务错误类型枚举。 5398 5399> **说明：** 5400> 从API version 8开始支持，从API version 11开始废弃，建议使用[媒体错误码](#averrorcode9)替代。 5401 5402**系统能力：** SystemCapability.Multimedia.Media.Core 5403 5404| 名称 | 值 | 说明 | 5405| -------------------------- | ---- | -------------------------------------- | 5406| MSERR_OK | 0 | 表示操作成功。 | 5407| MSERR_NO_MEMORY | 1 | 表示申请内存失败，系统可能无可用内存。 | 5408| MSERR_OPERATION_NOT_PERMIT | 2 | 表示无权限执行此操作。 | 5409| MSERR_INVALID_VAL | 3 | 表示传入入参无效。 | 5410| MSERR_IO | 4 | 表示发生IO错误。 | 5411| MSERR_TIMEOUT | 5 | 表示操作超时。 | 5412| MSERR_UNKNOWN | 6 | 表示未知错误。 | 5413| MSERR_SERVICE_DIED | 7 | 表示服务端失效。 | 5414| MSERR_INVALID_STATE | 8 | 表示在当前状态下，不允许执行此操作。 | 5415| MSERR_UNSUPPORTED | 9 | 表示在当前版本下，不支持此操作。 | 5416 5417## AudioPlayer<sup>(deprecated)</sup> 5418 5419> **说明：** 5420> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer](#avplayer9)替代。 5421 5422音频播放管理类，用于管理和播放音频媒体。在调用AudioPlayer的方法前，需要先通过[createAudioPlayer()](#mediacreateaudioplayerdeprecated)构建一个AudioPlayer实例。 5423 5424### 属性<sup>(deprecated)</sup> 5425 5426**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5427 5428| 名称 | 类型 | 只读 | 可选 | 说明 | 5429| ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 5430| 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。 | 5431| 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/> | 5432| loop | boolean | 否 | 否 | 音频循环播放属性，设置为'true'表示循环播放。 | 5433| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9) | 是 | 是 | 音频焦点模型。 | 5434| currentTime | number | 是 | 否 | 音频的当前播放位置，单位为毫秒（ms）。 | 5435| duration | number | 是 | 否 | 音频时长，单位为毫秒（ms）。 | 5436| state | [AudioState](#audiostatedeprecated) | 是 | 否 | 可以查询音频播放的状态，该状态不可作为调用play/pause/stop等状态切换的触发条件。 | 5437 5438### play<sup>(deprecated)</sup> 5439 5440play(): void 5441 5442开始播放音频资源，需在'dataLoad'事件成功触发后，才能调用。 5443 5444> **说明：** 5445> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9)替代。 5446 5447**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5448 5449**示例：** 5450 5451```ts 5452audioPlayer.on('play', () => { //设置'play'事件回调。 5453 console.info('audio play called'); 5454}); 5455audioPlayer.play(); 5456``` 5457 5458### pause<sup>(deprecated)</sup> 5459 5460pause(): void 5461 5462暂停播放音频资源。 5463 5464> **说明：** 5465> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9)替代。 5466 5467**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5468 5469**示例：** 5470 5471```ts 5472audioPlayer.on('pause', () => { //设置'pause'事件回调。 5473 console.info('audio pause called'); 5474}); 5475audioPlayer.pause(); 5476``` 5477 5478### stop<sup>(deprecated)</sup> 5479 5480stop(): void 5481 5482停止播放音频资源。 5483 5484> **说明：** 5485> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9)替代。 5486 5487**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5488 5489**示例：** 5490 5491```ts 5492audioPlayer.on('stop', () => { //设置'stop'事件回调。 5493 console.info('audio stop called'); 5494}); 5495audioPlayer.stop(); 5496``` 5497 5498### reset<sup>(deprecated)</sup> 5499 5500reset(): void 5501 5502重置播放音频资源。 5503 5504> **说明：** 5505> 从API version 7开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9)替代。 5506 5507**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5508 5509**示例：** 5510 5511```ts 5512audioPlayer.on('reset', () => { //设置'reset'事件回调。 5513 console.info('audio reset called'); 5514}); 5515audioPlayer.reset(); 5516``` 5517 5518### seek<sup>(deprecated)</sup> 5519 5520seek(timeMs: number): void 5521 5522跳转到指定播放位置。 5523 5524> **说明：** 5525> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 5526 5527**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5528 5529**参数：** 5530 5531| 参数名 | 类型 | 必填 | 说明 | 5532| ------ | ------ | ---- | ----------------------------------------------------------- | 5533| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围[0, duration]。 | 5534 5535**示例：** 5536 5537```ts 5538audioPlayer.on('timeUpdate', (seekDoneTime: number) => { //设置'timeUpdate'事件回调。 5539 if (seekDoneTime == null) { 5540 console.error('Failed to seek'); 5541 return; 5542 } 5543 console.info('Succeeded in seek. seekDoneTime: ' + seekDoneTime); 5544}); 5545audioPlayer.seek(30000); //seek到30000ms的位置。 5546``` 5547 5548### setVolume<sup>(deprecated)</sup> 5549 5550setVolume(vol: number): void 5551 5552设置音量。 5553 5554> **说明：** 5555> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 5556 5557**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5558 5559**参数：** 5560 5561| 参数名 | 类型 | 必填 | 说明 | 5562| ------ | ------ | ---- | ------------------------------------------------------------ | 5563| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 5564 5565**示例：** 5566 5567```ts 5568audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调。 5569 console.info('audio volumeChange called'); 5570}); 5571audioPlayer.setVolume(1); //设置音量到100%。 5572``` 5573 5574### release<sup>(deprecated)</sup> 5575 5576release(): void 5577 5578释放音频资源。 5579 5580> **说明：** 5581> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9)替代。 5582 5583**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5584 5585**示例：** 5586 5587```ts 5588audioPlayer.release(); 5589audioPlayer = undefined; 5590``` 5591 5592### getTrackDescription<sup>(deprecated)</sup> 5593 5594getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 5595 5596获取音频轨道信息。需在'dataLoad'事件成功触发后，才能调用。通过回调函数获取返回值。 5597 5598> **说明：** 5599> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9)替代。 5600 5601**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5602 5603**参数：** 5604 5605| 参数名 | 类型 | 必填 | 说明 | 5606| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 5607| callback | AsyncCallback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 回调函数。获取音频轨道信息成功时，err为undefined，data为获取到的MediaDescription数组，否则为错误对象。 | 5608 5609**示例：** 5610 5611```ts 5612import { BusinessError } from '@kit.BasicServicesKit'; 5613 5614audioPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 5615 if (arrList != null) { 5616 console.info('Succeeded in getting TrackDescription'); 5617 } else { 5618 console.error(`Failed to get TrackDescription, error:${error}`); 5619 } 5620}); 5621``` 5622 5623### getTrackDescription<sup>(deprecated)</sup> 5624 5625getTrackDescription(): Promise\<Array\<MediaDescription>> 5626 5627获取音频轨道信息。需在'dataLoad'事件成功触发后，才能调用。通过Promise获取返回值。 5628 5629> **说明：** 5630> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9-1)替代。 5631 5632**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5633 5634**返回值：** 5635 5636| 类型 | 说明 | 5637| ------------------------------------------------------ | ----------------------------------------------- | 5638| Promise<Array<[MediaDescription](#mediadescription8)>> | 音频轨道信息MediaDescription数组Promise返回值。 | 5639 5640**示例：** 5641 5642```ts 5643import { BusinessError } from '@kit.BasicServicesKit'; 5644 5645audioPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 5646 console.info('Succeeded in getting TrackDescription'); 5647}).catch((error: BusinessError) => { 5648 console.error(`Failed to get TrackDescription, error:${error}`); 5649}); 5650``` 5651 5652### on('bufferingUpdate')<sup>(deprecated)</sup> 5653 5654on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void 5655 5656开始订阅音频缓存更新事件。仅网络播放支持该订阅事件。 5657 5658> **说明：** 5659> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('bufferingUpdate')](#onbufferingupdate9)替代。 5660 5661**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5662 5663**参数：** 5664 5665| 参数名 | 类型 | 必填 | 说明 | 5666| -------- | -------- | ---- | ------------------------------------------------------------ | 5667| type | string | 是 | 音频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 5668| callback | function | 是 | 音频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)value值固定为0。 | 5669 5670**示例：** 5671 5672```ts 5673audioPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 5674 console.info('audio bufferingInfo type: ' + infoType); 5675 console.info('audio bufferingInfo value: ' + value); 5676}); 5677``` 5678 5679### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')<sup>(deprecated)</sup> 5680 5681on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void): void 5682 5683开始订阅音频播放事件。 5684 5685> **说明：** 5686> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('stateChange')](#onstatechange9)替代。 5687 5688**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5689 5690**参数：** 5691 5692| 参数名 | 类型 | 必填 | 说明 | 5693| -------- | ---------- | ---- | ------------------------------------------------------------ | 5694| 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)调用，播放音量改变后触发该事件。 | 5695| callback | () => void | 是 | 播放事件回调方法。 | 5696 5697**示例：** 5698 5699```ts 5700import { fileIo as fs } from '@kit.CoreFileKit'; 5701import { BusinessError } from '@kit.BasicServicesKit'; 5702 5703let audioPlayer: media.AudioPlayer = media.createAudioPlayer(); //创建一个音频播放实例。 5704audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调，src属性设置成功后，触发此回调。 5705 console.info('audio set source called'); 5706 audioPlayer.play(); //开始播放，并触发'play'事件回调。 5707}); 5708audioPlayer.on('play', () => { //设置'play'事件回调。 5709 console.info('audio play called'); 5710 audioPlayer.seek(30000); //调用seek方法，并触发'timeUpdate'事件回调。 5711}); 5712audioPlayer.on('pause', () => { //设置'pause'事件回调。 5713 console.info('audio pause called'); 5714 audioPlayer.stop(); //停止播放，并触发'stop'事件回调。 5715}); 5716audioPlayer.on('reset', () => { //设置'reset'事件回调。 5717 console.info('audio reset called'); 5718 audioPlayer.release(); //释放播放实例资源。 5719 audioPlayer = undefined; 5720}); 5721audioPlayer.on('timeUpdate', (seekDoneTime: number) => { //设置'timeUpdate'事件回调。 5722 if (seekDoneTime == null) { 5723 console.error('Failed to seek'); 5724 return; 5725 } 5726 console.info('Succeeded in seek, and seek time is ' + seekDoneTime); 5727 audioPlayer.setVolume(0.5); //设置音量为50%，并触发'volumeChange'事件回调。 5728}); 5729audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调。 5730 console.info('audio volumeChange called'); 5731 audioPlayer.pause(); //暂停播放，并触发'pause'事件回调。 5732}); 5733audioPlayer.on('finish', () => { //设置'finish'事件回调。 5734 console.info('audio play finish'); 5735 audioPlayer.stop(); //停止播放，并触发'stop'事件回调。 5736}); 5737audioPlayer.on('error', (error: BusinessError) => { //设置'error'事件回调。 5738 console.error(`audio error called, error: ${error}`); 5739}); 5740 5741// 用户选择音频设置fd(本地播放)。 5742let fdPath = 'fd://'; 5743// path路径的码流可通过"hdc file send D:\xxx\01.mp3 /data/accounts/account_0/appdata" 命令，将其推送到设备上。 5744let path = '/data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3'; 5745fs.open(path).then((file) => { 5746 fdPath = fdPath + '' + file.fd; 5747 console.info('Succeeded in opening fd, fd is' + fdPath); 5748 audioPlayer.src = fdPath; //设置src属性，并触发'dataLoad'事件回调。 5749}, (err: BusinessError) => { 5750 console.error('Failed to open fd, err is' + err); 5751}).catch((err: BusinessError) => { 5752 console.error('Failed to open fd, err is' + err); 5753}); 5754``` 5755 5756### on('timeUpdate')<sup>(deprecated)</sup> 5757 5758on(type: 'timeUpdate', callback: Callback\<number>): void 5759 5760开始订阅音频播放时间更新事件。处于播放状态时，每隔1s上报一次该事件。 5761 5762> **说明：** 5763> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('timeUpdate')](#ontimeupdate9)替代。 5764 5765**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5766 5767**参数：** 5768 5769| 参数名 | 类型 | 必填 | 说明 | 5770| -------- | ----------------- | ---- | ------------------------------------------------------------ | 5771| type | string | 是 | 播放事件回调类型，支持的事件包括：'timeUpdate'。<br>- 'timeUpdate'：音频播放时间戳更新，开始播放后自动触发该事件。 | 5772| callback | Callback\<number> | 是 | 播放事件回调方法。回调方法入参为更新后的时间戳。 | 5773 5774**示例：** 5775 5776```ts 5777audioPlayer.on('timeUpdate', (newTime: number) => { //设置'timeUpdate'事件回调。 5778 if (newTime == null) { 5779 console.error('Failed to do timeUpadate'); 5780 return; 5781 } 5782 console.info('Succeeded in doing timeUpadate. seekDoneTime: ' + newTime); 5783}); 5784audioPlayer.play(); //开始播放后，自动触发时间戳更新事件。 5785``` 5786 5787### on('audioInterrupt')<sup>(deprecated)</sup> 5788 5789on(type: 'audioInterrupt', callback: (info: audio.InterruptEvent) => void): void 5790 5791监听音频焦点变化事件，参考[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)。 5792 5793> **说明：** 5794> 从API version 9开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('audioInterrupt')](#onaudiointerrupt9)替代。 5795 5796**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5797 5798**参数：** 5799 5800| 参数名 | 类型 | 必填 | 说明 | 5801| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 5802| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 5803| callback | function | 是 | 音频焦点变化事件回调方法。 | 5804 5805**示例：** 5806 5807```ts 5808import { audio } from '@kit.AudioKit'; 5809 5810audioPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 5811 console.info('audioInterrupt called,and InterruptEvent info is:' + info) 5812}) 5813``` 5814 5815### on('error')<sup>(deprecated)</sup> 5816 5817on(type: 'error', callback: ErrorCallback): void 5818 5819开始订阅音频播放错误事件，当上报error错误事件后，用户需处理error事件，退出播放操作。 5820 5821> **说明：** 5822> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('error')](#onerror9)替代。 5823 5824**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5825 5826**参数：** 5827 5828| 参数名 | 类型 | 必填 | 说明 | 5829| -------- | ------------- | ---- | ------------------------------------------------------------ | 5830| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：音频播放中发生错误，触发该事件。 | 5831| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 播放错误事件回调方法。 | 5832 5833**示例：** 5834 5835```ts 5836import { BusinessError } from '@kit.BasicServicesKit'; 5837 5838audioPlayer.on('error', (error: BusinessError) => { //设置'error'事件回调。 5839 console.error(`audio error called, error: ${error}`); 5840}); 5841audioPlayer.setVolume(3); //设置volume为无效值，触发'error'事件。 5842``` 5843 5844## AudioState<sup>(deprecated)</sup> 5845 5846type AudioState = 'idle' | 'playing' | 'paused' | 'stopped' | 'error' 5847 5848音频播放的状态机。可通过state属性获取当前状态。 5849 5850> **说明：** 5851> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVPlayerState](#avplayerstate9)替代。 5852 5853**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 5854 5855| 类型 | 说明 | 5856| ------- | ---------------------------------------------- | 5857| 'idle' | 音频播放空闲，dataload/reset成功后处于此状态。 | 5858| 'playing' | 音频正在播放，play成功后处于此状态。 | 5859| 'paused' | 音频暂停播放，pause成功后处于此状态。 | 5860| 'stopped' | 音频播放停止，stop/播放结束后处于此状态。 | 5861| 'error' | 错误状态。 | 5862 5863## VideoPlayer<sup>(deprecated)</sup> 5864 5865> **说明：** 5866> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer](#avplayer9)替代。 5867 5868视频播放管理类，用于管理和播放视频媒体。在调用VideoPlayer的方法前，需要先通过[createVideoPlayer()](#mediacreatevideoplayerdeprecated)构建一个VideoPlayer实例。 5869 5870### 属性 5871 5872**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5873 5874| 名称 | 类型 | 只读 | 可选 | 说明 | 5875| ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 5876| 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。 | 5877| 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/> | 5878| loop<sup>8+</sup> | boolean | 否 | 否 | 视频循环播放属性，设置为'true'表示循环播放。 | 5879| videoScaleType<sup>9+</sup> | [VideoScaleType](#videoscaletype9) | 否 | 是 | 视频缩放模式。默认值为VIDEO_SCALE_TYPE_FIT。 | 5880| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](../apis-audio-kit/js-apis-audio.md#interruptmode9) | 否 | 是 | 音频焦点模型。 | 5881| currentTime<sup>8+</sup> | number | 是 | 否 | 视频的当前播放位置，单位为毫秒（ms）。 | 5882| duration<sup>8+</sup> | number | 是 | 否 | 视频时长，单位为毫秒（ms），返回-1表示直播模式。 | 5883| state<sup>8+</sup> | [VideoPlayState](#videoplaystatedeprecated) | 是 | 否 | 视频播放的状态。 | 5884| width<sup>8+</sup> | number | 是 | 否 | 视频宽，单位为像素（px）。 | 5885| height<sup>8+</sup> | number | 是 | 否 | 视频高，单位为像素（px）。 | 5886 5887### setDisplaySurface<sup>(deprecated)</sup> 5888 5889setDisplaySurface(surfaceId: string, callback: AsyncCallback\<void>): void 5890 5891设置SurfaceId。通过回调函数获取返回值。 5892 5893*注意：SetDisplaySurface需要在设置url和Prepare之间，无音频的视频流必须设置Surface否则Prepare失败。 5894 5895> **说明：** 5896> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.surfaceId](#属性)替代。 5897 5898**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5899 5900**参数：** 5901 5902| 参数名 | 类型 | 必填 | 说明 | 5903| --------- | -------------------- | ---- | ------------------------- | 5904| surfaceId | string | 是 | SurfaceId. | 5905| callback | AsyncCallback\<void> | 是 | 回调函数。当设置SurfaceId成功，err为undefined，否则为错误对象。 | 5906 5907**示例：** 5908 5909```ts 5910import { BusinessError } from '@kit.BasicServicesKit'; 5911 5912let surfaceId: string = ''; 5913videoPlayer.setDisplaySurface(surfaceId, (err: BusinessError) => { 5914 if (err) { 5915 console.error('Failed to set DisplaySurface!'); 5916 } else { 5917 console.info('Succeeded in setting DisplaySurface!'); 5918 } 5919}); 5920``` 5921 5922### setDisplaySurface<sup>(deprecated)</sup> 5923 5924setDisplaySurface(surfaceId: string): Promise\<void> 5925 5926设置SurfaceId。通过Promise获取返回值。 5927 5928*注意：SetDisplaySurface需要在设置url和Prepare之间，无音频的视频流必须设置Surface否则Prepare失败。 5929 5930> **说明：** 5931> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.surfaceId](#属性)替代。 5932 5933**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5934 5935**参数：** 5936 5937| 参数名 | 类型 | 必填 | 说明 | 5938| --------- | ------ | ---- | --------- | 5939| surfaceId | string | 是 | SurfaceId. | 5940 5941**返回值：** 5942 5943| 类型 | 说明 | 5944| -------------- | ------------------------------ | 5945| Promise\<void> | 设置SurfaceId的Promise返回值。 | 5946 5947**示例：** 5948 5949```ts 5950import { BusinessError } from '@kit.BasicServicesKit'; 5951 5952let surfaceId: string = ''; 5953videoPlayer.setDisplaySurface(surfaceId).then(() => { 5954 console.info('Succeeded in setting DisplaySurface'); 5955}).catch((error: BusinessError) => { 5956 console.error(`video catchCallback, error:${error}`); 5957}); 5958``` 5959 5960### prepare<sup>(deprecated)</sup> 5961 5962prepare(callback: AsyncCallback\<void>): void 5963 5964准备播放视频。通过回调函数获取返回值。 5965 5966> **说明：** 5967> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.prepare](#prepare9)替代。 5968 5969**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 5970 5971**参数：** 5972 5973| 参数名 | 类型 | 必填 | 说明 | 5974| -------- | -------------------- | ---- | ------------------------ | 5975| callback | AsyncCallback\<void> | 是 | 回调函数。当准备播放视频成功，err为undefined，否则为错误对象。| 5976 5977**示例：** 5978 5979```ts 5980import { BusinessError } from '@kit.BasicServicesKit'; 5981 5982videoPlayer.prepare((err: BusinessError) => { 5983 if (err) { 5984 console.error('Failed to prepare!'); 5985 } else { 5986 console.info('Succeeded in preparing!'); 5987 } 5988}); 5989``` 5990 5991### prepare<sup>(deprecated)</sup> 5992 5993prepare(): Promise\<void> 5994 5995准备播放视频。通过Promise获取返回值。 5996 5997> **说明：** 5998> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.prepare](#prepare9-1)替代。 5999 6000**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6001 6002**返回值：** 6003 6004| 类型 | 说明 | 6005| -------------- | ----------------------------- | 6006| Promise\<void> | 准备播放视频的Promise返回值。 | 6007 6008**示例：** 6009 6010```ts 6011import { BusinessError } from '@kit.BasicServicesKit'; 6012 6013videoPlayer.prepare().then(() => { 6014 console.info('Succeeded in preparing'); 6015}).catch((error: BusinessError) => { 6016 console.error(`video catchCallback, error:${error}`); 6017}); 6018``` 6019 6020### play<sup>(deprecated)</sup> 6021 6022play(callback: AsyncCallback\<void>): void 6023 6024开始播放视频。通过回调函数获取返回值。 6025 6026> **说明：** 6027> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9)替代。 6028 6029**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6030 6031**参数：** 6032 6033| 参数名 | 类型 | 必填 | 说明 | 6034| -------- | -------------------- | ---- | ------------------------ | 6035| callback | AsyncCallback\<void> | 是 | 回调函数。当开始播放视频成功，err为undefined，否则为错误对象。 | 6036 6037**示例：** 6038 6039```ts 6040import { BusinessError } from '@kit.BasicServicesKit'; 6041 6042videoPlayer.play((err: BusinessError) => { 6043 if (err) { 6044 console.error('Failed to play!'); 6045 } else { 6046 console.info('Succeeded in playing!'); 6047 } 6048}); 6049``` 6050 6051### play<sup>(deprecated)</sup> 6052 6053play(): Promise\<void> 6054 6055开始播放视频。通过Promise获取返回值。 6056 6057> **说明：** 6058> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.play](#play9-1)替代。 6059 6060**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6061 6062**返回值：** 6063 6064| 类型 | 说明 | 6065| -------------- | ----------------------------- | 6066| Promise\<void> | 开始播放视频的Promise返回值。 | 6067 6068**示例：** 6069 6070```ts 6071import { BusinessError } from '@kit.BasicServicesKit'; 6072 6073videoPlayer.play().then(() => { 6074 console.info('Succeeded in playing'); 6075}).catch((error: BusinessError) => { 6076 console.error(`video catchCallback, error:${error}`); 6077}); 6078``` 6079 6080### pause<sup>(deprecated)</sup> 6081 6082pause(callback: AsyncCallback\<void>): void 6083 6084通过回调方式暂停播放视频。通过回调函数获取返回值。 6085 6086> **说明：** 6087> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9)替代。 6088 6089**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6090 6091**参数：** 6092 6093| 参数名 | 类型 | 必填 | 说明 | 6094| -------- | -------------------- | ---- | ------------------------ | 6095| callback | AsyncCallback\<void> | 是 | 回调函数。当暂停播放视频成功，err为undefined，否则为错误对象。 | 6096 6097**示例：** 6098 6099```ts 6100import { BusinessError } from '@kit.BasicServicesKit'; 6101 6102videoPlayer.pause((err: BusinessError) => { 6103 if (err) { 6104 console.error('Failed to pause!'); 6105 } else { 6106 console.info('Succeeded in pausing!'); 6107 } 6108}); 6109``` 6110 6111### pause<sup>(deprecated)</sup> 6112 6113pause(): Promise\<void> 6114 6115暂停播放视频。通过Promise获取返回值。 6116 6117> **说明：** 6118> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.pause](#pause9-1)替代。 6119 6120**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6121 6122**返回值：** 6123 6124| 类型 | 说明 | 6125| -------------- | ----------------------------- | 6126| Promise\<void> | 暂停播放视频的Promise返回值。 | 6127 6128**示例：** 6129 6130```ts 6131import { BusinessError } from '@kit.BasicServicesKit'; 6132 6133videoPlayer.pause().then(() => { 6134 console.info('Succeeded in pausing'); 6135}).catch((error: BusinessError) => { 6136 console.error(`video catchCallback, error:${error}`); 6137}); 6138``` 6139 6140### stop<sup>(deprecated)</sup> 6141 6142stop(callback: AsyncCallback\<void>): void 6143 6144通过回调方式停止播放视频。通过回调函数获取返回值。 6145 6146> **说明：** 6147> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9)替代。 6148 6149**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6150 6151**参数：** 6152 6153| 参数名 | 类型 | 必填 | 说明 | 6154| -------- | -------------------- | ---- | ------------------------ | 6155| callback | AsyncCallback\<void> | 是 | 回调函数。当停止播放视频成功，err为undefined，否则为错误对象。 | 6156 6157**示例：** 6158 6159```ts 6160import { BusinessError } from '@kit.BasicServicesKit'; 6161 6162videoPlayer.stop((err: BusinessError) => { 6163 if (err) { 6164 console.error('Failed to stop!'); 6165 } else { 6166 console.info('Succeeded in stopping!'); 6167 } 6168}); 6169``` 6170 6171### stop<sup>(deprecated)</sup> 6172 6173stop(): Promise\<void> 6174 6175停止播放视频。通过Promise获取返回值。 6176 6177> **说明：** 6178> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.stop](#stop9-1)替代。 6179 6180**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6181 6182**返回值：** 6183 6184| 类型 | 说明 | 6185| -------------- | ----------------------------- | 6186| Promise\<void> | 停止播放视频的Promise返回值。 | 6187 6188**示例：** 6189 6190```ts 6191import { BusinessError } from '@kit.BasicServicesKit'; 6192 6193videoPlayer.stop().then(() => { 6194 console.info('Succeeded in stopping'); 6195}).catch((error: BusinessError) => { 6196 console.error(`video catchCallback, error:${error}`); 6197}); 6198``` 6199 6200### reset<sup>(deprecated)</sup> 6201 6202reset(callback: AsyncCallback\<void>): void 6203 6204重置播放视频。通过回调函数获取返回值。 6205 6206> **说明：** 6207> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9)替代。 6208 6209**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6210 6211**参数：** 6212 6213| 参数名 | 类型 | 必填 | 说明 | 6214| -------- | -------------------- | ---- | ------------------------ | 6215| callback | AsyncCallback\<void> | 是 | 回调函数。当重置播放视频成功，err为undefined，否则为错误对象。 | 6216 6217**示例：** 6218 6219```ts 6220import { BusinessError } from '@kit.BasicServicesKit'; 6221 6222videoPlayer.reset((err: BusinessError) => { 6223 if (err) { 6224 console.error('Failed to reset!'); 6225 } else { 6226 console.info('Succeeded in resetting!'); 6227 } 6228}); 6229``` 6230 6231### reset<sup>(deprecated)</sup> 6232 6233reset(): Promise\<void> 6234 6235重置播放视频。通过Promise获取返回值。 6236 6237> **说明：** 6238> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.reset](#reset9-1)替代。 6239 6240**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6241 6242**返回值：** 6243 6244| 类型 | 说明 | 6245| -------------- | ----------------------------- | 6246| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 6247 6248**示例：** 6249 6250```ts 6251import { BusinessError } from '@kit.BasicServicesKit'; 6252 6253videoPlayer.reset().then(() => { 6254 console.info('Succeeded in resetting'); 6255}).catch((error: BusinessError) => { 6256 console.error(`video catchCallback, error:${error}`); 6257}); 6258``` 6259 6260### seek<sup>(deprecated)</sup> 6261 6262seek(timeMs: number, callback: AsyncCallback\<number>): void 6263 6264跳转到指定播放位置，默认跳转到指定时间点的上一个关键帧。通过回调函数获取返回值。 6265 6266> **说明：** 6267> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6268 6269**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6270 6271**参数：** 6272 6273| 参数名 | 类型 | 必填 | 说明 | 6274| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 6275| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6276| callback | AsyncCallback\<number> | 是 | 回调函数。跳转到指定播放位置成功时，err为undefined，data为获取到的跳转到的播放位置，否则为错误对象。 | 6277 6278**示例：** 6279 6280```ts 6281import { BusinessError } from '@kit.BasicServicesKit'; 6282 6283let videoPlayer: media.VideoPlayer; 6284media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6285 if (video != null) { 6286 videoPlayer = video; 6287 console.info('Succeeded in creating VideoPlayer'); 6288 } else { 6289 console.error(`Failed to create VideoPlayer, error:${error}`); 6290 } 6291}); 6292 6293let seekTime: number = 5000; 6294videoPlayer.seek(seekTime, (err: BusinessError, result: number) => { 6295 if (err) { 6296 console.error('Failed to do seek!'); 6297 } else { 6298 console.info('Succeeded in doing seek!'); 6299 } 6300}); 6301``` 6302 6303### seek<sup>(deprecated)</sup> 6304 6305seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\<number>): void 6306 6307跳转到指定播放位置。通过回调函数获取返回值。 6308 6309> **说明：** 6310> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6311 6312**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6313 6314**参数：** 6315 6316| 参数名 | 类型 | 必填 | 说明 | 6317| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 6318| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6319| mode | [SeekMode](#seekmode8) | 是 | 跳转模式。 | 6320| callback | AsyncCallback\<number> | 是 | 回调函数。跳转到指定播放位置成功时，err为undefined，data为获取到的跳转到的播放位置，否则为错误对象。 | 6321 6322**示例：** 6323 6324```ts 6325import { BusinessError } from '@kit.BasicServicesKit'; 6326 6327let videoPlayer: media.VideoPlayer | null = null; 6328media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6329 if (video != null) { 6330 videoPlayer = video; 6331 console.info('Succeeded in creating VideoPlayer'); 6332 } else { 6333 console.error(`Failed to create VideoPlayer, error:${error}`); 6334 } 6335}); 6336let seekTime: number = 5000; 6337if (videoPlayer) { 6338 (videoPlayer as media.VideoPlayer).seek(seekTime, media.SeekMode.SEEK_NEXT_SYNC, (err: BusinessError, result: number) => { 6339 if (err) { 6340 console.error('Failed to do seek!'); 6341 } else { 6342 console.info('Succeeded in doing seek!'); 6343 } 6344 }); 6345} 6346``` 6347 6348### seek<sup>(deprecated)</sup> 6349 6350seek(timeMs: number, mode?:SeekMode): Promise\<number> 6351 6352跳转到指定播放位置，如果没有设置mode则跳转到指定时间点的上一个关键帧。通过Promise获取返回值。 6353 6354> **说明：** 6355> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.seek](#seek9)替代。 6356 6357**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6358 6359**参数：** 6360 6361| 参数名 | 类型 | 必填 | 说明 | 6362| ------ | ---------------------- | ---- | ------------------------------------------------------------ | 6363| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms），取值范围为[0, duration]。 | 6364| mode | [SeekMode](#seekmode8) | 否 | 基于视频I帧的跳转模式，默认为SEEK_PREV_SYNC模式。 | 6365 6366**返回值：** 6367 6368| 类型 | 说明 | 6369| ---------------- | ------------------------------------------- | 6370| Promise\<number> | 跳转到指定播放位置的Promise返回值，单位ms。 | 6371 6372**示例：** 6373 6374```ts 6375import { BusinessError } from '@kit.BasicServicesKit'; 6376 6377let videoPlayer: media.VideoPlayer | null = null; 6378media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6379 if (video != null) { 6380 videoPlayer = video; 6381 console.info('Succeeded in creating VideoPlayer'); 6382 } else { 6383 console.error(`Failed to create VideoPlayer, error:${error}`); 6384 } 6385}); 6386let seekTime: number = 5000; 6387if (videoPlayer) { 6388 (videoPlayer as media.VideoPlayer).seek(seekTime).then((seekDoneTime: number) => { // seekDoneTime表示seek完成后的时间点。 6389 console.info('Succeeded in doing seek'); 6390 }).catch((error: BusinessError) => { 6391 console.error(`video catchCallback, error:${error}`); 6392 }); 6393 6394 (videoPlayer as media.VideoPlayer).seek(seekTime, media.SeekMode.SEEK_NEXT_SYNC).then((seekDoneTime: number) => { 6395 console.info('Succeeded in doing seek'); 6396 }).catch((error: BusinessError) => { 6397 console.error(`video catchCallback, error:${error}`); 6398 }); 6399} 6400``` 6401 6402### setVolume<sup>(deprecated)</sup> 6403 6404setVolume(vol: number, callback: AsyncCallback\<void>): void 6405 6406设置音量。通过回调函数获取返回值。 6407 6408> **说明：** 6409> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 6410 6411**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6412 6413**参数：** 6414 6415| 参数名 | 类型 | 必填 | 说明 | 6416| -------- | -------------------- | ---- | ------------------------------------------------------------ | 6417| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 6418| callback | AsyncCallback\<void> | 是 | 回调函数。当设置音量成功，err为undefined，否则为错误对象。 | 6419 6420**示例：** 6421 6422```ts 6423import { BusinessError } from '@kit.BasicServicesKit'; 6424 6425let vol: number = 0.5; 6426videoPlayer.setVolume(vol, (err: BusinessError) => { 6427 if (err) { 6428 console.error('Failed to set Volume!'); 6429 } else { 6430 console.info('Succeeded in setting Volume!'); 6431 } 6432}); 6433``` 6434 6435### setVolume<sup>(deprecated)</sup> 6436 6437setVolume(vol: number): Promise\<void> 6438 6439设置音量。通过Promise获取返回值。 6440 6441> **说明：** 6442> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setVolume](#setvolume9)替代。 6443 6444**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6445 6446**参数：** 6447 6448| 参数名 | 类型 | 必填 | 说明 | 6449| ------ | ------ | ---- | ------------------------------------------------------------ | 6450| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 6451 6452**返回值：** 6453 6454| 类型 | 说明 | 6455| -------------- | ------------------------- | 6456| Promise\<void> | 设置音量的Promise返回值。 | 6457 6458**示例：** 6459 6460```ts 6461import { BusinessError } from '@kit.BasicServicesKit'; 6462 6463let vol: number = 0.5; 6464videoPlayer.setVolume(vol).then(() => { 6465 console.info('Succeeded in setting Volume'); 6466}).catch((error: BusinessError) => { 6467 console.error(`video catchCallback, error:${error}`); 6468}); 6469``` 6470 6471### release<sup>(deprecated)</sup> 6472 6473release(callback: AsyncCallback\<void>): void 6474 6475释放视频资源。通过回调函数获取返回值。 6476 6477> **说明：** 6478> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9)替代。 6479 6480**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6481 6482**参数：** 6483 6484| 参数名 | 类型 | 必填 | 说明 | 6485| -------- | -------------------- | ---- | ------------------------ | 6486| callback | AsyncCallback\<void> | 是 | 回调函数。当释放视频资源成功，err为undefined，否则为错误对象。 | 6487 6488**示例：** 6489 6490```ts 6491import { BusinessError } from '@kit.BasicServicesKit'; 6492 6493videoPlayer.release((err: BusinessError) => { 6494 if (err) { 6495 console.error('Failed to release!'); 6496 } else { 6497 console.info('Succeeded in releasing!'); 6498 } 6499}); 6500``` 6501 6502### release<sup>(deprecated)</sup> 6503 6504release(): Promise\<void> 6505 6506释放视频资源。通过Promise获取返回值。 6507 6508> **说明：** 6509> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.release](#release9-1)替代。 6510 6511**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6512 6513**返回值：** 6514 6515| 类型 | 说明 | 6516| -------------- | ----------------------------- | 6517| Promise\<void> | 释放视频资源的Promise返回值。 | 6518 6519**示例：** 6520 6521```ts 6522import { BusinessError } from '@kit.BasicServicesKit'; 6523 6524videoPlayer.release().then(() => { 6525 console.info('Succeeded in releasing'); 6526}).catch((error: BusinessError) => { 6527 console.error(`video catchCallback, error:${error}`); 6528}); 6529``` 6530 6531### getTrackDescription<sup>(deprecated)</sup> 6532 6533getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void 6534 6535获取视频轨道信息。通过回调函数获取返回值。 6536 6537> **说明：** 6538> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9)替代。 6539 6540**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6541 6542**参数：** 6543 6544| 参数名 | 类型 | 必填 | 说明 | 6545| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 6546| callback | AsyncCallback\<Array\<[MediaDescription](#mediadescription8)>> | 是 | 回调函数。获取视频轨道信息成功时，err为undefined，data为获取到的视频轨道信息MediaDescription数组，否则为错误对象。 | 6547 6548**示例：** 6549 6550```ts 6551import { BusinessError } from '@kit.BasicServicesKit'; 6552 6553videoPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => { 6554 if ((arrList) != null) { 6555 console.info('Succeeded in getting TrackDescription'); 6556 } else { 6557 console.error(`Failed to get TrackDescription, error:${error}`); 6558 } 6559}); 6560``` 6561 6562### getTrackDescription<sup>(deprecated)</sup> 6563 6564getTrackDescription(): Promise\<Array\<MediaDescription>> 6565 6566获取视频轨道信息。通过Promise获取返回值。 6567 6568> **说明：** 6569> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.getTrackDescription](#gettrackdescription9-1)替代。 6570 6571**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6572 6573**返回值：** 6574 6575| 类型 | 说明 | 6576| ------------------------------------------------------ | ----------------------------------------------- | 6577| Promise<Array<[MediaDescription](#mediadescription8)>> | Promise对象，返回获取的视频轨道信息MediaDescription数组。 | 6578 6579**示例：** 6580 6581```ts 6582import { BusinessError } from '@kit.BasicServicesKit'; 6583 6584videoPlayer.getTrackDescription().then((arrList: Array<media.MediaDescription>) => { 6585 if (arrList != null) { 6586 console.info('Succeeded in getting TrackDescription'); 6587 } else { 6588 console.error('Failed to get TrackDescription'); 6589 } 6590}).catch((error: BusinessError) => { 6591 console.error(`video catchCallback, error:${error}`); 6592}); 6593``` 6594 6595### setSpeed<sup>(deprecated)</sup> 6596 6597setSpeed(speed: number, callback: AsyncCallback\<number>): void 6598 6599设置播放速度。通过回调函数获取返回值。 6600 6601> **说明：** 6602> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setSpeed](#setspeed9)替代。 6603 6604**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6605 6606**参数：** 6607 6608| 参数名 | 类型 | 必填 | 说明 | 6609| -------- | ---------------------- | ---- | ---------------------------------------------------------- | 6610| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 6611| callback | AsyncCallback\<number> | 是 | 回调函数。设置播放速度成功时，err为undefined，data为设置的播放速度，否则为错误对象。 | 6612 6613**示例：** 6614 6615```ts 6616import { BusinessError } from '@kit.BasicServicesKit'; 6617 6618let videoPlayer: media.VideoPlayer | null = null; 6619media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6620 if (video != null) { 6621 videoPlayer = video; 6622 console.info('Succeeded in creating VideoPlayer'); 6623 } else { 6624 console.error(`Failed to create VideoPlayer, error:${error}`); 6625 } 6626}); 6627let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X; 6628if (videoPlayer) { 6629 (videoPlayer as media.VideoPlayer).setSpeed(speed, (err: BusinessError, result: number) => { 6630 if (err) { 6631 console.error('Failed to set Speed!'); 6632 } else { 6633 console.info('Succeeded in setting Speed!'); 6634 } 6635 }); 6636} 6637``` 6638 6639### setSpeed<sup>(deprecated)</sup> 6640 6641setSpeed(speed: number): Promise\<number> 6642 6643设置播放速度。通过Promise获取返回值。 6644 6645> **说明：** 6646> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.setSpeed](#setspeed9)替代。 6647 6648**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6649 6650**参数：** 6651 6652| 参数名 | 类型 | 必填 | 说明 | 6653| ------ | ------ | ---- | ---------------------------------------------------------- | 6654| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 6655 6656**返回值：** 6657 6658| 类型 | 说明 | 6659| ---------------- | ------------------------------------------------------------ | 6660| Promise\<number> | Promise对象，返回设置的播放速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 6661 6662**示例：** 6663 6664```ts 6665import { BusinessError } from '@kit.BasicServicesKit'; 6666 6667let videoPlayer: media.VideoPlayer | null = null; 6668media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => { 6669 if (video != null) { 6670 videoPlayer = video; 6671 console.info('Succeeded in creating VideoPlayer'); 6672 } else { 6673 console.error(`Failed to create VideoPlayer, error:${error}`); 6674 } 6675}); 6676let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X; 6677if (videoPlayer) { 6678 (videoPlayer as media.VideoPlayer).setSpeed(speed).then((result: number) => { 6679 console.info('Succeeded in setting Speed'); 6680 }).catch((error: BusinessError) => { 6681 console.error(`Failed to set Speed, error:${error}`);//todo:: error. 6682 }); 6683} 6684``` 6685 6686### on('playbackCompleted')<sup>(deprecated)</sup> 6687 6688on(type: 'playbackCompleted', callback: Callback\<void>): void 6689 6690开始监听视频播放完成事件。 6691 6692> **说明：** 6693> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('stateChange')](#onstatechange9)替代。 6694 6695**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6696 6697**参数：** 6698 6699| 参数名 | 类型 | 必填 | 说明 | 6700| -------- | -------- | ---- | ----------------------------------------------------------- | 6701| type | string | 是 | 视频播放完成事件回调类型，支持的事件：'playbackCompleted'。 | 6702| callback | Callback\<void> | 是 | 视频播放完成事件回调方法。 | 6703 6704**示例：** 6705 6706```ts 6707videoPlayer.on('playbackCompleted', () => { 6708 console.info('playbackCompleted called!'); 6709}); 6710``` 6711 6712### on('bufferingUpdate')<sup>(deprecated)</sup> 6713 6714on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void 6715 6716开始监听视频缓存更新事件。仅网络播放支持该订阅事件。 6717 6718> **说明：** 6719> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('bufferingUpdate')](#onbufferingupdate9)替代。 6720 6721**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6722 6723**参数：** 6724 6725| 参数名 | 类型 | 必填 | 说明 | 6726| -------- | -------- | ---- | ------------------------------------------------------------ | 6727| type | string | 是 | 视频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 6728| callback | function | 是 | 视频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)value值固定为0。 | 6729 6730**示例：** 6731 6732```ts 6733videoPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => { 6734 console.info('video bufferingInfo type: ' + infoType); 6735 console.info('video bufferingInfo value: ' + value); 6736}); 6737``` 6738 6739### on('startRenderFrame')<sup>(deprecated)</sup> 6740 6741on(type: 'startRenderFrame', callback: Callback\<void>): void 6742 6743开始监听视频播放首帧送显上报事件。 6744 6745> **说明：** 6746> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('startRenderFrame')](#onstartrenderframe9)替代。 6747 6748**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6749 6750**参数：** 6751 6752| 参数名 | 类型 | 必填 | 说明 | 6753| -------- | --------------- | ---- | ------------------------------------------------------------ | 6754| type | string | 是 | 视频播放首帧送显上报事件回调类型，支持的事件：'startRenderFrame'。 | 6755| callback | Callback\<void> | 是 | 视频播放首帧送显上报事件回调方法。 | 6756 6757**示例：** 6758 6759```ts 6760videoPlayer.on('startRenderFrame', () => { 6761 console.info('startRenderFrame called!'); 6762}); 6763``` 6764 6765### on('videoSizeChanged')<sup>(deprecated)</sup> 6766 6767on(type: 'videoSizeChanged', callback: (width: number, height: number) => void): void 6768 6769开始监听视频播放宽高变化事件。 6770 6771> **说明：** 6772> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('videoSizeChange')](#onvideosizechange9)替代。 6773 6774**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6775 6776**参数：** 6777 6778| 参数名 | 类型 | 必填 | 说明 | 6779| -------- | -------- | ---- | ------------------------------------------------------------ | 6780| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChanged'。 | 6781| callback | function | 是 | 视频播放宽高变化事件回调方法，width表示宽，height表示高。 | 6782 6783**示例：** 6784 6785```ts 6786videoPlayer.on('videoSizeChanged', (width: number, height: number) => { 6787 console.info('video width is: ' + width); 6788 console.info('video height is: ' + height); 6789}); 6790``` 6791### on('audioInterrupt')<sup>(deprecated)</sup> 6792 6793on(type: 'audioInterrupt', callback: (info: audio.InterruptEvent) => void): void 6794 6795监听音频焦点变化事件，参考[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)。 6796 6797> **说明：** 6798> 从API version 9开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('audioInterrupt')](#onaudiointerrupt9)替代。 6799 6800**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6801 6802**参数：** 6803 6804| 参数名 | 类型 | 必填 | 说明 | 6805| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- | 6806| type | string | 是 | 音频焦点变化事件回调类型，支持的事件：'audioInterrupt'。 | 6807| callback | function | 是 | 音频焦点变化事件回调方法。 | 6808 6809**示例：** 6810 6811```ts 6812import { audio } from '@kit.AudioKit'; 6813 6814videoPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => { 6815 console.info('audioInterrupt called,and InterruptEvent info is:' + info) 6816}) 6817``` 6818 6819### on('error')<sup>(deprecated)</sup> 6820 6821on(type: 'error', callback: ErrorCallback): void 6822 6823开始监听视频播放错误事件，当上报error错误事件后，用户需处理error事件，退出播放操作。 6824 6825> **说明：** 6826> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayer.on('error')](#onerror9)替代。 6827 6828**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6829 6830**参数：** 6831 6832| 参数名 | 类型 | 必填 | 说明 | 6833| -------- | ------------- | ---- | ------------------------------------------------------------ | 6834| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：视频播放中发生错误，触发该事件。 | 6835| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 播放错误事件回调方法。 | 6836 6837**示例：** 6838 6839```ts 6840import { BusinessError } from '@kit.BasicServicesKit'; 6841 6842videoPlayer.on('error', (error: BusinessError) => { // 设置'error'事件回调。 6843 console.error(`video error called, error: ${error}`); 6844}); 6845videoPlayer.url = 'fd://error'; //设置错误的播放地址，触发'error'事件。 6846``` 6847 6848## VideoPlayState<sup>(deprecated)</sup> 6849 6850type VideoPlayState = 'idle' | 'prepared' | 'playing' | 'paused' | 'stopped' | 'error' 6851 6852视频播放的状态机，可通过state属性获取当前状态。 6853 6854> **说明：** 6855> 从API version 8开始支持，从API version 9开始废弃，建议使用[AVPlayerState](#avplayerstate9)替代。 6856 6857**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 6858 6859| 类型 | 说明 | 6860| -------- | -------------- | 6861| 'idle' | 视频播放空闲。 | 6862| 'prepared' | 视频播放准备。 | 6863| 'playing' | 视频正在播放。 | 6864| 'paused' | 视频暂停播放。 | 6865| 'stopped' | 视频播放停止。 | 6866| 'error' | 错误状态。 | 6867 6868## AudioRecorder<sup>(deprecated)</sup> 6869 6870> **说明：** 6871> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder](#avrecorder9)替代。 6872 6873音频录制管理类，用于录制音频媒体。在调用AudioRecorder的方法前，需要先通过[createAudioRecorder()](#mediacreateaudiorecorderdeprecated) 构建一个AudioRecorder实例。 6874 6875### prepare<sup>(deprecated)</sup> 6876 6877prepare(config: AudioRecorderConfig): void 6878 6879录音准备。 6880 6881> **说明：** 6882> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.prepare](#prepare9-2)替代。 6883 6884**需要权限：** ohos.permission.MICROPHONE 6885 6886**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6887 6888**参数：** 6889 6890| 参数名 | 类型 | 必填 | 说明 | 6891| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ | 6892| config | [AudioRecorderConfig](#audiorecorderconfigdeprecated) | 是 | 配置录音的相关参数，包括音频输出URI、编码格式、采样率、声道数、输出格式等。 | 6893 6894**错误码：** 6895 6896以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 6897 6898| 错误码ID | 错误信息 | 6899| -------- | --------------------- | 6900| 201 | permission denied | 6901 6902**示例：** 6903 6904```ts 6905let audioRecorderConfig: media.AudioRecorderConfig = { 6906 audioEncoder : media.AudioEncoder.AAC_LC, 6907 audioEncodeBitRate : 22050, 6908 audioSampleRate : 22050, 6909 numberOfChannels : 2, 6910 format : media.AudioOutputFormat.AAC_ADTS, 6911 uri : 'fd://1', // 文件需先由调用者创建，并给予适当的权限。 6912 location : { latitude : 30, longitude : 130}, 6913} 6914audioRecorder.on('prepare', () => { //设置'prepare'事件回调。 6915 console.info('prepare called'); 6916}); 6917audioRecorder.prepare(audioRecorderConfig); 6918``` 6919 6920### start<sup>(deprecated)</sup> 6921 6922start(): void 6923 6924开始录制，需在'prepare'事件成功触发后，才能调用start方法。 6925 6926> **说明：** 6927> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.start](#start9)替代。 6928 6929**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6930 6931**示例：** 6932 6933```ts 6934audioRecorder.on('start', () => { //设置'start'事件回调。 6935 console.info('audio recorder start called'); 6936}); 6937audioRecorder.start(); 6938``` 6939 6940### pause<sup>(deprecated)</sup> 6941 6942pause():void 6943 6944暂停录制，需要在'start'事件成功触发后，才能调用pause方法。 6945 6946> **说明：** 6947> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.pause](#pause9-2)替代。 6948 6949**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6950 6951**示例：** 6952 6953```ts 6954audioRecorder.on('pause', () => { //设置'pause'事件回调。 6955 console.info('audio recorder pause called'); 6956}); 6957audioRecorder.pause(); 6958``` 6959 6960### resume<sup>(deprecated)</sup> 6961 6962resume():void 6963 6964恢复录制，需要在'pause'事件成功触发后，才能调用resume方法。 6965 6966> **说明：** 6967> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.resume](#resume9)替代。 6968 6969**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6970 6971**示例：** 6972 6973```ts 6974audioRecorder.on('resume', () => { //设置'resume'事件回调。 6975 console.info('audio recorder resume called'); 6976}); 6977audioRecorder.resume(); 6978``` 6979 6980### stop<sup>(deprecated)</sup> 6981 6982stop(): void 6983 6984停止录音。 6985 6986> **说明：** 6987> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.stop](#stop9-2)替代。 6988 6989**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 6990 6991**示例：** 6992 6993```ts 6994audioRecorder.on('stop', () => { //设置'stop'事件回调。 6995 console.info('audio recorder stop called'); 6996}); 6997audioRecorder.stop(); 6998``` 6999 7000### release<sup>(deprecated)</sup> 7001 7002release(): void 7003 7004释放录音资源。 7005 7006> **说明：** 7007> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.release](#release9-2)替代。 7008 7009**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7010 7011**示例：** 7012 7013```ts 7014audioRecorder.on('release', () => { //设置'release'事件回调。 7015 console.info('audio recorder release called'); 7016}); 7017audioRecorder.release(); 7018audioRecorder = undefined; 7019``` 7020 7021### reset<sup>(deprecated)</sup> 7022 7023reset(): void 7024 7025重置录音。 7026 7027进行重置录音之前，需要先调用stop()停止录音。重置录音之后，需要调用prepare()设置录音参数项，才能再次进行录音。 7028 7029> **说明：** 7030> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.reset](#reset9-2)替代。 7031 7032**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7033 7034**示例：** 7035 7036```ts 7037audioRecorder.on('reset', () => { //设置'reset'事件回调。 7038 console.info('audio recorder reset called'); 7039}); 7040audioRecorder.reset(); 7041``` 7042 7043### on('prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset')<sup>(deprecated)</sup> 7044 7045on(type: 'prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset', callback: () => void): void 7046 7047开始订阅音频录制事件。 7048 7049> **说明：** 7050> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.on('stateChange')](#onstatechange9-1)替代。 7051 7052**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7053 7054**参数：** 7055 7056| 参数名 | 类型 | 必填 | 说明 | 7057| -------- | -------- | ---- | ------------------------------------------------------------ | 7058| 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调用，音频重置为初始状态，触发该事件。 | 7059| callback | ()=>void | 是 | 录制事件回调方法。 | 7060 7061**示例：** 7062 7063```ts 7064import { BusinessError } from '@kit.BasicServicesKit'; 7065 7066let audioRecorder: media.AudioRecorder = media.createAudioRecorder(); // 创建一个音频录制实例。 7067let audioRecorderConfig: media.AudioRecorderConfig = { 7068 audioEncoder : media.AudioEncoder.AAC_LC, 7069 audioEncodeBitRate : 22050, 7070 audioSampleRate : 22050, 7071 numberOfChannels : 2, 7072 format : media.AudioOutputFormat.AAC_ADTS, 7073 uri : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限。 7074 location : { latitude : 30, longitude : 130} 7075} 7076audioRecorder.on('error', (error: BusinessError) => { // 设置'error'事件回调。 7077 console.error(`audio error called, error: ${error}`); 7078}); 7079audioRecorder.on('prepare', () => { // 设置'prepare'事件回调。 7080 console.info('prepare called'); 7081 audioRecorder.start(); // 开始录制，并触发'start'事件回调。 7082}); 7083audioRecorder.on('start', () => { // 设置'start'事件回调。 7084 console.info('audio recorder start called'); 7085}); 7086audioRecorder.on('pause', () => { // 设置'pause'事件回调。 7087 console.info('audio recorder pause called'); 7088}); 7089audioRecorder.on('resume', () => { // 设置'resume'事件回调。 7090 console.info('audio recorder resume called'); 7091}); 7092audioRecorder.on('stop', () => { // 设置'stop'事件回调。 7093 console.info('audio recorder stop called'); 7094}); 7095audioRecorder.on('release', () => { // 设置'release'事件回调。 7096 console.info('audio recorder release called'); 7097}); 7098audioRecorder.on('reset', () => { // 设置'reset'事件回调。 7099 console.info('audio recorder reset called'); 7100}); 7101audioRecorder.prepare(audioRecorderConfig) // 设置录制参数 ，并触发'prepare'事件回调。 7102``` 7103 7104### on('error')<sup>(deprecated)</sup> 7105 7106on(type: 'error', callback: ErrorCallback): void 7107 7108开始订阅音频录制错误事件，当上报error错误事件后，用户需处理error事件，退出录制操作。 7109 7110> **说明：** 7111> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorder.on('error')](#onerror9-1)替代。 7112 7113**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7114 7115**参数：** 7116 7117| 参数名 | 类型 | 必填 | 说明 | 7118| -------- | ------------- | ---- | ------------------------------------------------------------ | 7119| type | string | 是 | 录制错误事件回调类型'error'。<br/>- 'error'：音频录制过程中发生错误，触发该事件。 | 7120| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录制错误事件回调方法。 | 7121 7122**示例：** 7123 7124```ts 7125import { BusinessError } from '@kit.BasicServicesKit'; 7126 7127let audioRecorderConfig: media.AudioRecorderConfig = { 7128 audioEncoder : media.AudioEncoder.AAC_LC, 7129 audioEncodeBitRate : 22050, 7130 audioSampleRate : 22050, 7131 numberOfChannels : 2, 7132 format : media.AudioOutputFormat.AAC_ADTS, 7133 uri : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限。 7134 location : { latitude : 30, longitude : 130} 7135} 7136audioRecorder.on('error', (error: BusinessError) => { // 设置'error'事件回调。 7137 console.error(`audio error called, error: ${error}`); 7138}); 7139audioRecorder.prepare(audioRecorderConfig); // prepare不设置参数，触发'error'事件。 7140``` 7141 7142## AudioRecorderConfig<sup>(deprecated)</sup> 7143 7144> **说明：** 7145> 从API version 6开始支持，从API version 9开始废弃，建议使用[AVRecorderConfig](#avrecorderconfig9)替代。 7146 7147表示音频的录音配置。 7148 7149**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7150 7151| 名称 | 类型 | 必填 | 说明 | 7152| ----------------------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 7153| audioEncoder | [AudioEncoder](#audioencoderdeprecated) | 否 | 音频编码格式，默认设置为AAC_LC。<br/>**说明：** 从API version 8开始废弃，建议使用audioEncoderMime替代。 | 7154| audioEncodeBitRate | number | 否 | 音频编码比特率，默认值为48000。 | 7155| audioSampleRate | number | 否 | 音频采集采样率，默认值为48000。<br>可变比特率模式，码率仅作参考。 | 7156| numberOfChannels | number | 否 | 音频采集声道数，默认值为2。 | 7157| format | [AudioOutputFormat](#audiooutputformatdeprecated) | 否 | 音频输出封装格式，默认设置为MPEG_4。<br/>**说明：** 从API version 8开始废弃，建议使用fileFormat替代。 | 7158| location | [Location](#location) | 否 | 音频采集的地理位置。 | 7159| uri | string | 是 | 音频输出URI：fd://xx (fd number)<br/> <br/>文件需要由调用者创建，并赋予适当的权限。 | 7160| audioEncoderMime<sup>8+</sup> | [CodecMimeType](#codecmimetype8) | 否 | 容器编码格式。 | 7161| fileFormat<sup>8+</sup> | [ContainerFormatType](#containerformattype8) | 否 | 音频编码格式。 | 7162 7163## AudioEncoder<sup>(deprecated)</sup> 7164 7165> **说明：** 7166> 从API version 6开始支持，从API version 8开始废弃，建议使用[CodecMimeType](#codecmimetype8)替代。 7167 7168表示音频编码格式的枚举。 7169 7170**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7171 7172| 名称 | 值 | 说明 | 7173| ------- | ---- | ------------------------------------------------------------ | 7174| DEFAULT | 0 | 默认编码格式。<br/>仅做接口定义，暂不支持使用。 | 7175| AMR_NB | 1 | AMR-NB(Adaptive Multi Rate-Narrow Band Speech Codec) 编码格式。<br/>仅做接口定义，暂不支持使用。 | 7176| AMR_WB | 2 | AMR-WB(Adaptive Multi Rate-Wide Band Speech Codec) 编码格式。<br/>仅做接口定义，暂不支持使用。 | 7177| AAC_LC | 3 | AAC-LC（Advanced Audio Coding Low Complexity）编码格式。 | 7178| HE_AAC | 4 | HE_AAC（High-Efficiency Advanced Audio Coding）编码格式。<br/>仅做接口定义，暂不支持使用。 | 7179 7180## AudioOutputFormat<sup>(deprecated)</sup> 7181 7182> **说明：** 7183> 从API version 6开始支持，从API version 8 开始废弃，建议使用[ContainerFormatType](#containerformattype8)替代。 7184 7185表示音频封装格式的枚举。 7186 7187**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 7188 7189| 名称 | 值 | 说明 | 7190| -------- | ---- | ------------------------------------------------------------ | 7191| DEFAULT | 0 | 默认封装格式。<br/>仅做接口定义，暂不支持使用。 | 7192| MPEG_4 | 2 | 封装为MPEG-4格式。 | 7193| AMR_NB | 3 | 封装为AMR_NB格式。<br/>仅做接口定义，暂不支持使用。 | 7194| AMR_WB | 4 | 封装为AMR_WB格式。<br/>仅做接口定义，暂不支持使用。 | 7195| AAC_ADTS | 6 | 封装为ADTS（Audio Data Transport Stream）格式，是AAC音频的传输流格式。 | 7196 7197 7198## media.createAVImageGenerator<sup>12+</sup> 7199 7200createAVImageGenerator(callback: AsyncCallback\<AVImageGenerator>): void 7201 7202创建AVImageGenerator实例，通过回调函数获取返回值。 7203 7204**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7205 7206**参数：** 7207 7208| 参数名 | 类型 | 必填 | 说明 | 7209| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 7210| callback | AsyncCallback\<[AVImageGenerator](#avimagegenerator12)> | 是 | 回调函数。异步返回AVImageGenerator实例，失败时返回null。可用于获取视频缩略图。 | 7211 7212**错误码：** 7213 7214以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7215 7216| 错误码ID | 错误信息 | 7217| -------- | ------------------------------ | 7218| 5400101 | No memory. Returned by callback. | 7219 7220**示例：** 7221 7222```ts 7223import { BusinessError } from '@kit.BasicServicesKit'; 7224 7225let avImageGenerator: media.AVImageGenerator; 7226media.createAVImageGenerator((error: BusinessError, generator: media.AVImageGenerator) => { 7227 if (generator != null) { 7228 avImageGenerator = generator; 7229 console.info('Succeeded in creating AVImageGenerator'); 7230 } else { 7231 console.error(`Failed to creat AVImageGenerator, error message:${error.message}`); 7232 } 7233}); 7234``` 7235 7236## media.createAVImageGenerator<sup>12+</sup> 7237 7238createAVImageGenerator(): Promise\<AVImageGenerator> 7239 7240创建AVImageGenerator对象，通过Promise获取返回值。 7241 7242**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7243 7244**返回值：** 7245 7246| 类型 | 说明 | 7247| ------------------------------- | ------------------------------------------------------------ | 7248| Promise\<[AVImageGenerator](#avimagegenerator12)> | Promise对象。异步返回AVImageGenerator实例，失败时返回null。可用于获取视频缩略图。 | 7249 7250**错误码：** 7251 7252以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7253 7254| 错误码ID | 错误信息 | 7255| -------- | ----------------------------- | 7256| 5400101 | No memory. Returned by promise. | 7257 7258**示例：** 7259 7260```ts 7261import { BusinessError } from '@kit.BasicServicesKit'; 7262 7263let avImageGenerator: media.AVImageGenerator; 7264media.createAVImageGenerator().then((generator: media.AVImageGenerator) => { 7265 if (generator != null) { 7266 avImageGenerator = generator; 7267 console.info('Succeeded in creating AVImageGenerator'); 7268 } else { 7269 console.error('Failed to creat AVImageGenerator'); 7270 } 7271}).catch((error: BusinessError) => { 7272 console.error(`Failed to creat AVImageGenerator, error message:${error.message}`); 7273}); 7274``` 7275 7276## AVImageGenerator<sup>12+</sup> 7277 7278视频缩略图获取类，用于从视频资源中获取缩略图。在调用AVImageGenerator的方法前，需要先通过[createAVImageGenerator()](#mediacreateavimagegenerator12)构建一个AVImageGenerator实例。 7279 7280获取视频缩略图的demo可参考：[获取视频缩略图开发指导](../../media/media/avimagegenerator.md)。 7281 7282### 属性 7283 7284**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7285 7286| 名称 | 类型 | 可读 | 可写 | 说明 | 7287| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 7288| 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。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频缩略图数据获取异常。 | 7289 7290### fetchFrameByTime<sup>12+</sup> 7291 7292fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams, callback: AsyncCallback\<image.PixelMap>): void 7293 7294异步方式获取视频缩略图。通过注册回调函数获取返回值。 7295 7296**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7297 7298**参数：** 7299 7300| 参数名 | 类型 | 必填 | 说明 | 7301| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7302| timeUs | number | 是 | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 | 7303| options | [AVImageQueryOptions](#avimagequeryoptions12) | 是 | 需要获取的缩略图时间点与视频帧的对应关系。 | 7304| param | [PixelMapParams](#pixelmapparams12) | 是 | 需要获取的缩略图的格式参数。 | 7305| callback | AsyncCallback\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | 是 | 回调函数。获取缩略图成功时，err为undefined，data为PixelMap实例，否则为错误对象。 | 7306 7307**错误码：** 7308 7309以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7310 7311| 错误码ID | 错误信息 | 7312| -------- | ------------------------------------------ | 7313| 5400102 | Operation not allowed. Returned by callback. | 7314| 5400106 | Unsupported format. Returned by callback. | 7315 7316**示例：** 7317 7318```ts 7319import { BusinessError } from '@kit.BasicServicesKit'; 7320import { image } from '@kit.ImageKit'; 7321 7322let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7323let pixel_map : image.PixelMap | undefined = undefined; 7324 7325// 初始化入参。 7326let timeUs: number = 0 7327 7328let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC 7329 7330let param: media.PixelMapParams = { 7331 width : 300, 7332 height : 300, 7333} 7334 7335// 获取缩略图。 7336media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7337 if(generator != null){ 7338 avImageGenerator = generator; 7339 console.info(`Succeeded in creating AVImageGenerator`); 7340 avImageGenerator.fetchFrameByTime(timeUs, queryOption, param, (error: BusinessError, pixelMap) => { 7341 if (error) { 7342 console.error(`Failed to fetch FrameByTime, err = ${JSON.stringify(error)}`) 7343 return 7344 } 7345 pixel_map = pixelMap; 7346 }); 7347 } else { 7348 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7349 }; 7350}); 7351``` 7352 7353### fetchFrameByTime<sup>12+</sup> 7354 7355fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams): Promise<image.PixelMap> 7356 7357异步方式获取视频缩略图。通过Promise获取返回值。 7358 7359**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7360 7361**参数：** 7362 7363| 参数名 | 类型 | 必填 | 说明 | 7364| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7365| timeUs | number | 是 | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 | 7366| options | [AVImageQueryOptions](#avimagequeryoptions12) | 是 | 需要获取的缩略图时间点与视频帧的对应关系。 | 7367| param | [PixelMapParams](#pixelmapparams12) | 是 | 需要获取的缩略图的格式参数。 | 7368 7369**返回值：** 7370 7371| 类型 | 说明 | 7372| -------------- | ---------------------------------------- | 7373| Promise\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise对象，返回视频缩略图对象。 | 7374 7375**错误码：** 7376 7377以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7378 7379| 错误码ID | 错误信息 | 7380| -------- | ----------------------------------------- | 7381| 5400102 | Operation not allowed. Returned by promise. | 7382| 5400106 | Unsupported format. Returned by promise. | 7383 7384**示例：** 7385 7386```ts 7387import { BusinessError } from '@kit.BasicServicesKit'; 7388import { image } from '@kit.ImageKit'; 7389 7390let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7391let pixel_map : image.PixelMap | undefined = undefined; 7392 7393// 初始化入参。 7394let timeUs: number = 0 7395 7396let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC 7397 7398let param: media.PixelMapParams = { 7399 width : 300, 7400 height : 300, 7401} 7402 7403// 获取缩略图。 7404media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7405 if(generator != null){ 7406 avImageGenerator = generator; 7407 console.info(`Succeeded in creating AVImageGenerator`); 7408 avImageGenerator.fetchFrameByTime(timeUs, queryOption, param).then((pixelMap: image.PixelMap) => { 7409 pixel_map = pixelMap; 7410 }).catch((error: BusinessError) => { 7411 console.error(`Failed to fetch FrameByTime, error message:${error.message}`); 7412 }); 7413 } else { 7414 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7415 }; 7416}); 7417``` 7418 7419### release<sup>12+</sup> 7420 7421release(callback: AsyncCallback\<void>): void 7422 7423异步方式释放资源。通过注册回调函数获取返回值。 7424 7425**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7426 7427**参数：** 7428 7429| 参数名 | 类型 | 必填 | 说明 | 7430| -------- | -------------------------------------------- | ---- | ----------------------------------- | 7431| callback | AsyncCallback\<void> | 是 | 回调函数。当释放资源成功，err为undefined，否则为错误对象。 | 7432 7433**错误码：** 7434 7435以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7436 7437| 错误码ID | 错误信息 | 7438| -------- | ------------------------------------------ | 7439| 5400102 | Operation not allowed. Returned by callback. | 7440 7441**示例：** 7442 7443```ts 7444import { BusinessError } from '@kit.BasicServicesKit'; 7445 7446let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7447 7448//释放资源。 7449media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7450 if(generator != null){ 7451 avImageGenerator = generator; 7452 console.info(`Succeeded in creating AVImageGenerator`); 7453 avImageGenerator.release((error: BusinessError) => { 7454 if (error) { 7455 console.error(`Failed to release, err = ${JSON.stringify(error)}`); 7456 return; 7457 } 7458 console.info(`Succeeded in releasing`); 7459 }); 7460 } else { 7461 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7462 }; 7463}); 7464``` 7465 7466### release<sup>12+</sup> 7467 7468release(): Promise\<void> 7469 7470异步方式释放资源。通过Promise获取返回值。 7471 7472**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7473 7474**返回值：** 7475 7476| 类型 | 说明 | 7477| -------------- | ---------------------------------------- | 7478| Promise\<void> | 异步方式释放资源release方法的Promise返回值。 | 7479 7480**错误码：** 7481 7482以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7483 7484| 错误码ID | 错误信息 | 7485| -------- | ----------------------------------------- | 7486| 5400102 | Operation not allowed. Returned by promise. | 7487 7488**示例：** 7489 7490```ts 7491import { BusinessError } from '@kit.BasicServicesKit'; 7492 7493let avImageGenerator: media.AVImageGenerator | undefined = undefined; 7494 7495//释放资源。 7496media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => { 7497 if(generator != null){ 7498 avImageGenerator = generator; 7499 console.info(`Succeeded in creating AVImageGenerator`); 7500 avImageGenerator.release().then(() => { 7501 console.info(`Succeeded in releasing.`); 7502 }).catch((error: BusinessError) => { 7503 console.error(`Failed to release, error message:${error.message}`); 7504 }); 7505 } else { 7506 console.error(`Failed to creat AVImageGenerator, error message:${err.message}`); 7507 }; 7508}); 7509``` 7510 7511## AVImageQueryOptions<sup>12+</sup> 7512 7513需要获取的缩略图时间点与视频帧的对应关系。 7514 7515在获取视频缩略图时，传入的时间点与实际取得的视频帧所在时间点不一定相等，需要指定传入的时间点与实际取得的视频帧的时间关系。 7516 7517**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7518 7519| 名称 | 值 | 说明 | 7520| ------------------------ | --------------- | ------------------------------------------------------------ | 7521| AV_IMAGE_QUERY_NEXT_SYNC | 0 | 表示选取传入时间点或之后的关键帧。 | 7522| AV_IMAGE_QUERY_PREVIOUS_SYNC | 1 | 表示选取传入时间点或之前的关键帧。 | 7523| AV_IMAGE_QUERY_CLOSEST_SYNC | 2 | 表示选取离传入时间点最近的关键帧。 | 7524| AV_IMAGE_QUERY_CLOSEST | 3 | 表示选取离传入时间点最近的帧，该帧不一定是关键帧。 | 7525 7526## PixelMapParams<sup>12+</sup> 7527 7528获取视频缩略图时，输出缩略图的格式参数。 7529 7530**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 7531 7532| 名称 | 类型 | 可读 | 可写 | 说明 | 7533|--------|--------|------|------|---------------------------------------------------------------------------------| 7534| width | number | 是 | 是 | 输出的缩略图宽度。应保证大于0且不大于原始视频宽度。否则返回的缩略图不会进行缩放。 | 7535| height | number | 是 | 是 | 输出的缩略图高度。应保证大于0且不大于原始视频高度。否则返回的缩略图不会进行缩放。 | 7536 7537## media.createMediaSourceWithUrl<sup>12+</sup> 7538 7539createMediaSourceWithUrl(url: string, headers?: Record\<string, string>): MediaSource 7540 7541创建流媒体预下载媒体来源实例方法。 7542 7543**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 7544 7545**系统能力：** SystemCapability.Multimedia.Media.Core 7546 7547**参数：** 7548 7549| 参数名 | 类型 | 必填 | 说明 | 7550| -------- | -------- | ---- | -------------------- | 7551| url | string | 是 | - 流媒体预下载媒体来源url，支持的流媒体格式：HLS、HTTP-FLV、Dash、Https。<br> - 本地m3u8的fd路径。 | 7552| headers | Record\<string, string> | 否 | 支持流媒体预下载HttpHeader自定义。 | 7553 7554**返回值：** 7555 7556| 类型 | 说明 | 7557| -------------- | ------------------------------------------ | 7558| [MediaSource](#mediasource12) | MediaSource返回值。 | 7559 7560**错误码：** 7561 7562以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 7563 7564| 错误码ID | 错误信息 | 7565| -------- | ----------------------------------------- | 7566| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 7567| 5400101 | No memory. | 7568 7569**示例1：** 7570 7571```ts 7572let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 7573let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx", headers); 7574``` 7575 7576**示例2：** 7577 7578<!--code_no_check--> 7579```ts 7580import { common } from '@kit.AbilityKit'; 7581import { resourceManager } from '@kit.LocalizationKit'; 7582 7583let context = getContext(this) as common.UIAbilityContext; 7584let mgr = context.resourceManager; 7585let fileDescriptor = await mgr.getRawFd("xxx.m3u8"); 7586 7587let fd:string = fileDescriptor.fd.toString(); 7588let offset:string = fileDescriptor.offset.toString(); 7589let length:string = fileDescriptor.length.toString(); 7590let fdUrl:string = "fd://" + fd + "?offset=" + offset + "&size=" + length; 7591 7592let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"}; 7593let mediaSource : media.MediaSource = media.createMediaSourceWithUrl(fdUrl, headers); 7594 7595let mimeType : media.AVMimeTypes = media.AVMimeTypes.APPLICATION_M3U8; 7596mediaSource.setMimeType(mimeType); 7597 7598``` 7599 7600## MediaSource<sup>12+</sup> 7601 7602媒体数据信息。来源自[createMediaSourceWithUrl](#mediacreatemediasourcewithurl12)。 7603 7604**系统能力：** SystemCapability.Multimedia.Media.Core 7605 7606### setMimeType<sup>12+</sup> 7607 7608setMimeType(mimeType: AVMimeTypes): void 7609 7610设置媒体MIME类型，以帮助播放器处理扩展的媒体源。 7611 7612**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7613 7614**系统能力：** SystemCapability.Multimedia.Media.Core 7615 7616**参数：** 7617 7618| 参数名 | 类型 | 必填 | 说明 | 7619| -------- | -------- | ---- | -------------------- | 7620| mimeType | [AVMimeTypes](#mediasource12) | 是 | 媒体MIME类型。 | 7621 7622## AVMimeTypes<sup>12+</sup> 7623 7624媒体MIME类型，通过[setMimeType](#setmimetype12)设置。 7625 7626**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 7627 7628**系统能力：** SystemCapability.Multimedia.Media.Core 7629 7630 7631| 名称 | 值 | 说明 | 7632| ---------- | ---- | ------------------------------------------------------------ | 7633| APPLICATION_M3U8 | application/m3u8 | 表示m3u8本地文件。 | 7634 7635 7636## PlaybackStrategy<sup>12+</sup> 7637 7638播放策略。 7639 7640**系统能力：** SystemCapability.Multimedia.Media.Core 7641 7642| 名称 | 类型 | 必填 | 说明 | 7643| -------- | -------- | ---- | -------------------- | 7644| preferredWidth| number | 否 | 播放策略首选宽度，int类型，如1080。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 7645| preferredHeight | number | 否 | 播放策略首选高度，int类型，如1920。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 7646| preferredBufferDuration | number | 否 | 播放策略首选缓冲持续时间，单位s，取值范围1-20。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 7647| preferredHdr | boolean | 否 | 播放策略true是hdr，false非hdr，默认非hdr。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 7648| mutedMediaType | [MediaType](#mediatype8) | 否 | 静音播放的媒体类型，仅支持设置 MediaType.MEDIA_TYPE_AUD。 | 7649| preferredAudioLanguage<sup>13+</sup> | string | 否 | 播放策略首选音轨语言。dash场景下应用可按需设置。非dash场景暂不支持，建议缺省。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 7650| preferredSubtitleLanguage<sup>13+</sup> | string | 否 | 播放策略首选字幕语言。dash场景下应用可按需设置。非dash场景暂不支持，建议缺省。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 | 7651 7652## AVScreenCaptureRecordPreset<sup>12+</sup> 7653 7654进行屏幕录制时的编码、封装格式参数的枚举。 7655 7656**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7657 7658| 名称 | 值 | 说明 | 7659| --------------------------------- | ---- | -------------------------------------------- | 7660| SCREEN_RECORD_PRESET_H264_AAC_MP4 | 0 | 使用视频H264编码，音频AAC编码，MP4封装格式。 | 7661| SCREEN_RECORD_PRESET_H265_AAC_MP4 | 1 | 使用视频H265编码，音频AAC编码，MP4封装格式。 | 7662 7663## AVScreenCaptureStateCode<sup>12+</sup> 7664 7665屏幕录制的状态回调。 7666 7667**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7668 7669| 名称 | 值 | 说明 | 7670| ---------------------------------------- | ---- | ------------------------ | 7671| SCREENCAPTURE_STATE_STARTED | 0 | 录屏已开始。 | 7672| SCREENCAPTURE_STATE_CANCELED | 1 | 录屏被取消。 | 7673| SCREENCAPTURE_STATE_STOPPED_BY_USER | 2 | 录屏被用户手动停止。 | 7674| SCREENCAPTURE_STATE_INTERRUPTED_BY_OTHER | 3 | 录屏被其他录屏打断。 | 7675| SCREENCAPTURE_STATE_STOPPED_BY_CALL | 4 | 录屏被来电打断。 | 7676| SCREENCAPTURE_STATE_MIC_UNAVAILABLE | 5 | 录屏无法使用麦克风收音。 | 7677| SCREENCAPTURE_STATE_MIC_MUTED_BY_USER | 6 | 麦克风被用户关闭。 | 7678| SCREENCAPTURE_STATE_MIC_UNMUTED_BY_USER | 7 | 麦克风被用户打开。 | 7679| SCREENCAPTURE_STATE_ENTER_PRIVATE_SCENE | 8 | 录屏进入隐私页面。 | 7680| SCREENCAPTURE_STATE_EXIT_PRIVATE_SCENE | 9 | 录屏退出隐私页面。 | 7681| SCREENCAPTURE_STATE_STOPPED_BY_USER_SWITCHES | 10 | 系统用户切换，录屏中断。 | 7682 7683## AVScreenCaptureRecordConfig<sup>12+</sup> 7684 7685表示录屏参数配置。 7686 7687**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7688 7689| 名称 | 类型 | 必填 | 说明 | 7690| ----------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 7691| fd | number | 是 | 录制输出的文件fd。 | 7692| frameWidth | number | 否 | 录屏的视频宽度，默认屏幕宽度，根据不同屏幕默认值不同，单位px。 | 7693| frameHeight | number | 否 | 录屏的视频高度，默认屏幕高度，根据不同屏幕默认值不同，单位px。 | 7694| videoBitrate | number | 否 | 录屏的视频比特率，默认10000000。 | 7695| audioSampleRate | number | 否 | 录屏的音频采样率，内录的系统音和外录的麦克风都是用此采样率，默认48000，仅支持设置48000或16000。 | 7696| audioChannelCount | number | 否 | 录屏的音频通道数，内录的系统音和外录的麦克风都是用此通道数，默认2声道，仅支持设置1或2声道。 | 7697| audioBitrate | number | 否 | 录屏的音频比特率，内录的系统音和外录的麦克风都是用此比特率，默认96000。 | 7698| preset | [AVScreenCaptureRecordPreset](#avscreencapturerecordpreset12) | 否 | 录屏使用的编码和封装格式，默认SCREEN_RECORD_PRESET_H264_AAC_MP4格式。 | 7699| displayId<sup>15+</sup> | number | 否 | 指定录屏使用的屏幕，默认主屏幕。 | 7700 7701## AVScreenCaptureRecorder<sup>12+</sup> 7702 7703屏幕录制管理类，用于进行屏幕录制。在调用AVScreenCaptureRecorder的方法前，需要先通过[createAVScreenCaptureRecorder()](#mediacreateavscreencapturerecorder12)创建一个AVScreenCaptureRecorder实例。 7704 7705### init<sup>12+</sup> 7706 7707init(config: AVScreenCaptureRecordConfig): Promise\<void> 7708 7709异步方式进行录屏初始化，设置录屏参数。通过Promise获取返回值。 7710 7711**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7712 7713**参数：** 7714 7715| 参数名 | 类型 | 必填 | 说明 | 7716| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 7717| config | [AVScreenCaptureRecordConfig](#avscreencapturerecordconfig12) | 是 | 配置屏幕录制的相关参数。 | 7718 7719**返回值：** 7720 7721| 类型 | 说明 | 7722| -------------- | ----------------------------------- | 7723| Promise\<void> | 异步录屏初始化方法的Promise返回值。 | 7724 7725**错误码：** 7726 7727| 错误码ID | 错误信息 | 7728| -------- | ---------------------------------------------- | 7729| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 7730| 5400103 | IO error. Return by promise. | 7731| 5400105 | Service died. Return by promise. | 7732 7733**示例：** 7734 7735```ts 7736import { BusinessError } from '@kit.BasicServicesKit'; 7737 7738let avCaptureConfig: media.AVScreenCaptureRecordConfig = { 7739 fd: 0, // 文件需要先有调用者创建，赋予写权限，将文件fd传给此参数。 7740 frameWidth: 640, 7741 frameHeight: 480 7742 // 补充其他参数。 7743} 7744 7745avScreenCaptureRecorder.init(avCaptureConfig).then(() => { 7746 console.info('Succeeded in initing avScreenCaptureRecorder'); 7747}).catch((err: BusinessError) => { 7748 console.info('Failed to init avScreenCaptureRecorder, error: ' + err.message); 7749}) 7750``` 7751 7752### startRecording<sup>12+</sup> 7753 7754startRecording(): Promise\<void> 7755 7756异步方式开始录屏。通过Promise获取返回值。 7757 7758**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7759 7760**返回值：** 7761 7762| 类型 | 说明 | 7763| -------------- | -------------------------------- | 7764| Promise\<void> | 异步开始录屏方法的Promise返回值. | 7765 7766**错误码：** 7767 7768| 错误码ID | 错误信息 | 7769| -------- | -------------------------------- | 7770| 5400103 | IO error. Return by promise. | 7771| 5400105 | Service died. Return by promise. | 7772 7773**示例：** 7774 7775```ts 7776import { BusinessError } from '@kit.BasicServicesKit'; 7777 7778avScreenCaptureRecorder.startRecording().then(() => { 7779 console.info('Succeeded in starting avScreenCaptureRecorder'); 7780}).catch((err: BusinessError) => { 7781 console.info('Failed to start avScreenCaptureRecorder, error: ' + err.message); 7782}) 7783``` 7784 7785### stopRecording<sup>12+</sup> 7786 7787stopRecording(): Promise\<void> 7788 7789异步方式结束录屏。通过Promise获取返回值。 7790 7791**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7792 7793**返回值：** 7794 7795| 类型 | 说明 | 7796| -------------- | --------------------------------- | 7797| Promise\<void> | 异步结束录屏方法的Promise返回值。 | 7798 7799**错误码：** 7800 7801| 错误码ID | 错误信息 | 7802| -------- | -------------------------------- | 7803| 5400103 | IO error. Return by promise. | 7804| 5400105 | Service died. Return by promise. | 7805 7806**示例：** 7807 7808```ts 7809import { BusinessError } from '@kit.BasicServicesKit'; 7810 7811avScreenCaptureRecorder.stopRecording().then(() => { 7812 console.info('Succeeded in stopping avScreenCaptureRecorder'); 7813}).catch((err: BusinessError) => { 7814 console.info('Failed to stop avScreenCaptureRecorder, error: ' + err.message); 7815}) 7816``` 7817 7818### skipPrivacyMode<sup>12+</sup> 7819 7820skipPrivacyMode(windowIDs: Array\<number>): Promise\<void> 7821 7822录屏时，应用可对本应用的隐私窗口做安全豁免。通过Promise获取返回值。 7823如录屏时，用户在本应用进行输入密码等操作，应用不会进行黑屏处理。 7824 7825**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7826 7827**参数：** 7828 7829| 参数名 | 类型 | 必填 | 说明 | 7830| ------ | ------- | ---- | --------------------------------------------------------- | 7831| windowIDs | Array\<number> | 是 | 需要豁免隐私的窗口列表，包括主窗口id和子窗口id，窗口属性获取方法可以参考[窗口API引用](../apis-arkui/js-apis-window.md#getwindowproperties9)。 | 7832 7833**返回值：** 7834 7835| 类型 | 说明 | 7836| -------------- | -------------------------------- | 7837| Promise\<void> | 豁免隐私窗口的Promise返回值. | 7838 7839**错误码：** 7840 7841| 错误码ID | 错误信息 | 7842| -------- | -------------------------------- | 7843| 5400103 | IO error. Return by promise. | 7844| 5400105 | Service died. Return by promise. | 7845 7846**示例：** 7847 7848```ts 7849import { BusinessError } from '@kit.BasicServicesKit'; 7850 7851let windowIDs = []; 7852avScreenCaptureRecorder.skipPrivacyMode(windowIDs).then(() => { 7853 console.info('Succeeded in skipping privacy mode'); 7854}).catch((err: BusinessError) => { 7855 console.info('Failed to skip privacy mode, error: ' + err.message); 7856}) 7857``` 7858 7859### setMicEnabled<sup>12+</sup> 7860 7861setMicEnabled(enable: boolean): Promise\<void> 7862 7863异步方式设置麦克风开关。通过Promise获取返回值。 7864 7865**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7866 7867**参数：** 7868 7869| 参数名 | 类型 | 必填 | 说明 | 7870| ------ | ------- | ---- | --------------------------------------------------------- | 7871| enable | boolean | 是 | 麦克风开关控制，true代表麦克风打开，false代表麦克风关闭。 | 7872 7873**返回值：** 7874 7875| 类型 | 说明 | 7876| -------------- | --------------------------------------- | 7877| Promise\<void> | 异步设置麦克风开关方法的Promise返回值。 | 7878 7879**错误码：** 7880 7881| 错误码ID | 错误信息 | 7882| -------- | -------------------------------- | 7883| 5400103 | IO error. Return by promise. | 7884| 5400105 | Service died. Return by promise. | 7885 7886**示例：** 7887 7888```ts 7889import { BusinessError } from '@kit.BasicServicesKit'; 7890 7891avScreenCaptureRecorder.setMicEnabled(true).then(() => { 7892 console.info('Succeeded in setMicEnabled avScreenCaptureRecorder'); 7893}).catch((err: BusinessError) => { 7894 console.info('Failed to setMicEnabled avScreenCaptureRecorder, error: ' + err.message); 7895}) 7896``` 7897 7898### release<sup>12+</sup> 7899 7900release(): Promise\<void> 7901 7902异步方式释放录屏。通过Promise获取返回值。 7903 7904**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7905 7906**返回值：** 7907 7908| 类型 | 说明 | 7909| -------------- | --------------------------------- | 7910| Promise\<void> | 异步释放录屏方法的Promise返回值。 | 7911 7912**错误码：** 7913 7914| 错误码ID | 错误信息 | 7915| -------- | -------------------------------- | 7916| 5400103 | IO error. Return by promise. | 7917| 5400105 | Service died. Return by promise. | 7918 7919**示例：** 7920 7921```ts 7922import { BusinessError } from '@kit.BasicServicesKit'; 7923 7924avScreenCaptureRecorder.release().then(() => { 7925 console.info('Succeeded in releasing avScreenCaptureRecorder'); 7926}).catch((err: BusinessError) => { 7927 console.info('Faile to release avScreenCaptureRecorder, error: ' + err.message); 7928}) 7929``` 7930 7931### on('stateChange')<sup>12+</sup> 7932 7933on(type: 'stateChange', callback: Callback\<AVScreenCaptureStateCode>): void 7934 7935订阅录屏状态切换的事件，当状态发生的时候，会通过订阅的回调通知用户。用户只能订阅一个状态切换的回调方法，重复订阅时，以最后一次订阅的回调接口为准。 7936 7937**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7938 7939**参数：** 7940 7941| 参数名 | 类型 | 必填 | 说明 | 7942| -------- | -------- | ---- | ------------------------------------------------------------ | 7943| type | string | 是 | 状态切换事件回调类型，支持的事件：'stateChange'。 | 7944| callback | function | 是 | 状态切换事件回调方法，[AVScreenCaptureStateCode](#avscreencapturestatecode12)表示切换到的状态。 | 7945 7946**示例：** 7947 7948```ts 7949avScreenCaptureRecorder.on('stateChange', (state: media.AVScreenCaptureStateCode) => { 7950 console.info('avScreenCaptureRecorder stateChange to ' + state); 7951}) 7952``` 7953 7954### on('error')<sup>12+</sup> 7955 7956on(type: 'error', callback: ErrorCallback): void 7957 7958订阅AVScreenCaptureRecorder的错误事件，用户可以根据应用自身逻辑对错误事件进行处理。用户只能订阅一个错误事件的回调方法，重复订阅时，以最后一次订阅的回调接口为准。 7959 7960**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7961 7962**参数：** 7963 7964| 参数名 | 类型 | 必填 | 说明 | 7965| -------- | ------------- | ---- | --------------------------------------- | 7966| type | string | 是 | 错误事件回调类型，支持的事件：'error'。 | 7967| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录屏错误事件回调方法。 | 7968 7969**错误码：** 7970 7971| 错误码ID | 错误信息 | 7972| -------- | -------------------------------- | 7973| 201 | permission denied. | 7974| 5400103 | IO error. Return by ErrorCallback. | 7975| 5400105 | Service died. Return by ErrorCallback. | 7976 7977**示例：** 7978 7979```ts 7980avScreenCaptureRecorder.on('error', (err: BusinessError) => { 7981 console.error('avScreenCaptureRecorder error:' + err.message); 7982}) 7983``` 7984 7985### off('stateChange')<sup>12+</sup> 7986 7987 off(type: 'stateChange', callback?: Callback\<AVScreenCaptureStateCode>): void 7988 7989取消订阅状态切换回调事件。用户可以指定填入状态切换的回调方法来取消订阅。 7990 7991**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 7992 7993**参数：** 7994 7995| 参数名 | 类型 | 必填 | 说明 | 7996| -------- | -------- | ---- | ------------------------------------------------------------ | 7997| type | string | 是 | 状态切换事件回调类型，支持的事件：'stateChange'。 | 7998| callback | function | 否 | 状态切换事件回调方法，[AVScreenCaptureStateCode](#avscreencapturestatecode12)表示切换到的状态，不填此参数则会取消最后一次订阅事件。 | 7999 8000**示例：** 8001 8002```ts 8003avScreenCaptureRecorder.off('stateChange'); 8004``` 8005 8006### off('error')<sup>12+</sup> 8007 8008off(type: 'error', callback?: ErrorCallback): void 8009 8010取消订阅错误回调事件。用户可以指定填入错误回调方法来取消订阅。 8011 8012**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 8013 8014**参数：** 8015 8016| 参数名 | 类型 | 必填 | 说明 | 8017| -------- | -------- | ---- | ---------------------------------------------------------- | 8018| type | string | 是 | 状态切换事件回调类型，支持的事件：'error'。 | 8019| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否 | 录屏错误事件回调方法，不填此参数则会取消最后一次订阅事件。 | 8020 8021**示例：** 8022 8023```ts 8024avScreenCaptureRecorder.off('error'); 8025```
