1# 媒体服务 2 3> **说明：** 4> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 5 6 7媒体子系统为开发者提供一套简单且易于理解的接口，使得开发者能够方便接入系统并使用系统的媒体资源。 8 9媒体子系统包含了音视频相关媒体业务，提供以下常用功能： 10 11- 音频播放（[AudioPlayer](#audioplayer)） 12- 视频播放（[VideoPlayer](#videoplayer8)） 13- 音频录制（[AudioRecorder](#audiorecorder)） 14 15后续将提供以下功能：DataSource音视频播放、音视频编解码、容器封装解封装、媒体能力查询等功能。 16 17## 导入模块 18 19```js 20import media from '@ohos.multimedia.media'; 21``` 22 23## media.createAudioPlayer 24 25createAudioPlayer(): [AudioPlayer](#audioplayer) 26 27同步方式创建音频播放实例。 28 29**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 30 31**返回值：** 32 33| 类型 | 说明 | 34| --------------------------- | ------------------------------------------------------------ | 35| [AudioPlayer](#audioplayer) | 返回AudioPlayer类实例，失败时返回null。可用于音频播放、暂停、停止等操作。 | 36 37**示例：** 38 39```js 40let audioPlayer = media.createAudioPlayer(); 41``` 42 43## media.createVideoPlayer<sup>8+</sup> 44 45createVideoPlayer(callback: AsyncCallback\<[VideoPlayer](#videoplayer8)>): void 46 47异步方式创建视频播放实例，通过注册回调函数获取返回值。 48 49**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 50 51**参数：** 52 53| 参数名 | 类型 | 必填 | 说明 | 54| -------- | ------------------------------------------- | ---- | ------------------------------ | 55| callback | AsyncCallback<[VideoPlayer](#videoplayer8)> | 是 | 异步创建视频播放实例回调方法。 | 56 57**示例：** 58 59```js 60let videoPlayer 61 62media.createVideoPlayer((error, video) => { 63 if (video != null) { 64 videoPlayer = video; 65 console.info('video createVideoPlayer success'); 66 } else { 67 console.info(`video createVideoPlayer fail, error:${error.message}`); 68 } 69}); 70``` 71 72## media.createVideoPlayer<sup>8+</sup> 73 74createVideoPlayer(): Promise<[VideoPlayer](#videoplayer8)> 75 76异步方式创建视频播放实例，通过Promise获取返回值。 77 78**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 79 80**返回值：** 81 82| 类型 | 说明 | 83| ------------------------------------- | ----------------------------------- | 84| Promise<[VideoPlayer](#videoplayer8)> | 异步创建视频播放实例Promise返回值。 | 85 86**示例：** 87 88```js 89let videoPlayer 90 91media.createVideoPlayer().then((video) => { 92 if (video != null) { 93 videoPlayer = video; 94 console.info('video createVideoPlayer success'); 95 } else { 96 console.info('video createVideoPlayer fail'); 97 } 98}).catch((error) => { 99 console.info(`video catchCallback, error:${error.message}`); 100}); 101``` 102 103## media.createAudioRecorder 104 105createAudioRecorder(): AudioRecorder 106 107创建音频录制的实例来控制音频的录制。 108一台设备只允许创建一个录制实例。 109 110**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 111 112**返回值:** 113 114| 类型 | 说明 | 115| ------------------------------- | ----------------------------------------- | 116| [AudioRecorder](#audiorecorder) | 返回AudioRecorder类实例，失败时返回null。 | 117 118**示例：** 119 120```js 121let audioRecorder = media.createAudioRecorder(); 122``` 123 124 125 126 127## MediaErrorCode<sup>8+</sup> 128 129媒体服务错误类型枚举。 130 131**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。 132 133| 名称 | 值 | 说明 | 134| -------------------------- | ---- | -------------------------------------- | 135| MSERR_OK | 0 | 表示操作成功。 | 136| MSERR_NO_MEMORY | 1 | 表示申请内存失败，系统可能无可用内存。 | 137| MSERR_OPERATION_NOT_PERMIT | 2 | 表示无权限执行此操作。 | 138| MSERR_INVALID_VAL | 3 | 表示传入入参无效。 | 139| MSERR_IO | 4 | 表示发生IO错误。 | 140| MSERR_TIMEOUT | 5 | 表示操作超时。 | 141| MSERR_UNKNOWN | 6 | 表示未知错误。 | 142| MSERR_SERVICE_DIED | 7 | 表示服务端失效。 | 143| MSERR_INVALID_STATE | 8 | 表示在当前状态下，不允许执行此操作。 | 144| MSERR_UNSUPPORTED | 9 | 表示在当前版本下，不支持此操作。 | 145 146## MediaType<sup>8+</sup> 147 148媒体类型枚举。 149 150**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。 151 152| 名称 | 值 | 说明 | 153| -------------- | ---- | ---------- | 154| MEDIA_TYPE_AUD | 0 | 表示音频。 | 155| MEDIA_TYPE_VID | 1 | 表示视频。 | 156 157## CodecMimeType<sup>8+</sup> 158 159Codec MIME类型枚举。 160 161**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。 162 163| 名称 | 值 | 说明 | 164| ------------ | --------------------- | ------------------------ | 165| VIDEO_H263 | 'video/h263' | 表示视频/h263类型。 | 166| VIDEO_AVC | 'video/avc' | 表示视频/avc类型。 | 167| VIDEO_MPEG2 | 'video/mpeg2' | 表示视频/mpeg2类型。 | 168| VIDEO_MPEG4 | 'video/mp4v-es' | 表示视频/mpeg4类型。 | 169| VIDEO_VP8 | 'video/x-vnd.on2.vp8' | 表示视频/vp8类型。 | 170| AUDIO_AAC | "audio/mp4a-latm" | 表示音频/mp4a-latm类型。 | 171| AUDIO_VORBIS | 'audio/vorbis' | 表示音频/vorbis类型。 | 172| AUDIO_FLAC | 'audio/flac' | 表示音频/flac类型。 | 173 174## MediaDescriptionKey<sup>8+</sup> 175 176媒体信息描述枚举。 177 178**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。 179 180| 名称 | 值 | 说明 | 181| ------------------------ | --------------- | ------------------------------------------------------------ | 182| MD_KEY_TRACK_INDEX | "track_index" | 表示轨道序号，其对应键值类型为number。 | 183| MD_KEY_TRACK_TYPE | "track_type" | 表示轨道类型，其对应键值类型为number，参考[MediaType](#mediatype8)。 | 184| MD_KEY_CODEC_MIME | "codec_mime" | 表示codec_mime类型，其对应键值类型为string。 | 185| MD_KEY_DURATION | "duration" | 表示媒体时长，其对应键值类型为number，单位为毫秒（ms）。 | 186| MD_KEY_BITRATE | "bitrate" | 表示比特率，其对应键值类型为number，单位为比特率（bps）。 | 187| MD_KEY_WIDTH | "width" | 表示视频宽度，其对应键值类型为number，单位为像素（px）。 | 188| MD_KEY_HEIGHT | "height" | 表示视频高度，其对应键值类型为number，单位为像素（px）。 | 189| MD_KEY_FRAME_RATE | "frame_rate" | 表示视频帧率，其对应键值类型为number，单位为100帧每秒（100fps）。 | 190| MD_KEY_AUD_CHANNEL_COUNT | "channel_count" | 表示声道数，其对应键值类型为number。 | 191| MD_KEY_AUD_SAMPLE_RATE | "sample_rate" | 表示采样率，其对应键值类型为number，单位为赫兹（Hz）。 | 192 193## BufferingInfoType<sup>8+</sup> 194 195缓存事件类型枚举。 196 197**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。 198 199| 名称 | 值 | 说明 | 200| ----------------- | ---- | -------------------------------- | 201| BUFFERING_START | 1 | 表示开始缓存。 | 202| BUFFERING_END | 2 | 表示结束缓存。 | 203| BUFFERING_PERCENT | 3 | 表示缓存百分比。 | 204| CACHED_DURATION | 4 | 表示缓存时长，单位为毫秒（ms）。 | 205 206## AudioPlayer 207 208音频播放管理类，用于管理和播放音频媒体。在调用AudioPlayer的方法前，需要先通过[createAudioPlayer()](#mediacreateaudioplayer)构建一个[AudioPlayer](#audioplayer)实例。 209 210音频播放demo可参考：[音频播放开发指导](../../media/audio-playback.md) 211 212### 属性<a name=audioplayer_属性></a> 213 214**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.AudioPlayer。 215 216| 名称 | 类型 | 可读 | 可写 | 说明 | 217| ----------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ | 218| src | string | 是 | 是 | 音频媒体URI，支持当前主流的视频格式(mp4、mpeg-ts、webm、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/>**注意事项**：<br>使用媒体素材需要获取读权限，否则无法正常播放。| 219| loop | boolean | 是 | 是 | 音频循环播放属性，设置为'true'表示循环播放。 | 220| currentTime | number | 是 | 否 | 音频的当前播放位置。 | 221| duration | number | 是 | 否 | 音频时长。 | 222| state | [AudioState](#audiostate) | 是 | 否 | 音频播放的状态。 | 223 224### play<a name=audioplayer_play></a> 225 226play(): void 227 228开始播放音频资源，需在[dataLoad](#audioplayer_on)事件成功触发后，才能调用。 229 230**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 231 232**示例：** 233 234```js 235audioPlayer.on('play', () => { //设置'play'事件回调 236 console.log('audio play success'); 237}); 238audioPlayer.play(); 239``` 240 241### pause<a name=audioplayer_pause></a> 242 243pause(): void 244 245暂停播放音频资源。 246 247**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 248 249**示例：** 250 251```js 252audioPlayer.on('pause', () => { //设置'pause'事件回调 253 console.log('audio pause success'); 254}); 255audioPlayer.pause(); 256``` 257 258### stop<a name=audioplayer_stop></a> 259 260stop(): void 261 262停止播放音频资源。 263 264**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 265 266**示例：** 267 268```js 269audioPlayer.on('stop', () => { //设置'stop'事件回调 270 console.log('audio stop success'); 271}); 272audioPlayer.stop(); 273``` 274 275### reset<sup>7+</sup><a name=audioplayer_reset></a> 276 277reset(): void 278 279切换播放音频资源。 280 281**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 282 283**示例：** 284 285```js 286audioPlayer.on('reset', () => { //设置'reset'事件回调 287 console.log('audio reset success'); 288}); 289audioPlayer.reset(); 290``` 291 292### seek<a name=audioplayer_seek></a> 293 294seek(timeMs: number): void 295 296跳转到指定播放位置。 297 298**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 299 300**参数：** 301 302| 参数名 | 类型 | 必填 | 说明 | 303| ------ | ------ | ---- | ------------------------------------ | 304| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms）。 | 305 306**示例：** 307 308```js 309audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调 310 if (seekDoneTime == null) { 311 console.info('audio seek fail'); 312 return; 313 } 314 console.log('audio seek success. seekDoneTime: ' + seekDoneTime); 315}); 316audioPlayer.seek(30000); //seek到30000ms的位置 317``` 318 319### setVolume<a name=audioplayer_setvolume></a> 320 321setVolume(vol: number): void 322 323设置音量。 324 325**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| ------ | ------ | ---- | ------------------------------------------------------------ | 331| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 332 333**示例：** 334 335```js 336audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调 337 console.log('audio volumeChange success'); 338}); 339audioPlayer.setVolume(1); //设置音量到100% 340``` 341 342### release<a name=audioplayer_release></a> 343 344release(): void 345 346释放音频资源。 347 348**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 349 350**示例：** 351 352```js 353audioPlayer.release(); 354audioPlayer = undefined; 355``` 356 357### getTrackDescription<sup>8+</sup><a name=audioplayer_gettrackdescription1></a> 358 359getTrackDescription(callback: AsyncCallback<Array\<MediaDescription>>): void 360 361通过回调方式获取音频轨道信息。需在[dataLoad](#audioplayer_on)事件成功触发后，才能调用。 362 363**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 364 365**参数：** 366 367| 参数名 | 类型 | 必填 | 说明 | 368| -------- | ------------------------------------------------------------ | ---- | -------------------------- | 369| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是 | 获取音频轨道信息回调方法。 | 370 371**示例：** 372 373```js 374function printfDescription(obj) { 375 for (let item in obj) { 376 let property = obj[item]; 377 console.info('audio key is ' + item); 378 console.info('audio value is ' + property); 379 } 380} 381 382audioPlayer.getTrackDescription((error, arrlist) => { 383 if (arrlist != null) { 384 for (let i = 0; i < arrlist.length; i++) { 385 printfDescription(arrlist[i]); 386 } 387 } else { 388 console.log(`audio getTrackDescription fail, error:${error.message}`); 389 } 390}); 391``` 392 393### getTrackDescription<sup>8+</sup><a name=audioplayer_gettrackdescription2></a> 394 395getTrackDescription(): Promise<Array\<MediaDescription>> 396 397通过Promise方式获取音频轨道信息。需在[dataLoad](#audioplayer_on)事件成功触发后，才能调用 398 399**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 400 401**返回值：** 402 403| 类型 | 说明 | 404| ------------------------------------------------------ | ------------------------------- | 405| Promise<Array<[MediaDescription](#mediadescription8)>> | 获取音频轨道信息Promise返回值。 | 406 407**示例：** 408 409```js 410function printfDescription(obj) { 411 for (let item in obj) { 412 let property = obj[item]; 413 console.info('audio key is ' + item); 414 console.info('audio value is ' + property); 415 } 416} 417 418audioPlayer.getTrackDescription().then((arrlist) => { 419 if (arrlist != null) { 420 arrayDescription = arrlist; 421 } else { 422 console.log('audio getTrackDescription fail'); 423 } 424}).catch((error) => { 425 console.info(`audio catchCallback, error:${error.message}`); 426}); 427 428for (let i = 0; i < arrayDescription.length; i++) { 429 printfDescription(arrayDescription[i]); 430} 431``` 432 433### on('bufferingUpdate')<sup>8+</sup> 434 435on(type: 'bufferingUpdate', callback: (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void): void 436 437开始订阅音频缓存更新事件。 438 439**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 440 441**参数：** 442 443| 参数名 | 类型 | 必填 | 说明 | 444| -------- | -------- | ---- | ------------------------------------------------------------ | 445| type | string | 是 | 音频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 446| callback | function | 是 | 音频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时，value值有效，否则固定为0。 | 447 448**示例：** 449 450```js 451audioPlayer.on('bufferingUpdate', (infoType, value) => { 452 console.log('audio bufferingInfo type: ' + infoType); 453 console.log('audio bufferingInfo value: ' + value); 454}); 455``` 456 457 ### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')<a name = audioplayer_on></a> 458 459on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void): void 460 461开始订阅音频播放事件。 462 463**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 464 465**参数：** 466 467| 参数名 | 类型 | 必填 | 说明 | 468| -------- | ---------- | ---- | ------------------------------------------------------------ | 469| type | string | 是 | 播放事件回调类型，支持的事件包括：'play' \| 'pause' \| 'stop' \| 'reset' \| 'dataLoad' \| 'finish' \| 'volumeChange'。<br>- 'play'：完成[play()](#audioplayer_play)调用，音频开始播放，触发该事件。<br>- 'pause'：完成[pause()](#audioplayer_pause)调用，音频暂停播放，触发该事件。<br>- 'stop'：完成[stop()](#audioplayer_stop)调用，音频停止播放，触发该事件。<br>- 'reset'：完成[reset()](#audioplayer_reset)调用，播放器重置，触发该事件。<br>- 'dataLoad'：完成音频数据加载后触发该事件，即src属性设置完成后触发该事件。<br>- 'finish'：完成音频播放后触发该事件。<br>- 'volumeChange'：完成[setVolume()](#audioplayer_setvolume)调用，播放音量改变后触发该事件。 | 470| callback | () => void | 是 | 播放事件回调方法。 | 471 472**示例：** 473 474```js 475let audioPlayer = media.createAudioPlayer(); //创建一个音频播放实例 476audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调，src属性设置成功后，触发此回调 477 console.info('audio set source success'); 478 audioPlayer.play(); //开始播放，并触发'play'事件回调 479}); 480audioPlayer.on('play', () => { //设置'play'事件回调 481 console.info('audio play success'); 482 audioPlayer.seek(30000); //调用seek方法，并触发'timeUpdate'事件回调 483}); 484audioPlayer.on('pause', () => { //设置'pause'事件回调 485 console.info('audio pause success'); 486 audioPlayer.stop(); //停止播放，并触发'stop'事件回调 487}); 488audioPlayer.on('reset', () => { //设置'reset'事件回调 489 console.info('audio reset success'); 490 audioPlayer.release(); //释放播放实例资源 491 audioPlayer = undefined; 492}); 493audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调 494 if (seekDoneTime == null) { 495 console.info('audio seek fail'); 496 return; 497 } 498 console.info('audio seek success, and seek time is ' + seekDoneTime); 499 audioPlayer.setVolume(0.5); //设置音量为50%，并触发'volumeChange'事件回调 500}); 501audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调 502 console.info('audio volumeChange success'); 503 audioPlayer.pause(); //暂停播放，并触发'pause'事件回调 504}); 505audioPlayer.on('finish', () => { //设置'finish'事件回调 506 console.info('audio play finish'); 507 audioPlayer.stop(); //停止播放，并触发'stop'事件回调 508}); 509audioPlayer.on('error', (error) => { //设置'error'事件回调 510 console.info(`audio error called, errName is ${error.name}`); 511 console.info(`audio error called, errCode is ${error.code}`); 512 console.info(`audio error called, errMessage is ${error.message}`); 513}); 514 515// 用户选择音频设置fd(本地播放) 516let fdPath = 'fd://' 517// path路径的码流可通过"hdc file send D:\xxx\01.mp3 /data/accounts/account_0/appdata" 命令，将其推送到设备上 518let path = '/data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3'; 519fileIO.open(path).then(fdNumber) => { 520 fdPath = fdPath + '' + fdNumber; 521 console.info('open fd success fd is' + fdPath); 522}, (err) => { 523 console.info('open fd failed err is' + err); 524}).catch((err) => { 525 console.info('open fd failed err is' + err); 526}); 527audioPlayer.src = fdPath; //设置src属性，并触发'dataLoad'事件回调 528``` 529 530### on('timeUpdate') 531 532on(type: 'timeUpdate', callback: Callback\<number>): void 533 534开始订阅音频播放[seek()](#seek)时间更新事件。 535 536**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 537 538**参数：** 539 540| 参数名 | 类型 | 必填 | 说明 | 541| -------- | ----------------- | ---- | ------------------------------------------------------------ | 542| type | string | 是 | 播放事件回调类型，支持的事件包括：'timeUpdate'。<br>- 'timeUpdate'：[seek()](#audioplayer_seek)调用完成，触发该事件。 | 543| callback | Callback\<number> | 是 | 播放事件回调方法。回调方法入参为成功seek的时间。 | 544 545**示例：** 546 547```js 548audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调 549 if (seekDoneTime == null) { 550 console.info('audio seek fail'); 551 return; 552 } 553 console.log('audio seek success. seekDoneTime: ' + seekDoneTime); 554}); 555audioPlayer.seek(30000); //seek到30000ms的位置 556``` 557 558### on('error') 559 560on(type: 'error', callback: ErrorCallback): void 561 562开始订阅音频播放错误事件。 563 564**系统能力：** SystemCapability.Multimedia.Media.AudioPlayer 565 566**参数：** 567 568| 参数名 | 类型 | 必填 | 说明 | 569| -------- | ------------- | ---- | ------------------------------------------------------------ | 570| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：音频播放中发生错误，触发该事件。 | 571| callback | ErrorCallback | 是 | 播放错误事件回调方法。 | 572 573**示例：** 574 575```js 576audioPlayer.on('error', (error) => { //设置'error'事件回调 577 console.info(`audio error called, errName is ${error.name}`); //打印错误类型名称 578 console.info(`audio error called, errCode is ${error.code}`); //打印错误码 579 console.info(`audio error called, errMessage is ${error.message}`);//打印错误类型详细描述 580}); 581audioPlayer.setVolume(3); //设置volume为无效值，触发'error'事件 582``` 583 584## AudioState 585 586音频播放的状态机。可通过state属性获取当前状态。 587 588**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.AudioPlayer。 589 590| 名称 | 类型 | 描述 | 591| ------------------ | ------ | -------------- | 592| idle | string | 音频播放空闲。 | 593| playing | string | 音频正在播放。 | 594| paused | string | 音频暂停播放。 | 595| stopped | string | 音频播放停止。 | 596| error<sup>8+</sup> | string | 错误状态。 | 597 598## VideoPlayer<sup>8+</sup> 599 600视频播放管理类，用于管理和播放视频媒体。在调用VideoPlayer的方法前，需要先通过[createVideoPlayer()](#mediacreatevideoplayer8)构建一个[VideoPlayer](#videoplayer8)实例。 601 602视频播放demo可参考：[视频播放开发指导](../../media/video-playback.md) 603 604### 属性<a name=videoplayer_属性></a> 605 606**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoPlayer。 607 608| 名称 | 类型 | 可读 | 可写 | 说明 | 609| ------------------------ | ---------------------------------- | ---- | ---- | ------------------------------------------------------------ | 610| url<sup>8+</sup> | string | 是 | 是 | 视频媒体URL，支持当前主流的视频格式(mp4、mpeg-ts、webm、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/>**注意事项**：<br>使用媒体素材需要获取读权限，否则无法正常播放。 | 611| loop<sup>8+</sup> | boolean | 是 | 是 | 视频循环播放属性，设置为'true'表示循环播放。 | 612| currentTime<sup>8+</sup> | number | 是 | 否 | 视频的当前播放位置。 | 613| duration<sup>8+</sup> | number | 是 | 否 | 视频时长，返回-1表示直播模式。 | 614| state<sup>8+</sup> | [VideoPlayState](#videoplaystate8) | 是 | 否 | 视频播放的状态。 | 615| width<sup>8+</sup> | number | 是 | 否 | 视频宽。 | 616| height<sup>8+</sup> | number | 是 | 否 | 视频高。 | 617 618### setDisplaySurface<sup>8+</sup> 619 620setDisplaySurface(surfaceId: string, callback: AsyncCallback\<void>): void 621 622通过回调方式设置SurfaceId。 623 624**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 625 626**参数：** 627 628| 参数名 | 类型 | 必填 | 说明 | 629| --------- | -------- | ---- | ------------------------- | 630| surfaceId | string | 是 | SurfaceId | 631| callback | function | 是 | 设置SurfaceId的回调方法。 | 632 633**示例：** 634 635```js 636videoPlayer.setDisplaySurface(surfaceId, (err) => { 637 if (err == null) { 638 console.info('setDisplaySurface success!'); 639 } else { 640 console.info('setDisplaySurface fail!'); 641 } 642}); 643``` 644 645### setDisplaySurface<sup>8+</sup> 646 647setDisplaySurface(surfaceId: string): Promise\<void> 648 649通过Promise方式设置SurfaceId。 650 651**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 652 653**参数：** 654 655| 参数名 | 类型 | 必填 | 说明 | 656| --------- | ------ | ---- | --------- | 657| surfaceId | string | 是 | SurfaceId | 658 659**返回值：** 660 661| 类型 | 说明 | 662| -------------- | ------------------------------ | 663| Promise\<void> | 设置SurfaceId的Promise返回值。 | 664 665**示例：** 666 667```js 668videoPlayer.setDisplaySurface(surfaceId).then(() => { 669 console.info('setDisplaySurface success'); 670}).catch((error) => { 671 console.info(`video catchCallback, error:${error.message}`); 672}); 673``` 674 675### prepare<sup>8+</sup> 676 677prepare(callback: AsyncCallback\<void>): void 678 679通过回调方式准备播放视频。 680 681**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 682 683**参数：** 684 685| 参数名 | 类型 | 必填 | 说明 | 686| -------- | -------- | ---- | ------------------------ | 687| callback | function | 是 | 准备播放视频的回调方法。 | 688 689**示例：** 690 691```js 692videoPlayer.prepare((err) => { 693 if (err == null) { 694 console.info('prepare success!'); 695 } else { 696 console.info('prepare fail!'); 697 } 698}); 699``` 700 701### prepare<sup>8+</sup> 702 703prepare(): Promise\<void> 704 705通过Promise方式准备播放视频。 706 707**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 708 709**返回值：** 710 711| 类型 | 说明 | 712| -------------- | ----------------------------- | 713| Promise\<void> | 准备播放视频的Promise返回值。 | 714 715**示例：** 716 717```js 718videoPlayer.prepare().then(() => { 719 console.info('prepare success'); 720}).catch((error) => { 721 console.info(`video catchCallback, error:${error.message}`); 722}); 723``` 724 725### play<sup>8+</sup> 726 727play(callback: AsyncCallback\<void>): void; 728 729通过回调方式开始播放视频。 730 731**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 732 733**参数：** 734 735| 参数名 | 类型 | 必填 | 说明 | 736| -------- | -------- | ---- | ------------------------ | 737| callback | function | 是 | 开始播放视频的回调方法。 | 738 739**示例：** 740 741```js 742videoPlayer.play((err) => { 743 if (err == null) { 744 console.info('play success!'); 745 } else { 746 console.info('play fail!'); 747 } 748}); 749``` 750 751### play<sup>8+</sup> 752 753play(): Promise\<void>; 754 755通过Promise方式开始播放视频。 756 757**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 758 759**返回值：** 760 761| 类型 | 说明 | 762| -------------- | ----------------------------- | 763| Promise\<void> | 开始播放视频的Promise返回值。 | 764 765**示例：** 766 767```js 768videoPlayer.play().then(() => { 769 console.info('play success'); 770}).catch((error) => { 771 console.info(`video catchCallback, error:${error.message}`); 772}); 773``` 774 775### pause<sup>8+</sup> 776 777pause(callback: AsyncCallback\<void>): void 778 779通过回调方式暂停播放视频。 780 781**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 782 783**参数：** 784 785| 参数名 | 类型 | 必填 | 说明 | 786| -------- | -------- | ---- | ------------------------ | 787| callback | function | 是 | 暂停播放视频的回调方法。 | 788 789**示例：** 790 791```js 792videoPlayer.pause((err) => { 793 if (err == null) { 794 console.info('pause success!'); 795 } else { 796 console.info('pause fail!'); 797 } 798}); 799``` 800 801### pause<sup>8+</sup> 802 803pause(): Promise\<void> 804 805通过Promise方式暂停播放视频。 806 807**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 808 809**返回值：** 810 811| 类型 | 说明 | 812| -------------- | ----------------------------- | 813| Promise\<void> | 暂停播放视频的Promise返回值。 | 814 815**示例：** 816 817```js 818videoPlayer.pause().then(() => { 819 console.info('pause success'); 820}).catch((error) => { 821 console.info(`video catchCallback, error:${error.message}`); 822}); 823``` 824 825### stop<sup>8+</sup> 826 827stop(callback: AsyncCallback\<void>): void 828 829通过回调方式停止播放视频。 830 831**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 832 833**参数：** 834 835| 参数名 | 类型 | 必填 | 说明 | 836| -------- | -------- | ---- | ------------------------ | 837| callback | function | 是 | 停止播放视频的回调方法。 | 838 839**示例：** 840 841```js 842videoPlayer.stop((err) => { 843 if (err == null) { 844 console.info('stop success!'); 845 } else { 846 console.info('stop fail!'); 847 } 848}); 849``` 850 851### stop<sup>8+</sup> 852 853stop(): Promise\<void> 854 855通过Promise方式停止播放视频。 856 857**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 858 859**返回值：** 860 861| 类型 | 说明 | 862| -------------- | ----------------------------- | 863| Promise\<void> | 停止播放视频的Promise返回值。 | 864 865**示例：** 866 867```js 868videoPlayer.stop().then(() => { 869 console.info('stop success'); 870}).catch((error) => { 871 console.info(`video catchCallback, error:${error.message}`); 872}); 873``` 874 875### reset<sup>8+</sup> 876 877reset(callback: AsyncCallback\<void>): void 878 879通过回调方式切换播放视频。 880 881**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 882 883**参数：** 884 885| 参数名 | 类型 | 必填 | 说明 | 886| -------- | -------- | ---- | ------------------------ | 887| callback | function | 是 | 切换播放视频的回调方法。 | 888 889**示例：** 890 891```js 892videoPlayer.reset((err) => { 893 if (err == null) { 894 console.info('reset success!'); 895 } else { 896 console.info('reset fail!'); 897 } 898}); 899``` 900 901### reset<sup>8+</sup> 902 903reset(): Promise\<void> 904 905通过Promise方式切换播放视频。 906 907**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 908 909**返回值：** 910 911| 类型 | 说明 | 912| -------------- | ----------------------------- | 913| Promise\<void> | 切换播放视频的Promise返回值。 | 914 915**示例：** 916 917```js 918videoPlayer.reset().then(() => { 919 console.info('reset success'); 920}).catch((error) => { 921 console.info(`video catchCallback, error:${error.message}`); 922}); 923``` 924 925### seek<sup>8+</sup> 926 927seek(timeMs: number, callback: AsyncCallback\<number>): void 928 929通过回调方式跳转到指定播放位置，默认跳转到指定时间点的下一个关键帧。 930 931**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 932 933**参数：** 934 935| 参数名 | 类型 | 必填 | 说明 | 936| -------- | -------- | ---- | ------------------------------------ | 937| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms）。 | 938| callback | function | 是 | 跳转到指定播放位置的回调方法。 | 939 940**示例：** 941 942```js 943videoPlayer.seek((seekTime, err) => { 944 if (err == null) { 945 console.info('seek success!'); 946 } else { 947 console.info('seek fail!'); 948 } 949}); 950``` 951 952### seek<sup>8+</sup> 953 954seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\<number>): void 955 956通过回调方式跳转到指定播放位置。 957 958**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 959 960**参数：** 961 962| 参数名 | 类型 | 必填 | 说明 | 963| -------- | ---------------------- | ---- | ------------------------------------ | 964| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms）。 | 965| mode | [SeekMode](#seekmode8) | 是 | 跳转模式。 | 966| callback | function | 是 | 跳转到指定播放位置的回调方法。 | 967 968**示例：** 969 970```js 971videoPlayer.seek((seekTime, seekMode, err) => { 972 if (err == null) { 973 console.info('seek success!'); 974 } else { 975 console.info('seek fail!'); 976 } 977}); 978``` 979 980### seek<sup>8+</sup> 981 982seek(timeMs: number, mode?:SeekMode): Promise\<number> 983 984通过Promise方式跳转到指定播放位置，如果没有设置mode则跳转到指定时间点的下一个关键帧。 985 986**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 987 988**参数：** 989 990| 参数名 | 类型 | 必填 | 说明 | 991| ------ | ---------------------- | ---- | ------------------------------------ | 992| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒（ms）。 | 993| mode | [SeekMode](#seekmode8) | 否 | 跳转模式。 | 994 995**返回值：** 996 997| 类型 | 说明 | 998| -------------- | ----------------------------------- | 999| Promise\<void> | 跳转到指定播放位置的Promise返回值。 | 1000 1001**示例：** 1002 1003```js 1004videoPlayer.seek(seekTime).then((seekDoneTime) => { // seekDoneTime表示seek完成后的时间点 1005 console.info('seek success'); 1006}).catch((error) => { 1007 console.info(`video catchCallback, error:${error.message}`); 1008}); 1009 1010videoPlayer.seek(seekTime, seekMode).then((seekDoneTime) => { 1011 console.info('seek success'); 1012}).catch((error) => { 1013 console.info(`video catchCallback, error:${error.message}`); 1014}); 1015``` 1016 1017### setVolume<sup>8+</sup> 1018 1019setVolume(vol: number, callback: AsyncCallback\<void>): void 1020 1021通过回调方式设置音量。 1022 1023**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1024 1025**参数：** 1026 1027| 参数名 | 类型 | 必填 | 说明 | 1028| -------- | -------- | ---- | ------------------------------------------------------------ | 1029| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 1030| callback | function | 是 | 设置音量的回调方法。 | 1031 1032**示例：** 1033 1034```js 1035videoPlayer.setVolume((vol, err) => { 1036 if (err == null) { 1037 console.info('setVolume success!'); 1038 } else { 1039 console.info('setVolume fail!'); 1040 } 1041}); 1042``` 1043 1044### setVolume<sup>8+</sup> 1045 1046setVolume(vol: number): Promise\<void> 1047 1048通过Promise方式设置音量。 1049 1050**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1051 1052**参数：** 1053 1054| 参数名 | 类型 | 必填 | 说明 | 1055| ------ | ------ | ---- | ------------------------------------------------------------ | 1056| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | 1057 1058**返回值：** 1059 1060| 类型 | 说明 | 1061| -------------- | ------------------------- | 1062| Promise\<void> | 设置音量的Promise返回值。 | 1063 1064**示例：** 1065 1066```js 1067videoPlayer.setVolume(vol).then() => { 1068 console.info('setVolume success'); 1069}).catch((error) => { 1070 console.info(`video catchCallback, error:${error.message}`); 1071}); 1072``` 1073 1074### release<sup>8+</sup> 1075 1076release(callback: AsyncCallback\<void>): void 1077 1078通过回调方式释放视频资源。 1079 1080**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1081 1082**参数：** 1083 1084| 参数名 | 类型 | 必填 | 说明 | 1085| -------- | -------- | ---- | ------------------------ | 1086| callback | function | 是 | 释放视频资源的回调方法。 | 1087 1088**示例：** 1089 1090```js 1091videoPlayer.release((err) => { 1092 if (err == null) { 1093 console.info('release success!'); 1094 } else { 1095 console.info('release fail!'); 1096 } 1097}); 1098``` 1099 1100### release<sup>8+</sup> 1101 1102release(): Promise\<void> 1103 1104通过Promise方式释放视频资源。 1105 1106**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1107 1108**返回值：** 1109 1110| 类型 | 说明 | 1111| -------------- | ----------------------------- | 1112| Promise\<void> | 释放视频资源的Promise返回值。 | 1113 1114**示例：** 1115 1116```js 1117videoPlayer.release().then() => { 1118 console.info('release success'); 1119}).catch((error) => { 1120 console.info(`video catchCallback, error:${error.message}`); 1121}); 1122``` 1123 1124### getTrackDescription<sup>8+</sup> 1125 1126getTrackDescription(callback: AsyncCallback<Array\<MediaDescription>>): void 1127 1128通过回调方式获取视频轨道信息。 1129 1130**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1131 1132**参数：** 1133 1134| 参数名 | 类型 | 必填 | 说明 | 1135| -------- | ------------------------------------------------------------ | ---- | -------------------------- | 1136| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是 | 获取视频轨道信息回调方法。 | 1137 1138**示例：** 1139 1140```js 1141function printfDescription(obj) { 1142 for (let item in obj) { 1143 let property = obj[item]; 1144 console.info('video key is ' + item); 1145 console.info('video value is ' + property); 1146 } 1147} 1148 1149videoPlayer.getTrackDescription((error, arrlist) => { 1150 if (arrlist != null) { 1151 for (let i = 0; i < arrlist.length; i++) { 1152 printfDescription(arrlist[i]); 1153 } 1154 } else { 1155 console.log(`video getTrackDescription fail, error:${error.message}`); 1156 } 1157}); 1158``` 1159 1160### getTrackDescription<sup>8+</sup> 1161 1162getTrackDescription(): Promise<Array\<MediaDescription>> 1163 1164通过Promise方式获取视频轨道信息。 1165 1166**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1167 1168**返回值：** 1169 1170| 类型 | 说明 | 1171| ------------------------------------------------------ | ------------------------------- | 1172| Promise<Array<[MediaDescription](#mediadescription8)>> | 获取视频轨道信息Promise返回值。 | 1173 1174**示例：** 1175 1176```js 1177function printfDescription(obj) { 1178 for (let item in obj) { 1179 let property = obj[item]; 1180 console.info('video key is ' + item); 1181 console.info('video value is ' + property); 1182 } 1183} 1184 1185let arrayDescription; 1186videoPlayer.getTrackDescription().then((arrlist) => { 1187 if (arrlist != null) { 1188 arrayDescription = arrlist; 1189 } else { 1190 console.log('video getTrackDescription fail'); 1191 } 1192}).catch((error) => { 1193 console.info(`video catchCallback, error:${error.message}`); 1194}); 1195for (let i = 0; i < arrayDescription.length; i++) { 1196 printfDescription(arrayDescription[i]); 1197} 1198``` 1199 1200### setSpeed<sup>8+</sup> 1201 1202setSpeed(speed:number, callback: AsyncCallback\<number>): void 1203 1204通过回调方式设置播放速度。 1205 1206**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1207 1208**参数：** 1209 1210| 参数名 | 类型 | 必填 | 说明 | 1211| -------- | -------- | ---- | ---------------------------------------------------------- | 1212| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 1213| callback | function | 是 | 设置播放速度的回调方法。 | 1214 1215**示例：** 1216 1217```js 1218videoPlayer.setSpeed((speed:number, err) => { 1219 if (err == null) { 1220 console.info('setSpeed success!'); 1221 } else { 1222 console.info('setSpeed fail!'); 1223 } 1224}); 1225``` 1226 1227### setSpeed<sup>8+</sup> 1228 1229setSpeed(speed:number): Promise\<number> 1230 1231通过Promise方式设置播放速度。 1232 1233**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1234 1235**参数：** 1236 1237| 参数名 | 类型 | 必填 | 说明 | 1238| ------ | ------ | ---- | ---------------------------------------------------------- | 1239| speed | number | 是 | 指定播放视频速度，具体见[PlaybackSpeed](#playbackspeed8)。 | 1240 1241**返回值：** 1242 1243| 类型 | 说明 | 1244| ---------------- | ------------------------- | 1245| Promise\<number> | 通过Promise获取设置结果。 | 1246 1247**示例：** 1248 1249```js 1250videoPlayer.setSpeed(speed).then() => { 1251 console.info('setSpeed success'); 1252}).catch((error) => { 1253 console.info(`video catchCallback, error:${error.message}`); 1254}); 1255``` 1256 1257### on('playbackCompleted')<sup>8+</sup> 1258 1259on(type: 'playbackCompleted', callback: Callback\<void>): void 1260 1261开始监听视频播放完成事件。 1262 1263**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1264 1265**参数：** 1266 1267| 参数名 | 类型 | 必填 | 说明 | 1268| -------- | -------- | ---- | ----------------------------------------------------------- | 1269| type | string | 是 | 视频播放完成事件回调类型，支持的事件：'playbackCompleted'。 | 1270| callback | function | 是 | 视频播放完成事件回调方法。 | 1271 1272**示例：** 1273 1274```js 1275videoPlayer.on('playbackCompleted', () => { 1276 console.info('playbackCompleted success!'); 1277}); 1278``` 1279 1280### on('bufferingUpdate')<sup>8+</sup> 1281 1282on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void 1283 1284开始监听视频缓存更新事件。 1285 1286**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1287 1288**参数：** 1289 1290| 参数名 | 类型 | 必填 | 说明 | 1291| -------- | -------- | ---- | ------------------------------------------------------------ | 1292| type | string | 是 | 视频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | 1293| callback | function | 是 | 视频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时，value值有效，否则固定为0。 | 1294 1295**示例：** 1296 1297```js 1298videoPlayer.on('bufferingUpdate', (infoType, value) => { 1299 console.log('video bufferingInfo type: ' + infoType); 1300 console.log('video bufferingInfo value: ' + value); 1301}); 1302``` 1303 1304### on('startRenderFrame')<sup>8+</sup> 1305 1306on(type: 'startRenderFrame', callback: Callback\<void>): void 1307 1308开始监听视频播放首帧送显上报事件。 1309 1310**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1311 1312**参数：** 1313 1314| 参数名 | 类型 | 必填 | 说明 | 1315| -------- | --------------- | ---- | ------------------------------------------------------------ | 1316| type | string | 是 | 视频播放首帧送显上报事件回调类型，支持的事件：'startRenderFrame'。 | 1317| callback | Callback\<void> | 是 | 视频播放首帧送显上报事件回调方法。 | 1318 1319**示例：** 1320 1321```js 1322videoPlayer.on('startRenderFrame', () => { 1323 console.info('startRenderFrame success!'); 1324}); 1325``` 1326 1327### on('videoSizeChanged')<sup>8+</sup> 1328 1329on(type: 'videoSizeChanged', callback: (width: number, height: number) => void): void 1330 1331开始监听视频播放宽高变化事件。 1332 1333**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1334 1335**参数：** 1336 1337| 参数名 | 类型 | 必填 | 说明 | 1338| -------- | -------- | ---- | ------------------------------------------------------------ | 1339| type | string | 是 | 视频播放宽高变化事件回调类型，支持的事件：'videoSizeChanged'。 | 1340| callback | function | 是 | 视频播放宽高变化事件回调方法，width表示宽，height表示高。 | 1341 1342**示例：** 1343 1344```js 1345videoPlayer.on('videoSizeChanged', (width, height) => { 1346 console.log('video width is: ' + width); 1347 console.log('video height is: ' + height); 1348}); 1349``` 1350 1351### on('error')<sup>8+</sup> 1352 1353on(type: 'error', callback: ErrorCallback): void 1354 1355开始监听视频播放错误事件。 1356 1357**系统能力：** SystemCapability.Multimedia.Media.VideoPlayer 1358 1359**参数：** 1360 1361| 参数名 | 类型 | 必填 | 说明 | 1362| -------- | ------------- | ---- | ------------------------------------------------------------ | 1363| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。<br>- 'error'：视频播放中发生错误，触发该事件。 | 1364| callback | ErrorCallback | 是 | 播放错误事件回调方法。 | 1365 1366**示例：** 1367 1368```js 1369videoPlayer.on('error', (error) => { // 设置'error'事件回调 1370 console.info(`video error called, errName is ${error.name}`); // 打印错误类型名称 1371 console.info(`video error called, errCode is ${error.code}`); // 打印错误码 1372 console.info(`video error called, errMessage is ${error.message}`);// 打印错误类型详细描述 1373}); 1374videoPlayer.setVolume(3); //设置volume为无效值，触发'error'事件 1375``` 1376 1377## VideoPlayState<sup>8+</sup> 1378 1379视频播放的状态机，可通过state属性获取当前状态。 1380 1381**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoPlayer。 1382 1383| 名称 | 类型 | 描述 | 1384| -------- | ------ | -------------- | 1385| idle | string | 视频播放空闲。 | 1386| prepared | string | 视频播放准备。 | 1387| playing | string | 视频正在播放。 | 1388| paused | string | 视频暂停播放。 | 1389| stopped | string | 视频播放停止。 | 1390| error | string | 错误状态。 | 1391 1392## SeekMode<sup>8+</sup> 1393 1394视频播放的Seek模式枚举，可通过seek方法作为参数传递下去。 1395 1396**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。 1397 1398| 名称 | 值 | 描述 | 1399| -------------- | ---- | ------------------------------------------------------------ | 1400| SEEK_NEXT_SYNC | 0 | 表示跳转到指定时间点的下一个关键帧，建议向后快进的时候用这个枚举值。 | 1401| SEEK_PREV_SYNC | 1 | 表示跳转到指定时间点的上一个关键帧，建议向前快进的时候用这个枚举值。 | 1402 1403## PlaybackSpeed<sup>8+</sup> 1404 1405视频播放的倍速枚举，可通过setSpeed方法作为参数传递下去。 1406 1407**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoPlayer。 1408 1409| 名称 | 值 | 描述 | 1410| -------------------- | ---- | ------------------------------ | 1411| SPEED_FORWARD_0_75_X | 0 | 表示视频播放正常播速的0.75倍。 | 1412| SPEED_FORWARD_1_00_X | 1 | 表示视频播放正常播速。 | 1413| SPEED_FORWARD_1_25_X | 2 | 表示视频播放正常播速的1.25倍。 | 1414| SPEED_FORWARD_1_75_X | 3 | 表示视频播放正常播速的1.75倍。 | 1415| SPEED_FORWARD_2_00_X | 4 | 表示视频播放正常播速的2.00倍。 | 1416 1417## MediaDescription<sup>8+</sup> 1418 1419### [key : string] : Object 1420 1421通过key-value方式获取媒体信息。 1422 1423**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。 1424 1425| 名称 | 类型 | 说明 | 1426| ----- | ------ | ------------------------------------------------------------ | 1427| key | string | 通过key值获取对应的value。key值具体可见[MediaDescriptionKey](#mediadescriptionkey8)。 | 1428| value | any | 对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[MediaDescriptionKey](#mediadescriptionkey8)的描述信息。 | 1429 1430**示例：** 1431 1432```js 1433function printfItemDescription(obj, key) { 1434 let property = obj[key]; 1435 console.info('audio key is ' + key); 1436 console.info('audio value is ' + property); 1437} 1438 1439audioPlayer.getTrackDescription((error, arrlist) => { 1440 if (arrlist != null) { 1441 for (let i = 0; i < arrlist.length; i++) { 1442 printfItemDescription(arrlist[i], MD_KEY_TRACK_TYPE); //打印出每条轨道MD_KEY_TRACK_TYPE的值 1443 } 1444 } else { 1445 console.log(`audio getTrackDescription fail, error:${error.message}`); 1446 } 1447}); 1448``` 1449 1450## AudioRecorder 1451 1452音频录制管理类，用于录制音频媒体。在调用AudioRecorder的方法前，需要先通过[createAudioRecorder()](#mediacreateaudiorecorder) 构建一个[AudioRecorder](#audiorecorder)实例。 1453 1454音频录制demo可参考：[音频录制开发指导](../../media/audio-recorder.md) 1455 1456### prepare<a name=audiorecorder_prepare></a> 1457 1458prepare(config: AudioRecorderConfig): void 1459 1460录音准备。 1461 1462**需要权限：** ohos.permission.MICROPHONE 1463 1464**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 1465 1466**参数：** 1467 1468| 参数名 | 类型 | 必填 | 说明 | 1469| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ | 1470| config | [AudioRecorderConfig](#audiorecorderconfig) | 是 | 配置录音的相关参数，包括音频输出URI、编码格式、采样率、声道数、输出格式等。 | 1471 1472**示例：** 1473 1474```js 1475let audioRecorderConfig = { 1476 audioEncoder : media.AudioEncoder.AAC_LC, 1477 audioEncodeBitRate : 22050, 1478 audioSampleRate : 22050, 1479 numberOfChannels : 2, 1480 format : media.AudioOutputFormat.AAC_ADTS, 1481 uri : 'fd://1', // 文件需先由调用者创建，并给予适当的权限 1482 location : { latitude : 30, longitude : 130}, 1483} 1484audioRecorder.on('prepare', () => { //设置'prepare'事件回调 1485 console.log('prepare success'); 1486}); 1487audioRecorder.prepare(audioRecorderConfig); 1488``` 1489 1490 1491### start<a name=audiorecorder_start></a> 1492 1493start(): void 1494 1495开始录制，需在[prepare](#audiorecorder_on)事件成功触发后，才能调用start方法。 1496 1497**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 1498 1499**示例：** 1500 1501```js 1502audioRecorder.on('start', () => { //设置'start'事件回调 1503 console.log('audio recorder start success'); 1504}); 1505audioRecorder.start(); 1506``` 1507 1508### pause<a name=audiorecorder_pause></a> 1509 1510pause():void 1511 1512暂停录制，需要在[start](#audiorecorder_on)事件成功触发后，才能调用pause方法。 1513 1514**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 1515 1516**示例：** 1517 1518```js 1519audioRecorder.on('pause', () => { //设置'pause'事件回调 1520 console.log('audio recorder pause success'); 1521}); 1522audioRecorder.pause(); 1523``` 1524 1525### resume<a name=audiorecorder_resume></a> 1526 1527resume():void 1528 1529恢复录制，需要在[pause](#audiorecorder_on)事件成功触发后，才能调用resume方法。 1530 1531**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 1532 1533**示例：** 1534 1535```js 1536audioRecorder.on('resume', () => { //设置'resume'事件回调 1537 console.log('audio recorder resume success'); 1538}); 1539audioRecorder.resume(); 1540``` 1541 1542### stop<a name=audiorecorder_stop></a> 1543 1544stop(): void 1545 1546停止录音。 1547 1548**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 1549 1550**示例：** 1551 1552```js 1553audioRecorder.on('stop', () => { //设置'stop'事件回调 1554 console.log('audio recorder stop success'); 1555}); 1556audioRecorder.stop(); 1557``` 1558 1559### release<a name=audiorecorder_release></a> 1560 1561release(): void 1562 1563释放录音资源。 1564 1565**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 1566 1567**示例：** 1568 1569```js 1570audioRecorder.on('release', () => { //设置'release'事件回调 1571 console.log('audio recorder release success'); 1572}); 1573audioRecorder.release(); 1574audioRecorder = undefined; 1575``` 1576 1577### reset<a name=audiorecorder_reset></a> 1578 1579reset(): void 1580 1581重置录音。 1582 1583进行重置录音之前，需要先调用[stop()](#audiorecorder_stop)停止录音。重置录音之后，需要调用[prepare()](#audiorecorder_prepare)设置录音参数项，才能再次进行录音。 1584 1585**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 1586 1587**示例：** 1588 1589```js 1590audioRecorder.on('reset', () => { //设置'reset'事件回调 1591 console.log('audio recorder reset success'); 1592}); 1593audioRecorder.reset(); 1594``` 1595 1596### on('prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset')<a name=audiorecorder_on></a> 1597 1598on(type: 'prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset', callback: () => void): void 1599 1600开始订阅音频录制事件。 1601 1602**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 1603 1604**参数：** 1605 1606| 参数名 | 类型 | 必填 | 说明 | 1607| -------- | -------- | ---- | ------------------------------------------------------------ | 1608| type | string | 是 | 录制事件回调类型，支持的事件包括：'prepare' \| 'start' \| 'pause' \| ’resume‘ \| 'stop' \| 'release' \| 'reset'。<br/>- 'prepare' ：完成[prepare](#audiorecorder_prepare)调用，音频录制参数设置完成，触发该事件。<br/>- 'start' ：完成[start](#audiorecorder_start)调用，音频录制开始，触发该事件。<br/>- 'pause': 完成[pause](#audiorecorder_pause)调用，音频暂停录制，触发该事件。<br/>- 'resume': 完成[resume](#audiorecorder_resume)调用，音频恢复录制，触发该事件。<br/>- 'stop' ：完成[stop](#audiorecorder_stop)调用，音频停止录制，触发该事件。<br/>- 'release' ：完成[release](#audiorecorder_release)调用，音频释放录制资源，触发该事件。<br/>- 'reset'：完成[reset](#audiorecorder_reset)调用，音频重置为初始状态，触发该事件。 | 1609| callback | ()=>void | 是 | 录制事件回调方法。 | 1610 1611**示例：** 1612 1613```js 1614let audiorecorder = media.createAudioRecorder(); // 创建一个音频录制实例 1615let audioRecorderConfig = { 1616 audioEncoder : media.AudioEncoder.AAC_LC, , 1617 audioEncodeBitRate : 22050, 1618 audioSampleRate : 22050, 1619 numberOfChannels : 2, 1620 format : media.AudioOutputFormat.AAC_ADTS, 1621 uri : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限 1622 location : { latitude : 30, longitude : 130}, 1623} 1624audioRecorder.on('error', (error) => { // 设置'error'事件回调 1625 console.info(`audio error called, errName is ${error.name}`); 1626 console.info(`audio error called, errCode is ${error.code}`); 1627 console.info(`audio error called, errMessage is ${error.message}`); 1628}); 1629audioRecorder.on('prepare', () => { // 设置'prepare'事件回调 1630 console.log('prepare success'); 1631 audioRecorder.start(); // 开始录制，并触发'start'事件回调 1632}); 1633audioRecorder.on('start', () => { // 设置'start'事件回调 1634 console.log('audio recorder start success'); 1635}); 1636audioRecorder.on('pause', () => { // 设置'pause'事件回调 1637 console.log('audio recorder pause success'); 1638}); 1639audioRecorder.on('resume', () => { // 设置'resume'事件回调 1640 console.log('audio recorder resume success'); 1641}); 1642audioRecorder.on('stop', () => { // 设置'stop'事件回调 1643 console.log('audio recorder stop success'); 1644}); 1645audioRecorder.on('release', () => { // 设置'release'事件回调 1646 console.log('audio recorder release success'); 1647}); 1648audioRecorder.on('reset', () => { // 设置'reset'事件回调 1649 console.log('audio recorder reset success'); 1650}); 1651audioRecorder.prepare(audioRecorderConfig) // 设置录制参数 ，并触发'prepare'事件回调 1652``` 1653 1654### on('error') 1655 1656on(type: 'error', callback: ErrorCallback): void 1657 1658开始订阅音频录制错误事件。 1659 1660**系统能力：** SystemCapability.Multimedia.Media.AudioRecorder 1661 1662**参数：** 1663 1664| 参数名 | 类型 | 必填 | 说明 | 1665| -------- | ------------- | ---- | ------------------------------------------------------------ | 1666| type | string | 是 | 录制错误事件回调类型'error'。<br/>- 'error'：音频录制过程中发生错误，触发该事件。 | 1667| callback | ErrorCallback | 是 | 录制错误事件回调方法。 | 1668 1669**示例：** 1670 1671```js 1672let audioRecorderConfig = { 1673 audioEncoder : media.AudioEncoder.AAC_LC, 1674 audioEncodeBitRate : 22050, 1675 audioSampleRate : 22050, 1676 numberOfChannels : 2, 1677 format : media.AudioOutputFormat.AAC_ADTS, 1678 uri : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限 1679 location : { latitude : 30, longitude : 130}, 1680} 1681audioRecorder.on('error', (error) => { // 设置'error'事件回调 1682 console.info(`audio error called, error: ${error}`); 1683}); 1684audioRecorder.prepare(audioRecorderConfig); // prepare设置错误参数，触发'error'事件 1685``` 1686 1687## AudioRecorderConfig 1688 1689表示音频的录音配置。 1690 1691**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.AudioRecorder。 1692 1693| 名称 | 参数类型 | 必填 | 说明 | 1694| --------------------- | --------------------------------------- | ---- | ------------------------------------------------------------ | 1695| audioEncoder<sup>(deprecated)</sup> | [AudioEncoder](#audioencoder) | 否 | 音频编码格式，默认设置为AAC_LC。<br/>**说明：** 从API Version 8 开始废弃，建议使用audioEncoderMime替代。 | 1696| audioEncodeBitRate | number | 否 | 音频编码比特率，默认值为48000。 | 1697| audioSampleRate | number | 否 | 音频采集采样率，默认值为48000。 | 1698| numberOfChannels | number | 否 | 音频采集声道数，默认值为2。 | 1699| format<sup>(deprecated)</sup> | [AudioOutputFormat](#audiooutputformat) | 否 | 音频输出封装格式，默认设置为MPEG_4。<br/>**说明：** 从API Version 8 开始废弃，建议使用fileFormat替代。 | 1700| location | [Location](#location) | 否 | 音频采集的地理位置。 | 1701| uri | string | 是 | 音频输出URI：fd://xx (fd number)<br/> <br/>文件需要由调用者创建，并赋予适当的权限。 | 1702| audioEncoderMime<sup>8+</sup> | [CodecMimeType](#codecmimetype8) | 否 | 音频编码格式。 | 1703| fileFormat<sup>8+</sup> | [ContainerFormatType](#containerformattype8) | 否 | 音频编码格式。 | 1704 1705 1706## AudioEncoder<sup>(deprecated)</sup> 1707 1708> **说明：** 1709> 从 API Version 8 开始废弃，建议使用[CodecMimeType](#codecmimetype8)替代。 1710 1711表示音频编码格式的枚举。 1712 1713**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.AudioRecorder。 1714 1715| 名称 | 默认值 | 说明 | 1716| ------- | ------ | ------------------------------------------------------------ | 1717| DEFAULT | 0 | 默认编码格式。<br/>仅做接口定义，暂不支持使用。 | 1718| AMR_NB | 1 | AMR-NB(Adaptive Multi Rate-Narrow Band Speech Codec) 编码格式。<br/>仅做接口定义，暂不支持使用。 | 1719| AMR_WB | 2 | AMR-WB(Adaptive Multi Rate-Wide Band Speech Codec) 编码格式。<br/>仅做接口定义，暂不支持使用。 | 1720| AAC_LC | 3 | AAC-LC（Advanced Audio Coding Low Complexity）编码格式。 | 1721| HE_AAC | 4 | HE_AAC（High-Efficiency Advanced Audio Coding）编码格式。<br/>仅做接口定义，暂不支持使用。 | 1722 1723 1724## AudioOutputFormat<sup>(deprecated)</sup> 1725 1726> **说明：** 1727> 从 API Version 8 开始废弃，建议使用[ContainerFormatType](#containerformattype8)替代。 1728 1729表示音频封装格式的枚举。 1730 1731**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.AudioRecorder。 1732 1733| 名称 | 默认值 | 说明 | 1734| -------- | ------ | ------------------------------------------------------------ | 1735| DEFAULT | 0 | 默认封装格式。<br/>仅做接口定义，暂不支持使用。 | 1736| MPEG_4 | 2 | 封装为MPEG-4格式。 | 1737| AMR_NB | 3 | 封装为AMR_NB格式。<br/>仅做接口定义，暂不支持使用。 | 1738| AMR_WB | 4 | 封装为AMR_WB格式。<br/>仅做接口定义，暂不支持使用。 | 1739| AAC_ADTS | 6 | 封装为ADTS（Audio Data Transport Stream）格式，是AAC音频的传输流格式。 | 1740 1741 1742## ContainerFormatType<sup>8+</sup> 1743 1744表示容器格式类型的枚举，缩写为CFT。 1745 1746**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。 1747 1748| 名称 | 值 | 说明 | 1749| ----------- | ----- | --------------------- | 1750| CFT_MPEG_4 | "mp4" | 视频的容器格式，MP4。 | 1751| CFT_MPEG_4A | "m4a" | 音频的容器格式，M4A。 | 1752 1753## Location 1754 1755视频录制的地理位置。 1756 1757**系统能力：** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。 1758 1759| 名称 | 参数类型 | 必填 | 说明 | 1760| --------- | -------- | ---- | ---------------- | 1761| latitude | number | 是 | 地理位置的纬度。 | 1762| longitude | number | 是 | 地理位置的经度。 |
