js-apis-media.md 86.7 KB
Newer Older
W
wusongqing 已提交
1
# 媒体服务
2

Z
zengyawen 已提交
3 4 5
> **说明:**
> 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

W
wusongqing 已提交
6
媒体子系统为开发者提供一套简单且易于理解的接口,使得开发者能够方便接入系统并使用系统的媒体资源。
Z
zengyawen 已提交
7

W
wusongqing 已提交
8
媒体子系统包含了音视频相关媒体业务,提供以下常用功能:
9

W
wusongqing 已提交
10 11 12
- 音频播放([AudioPlayer](#audioplayer)
- 视频播放([VideoPlayer](#videoplayer8)
- 音频录制([AudioRecorder](#audiorecorder)
Z
zengyawen 已提交
13
- 视频录制([VideoRecorder](#videorecorder9)
14

W
wusongqing 已提交
15
后续将提供以下功能:DataSource音视频播放、音视频编解码、容器封装解封装、媒体能力查询等功能。
16

W
wusongqing 已提交
17
## 导入模块
Z
zengyawen 已提交
18

19
```js
Z
zengyawen 已提交
20 21 22
import media from '@ohos.multimedia.media';
```

23
##  media.createAudioPlayer
Z
zengyawen 已提交
24

25
createAudioPlayer(): [AudioPlayer](#audioplayer)
Z
zengyawen 已提交
26

W
wusongqing 已提交
27 28
同步方式创建音频播放实例。

Z
zengyawen 已提交
29
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
30

W
wusongqing 已提交
31
**返回值:**
Z
zengyawen 已提交
32

W
wusongqing 已提交
33
| 类型                        | 说明                                                         |
34
| --------------------------- | ------------------------------------------------------------ |
W
wusongqing 已提交
35
| [AudioPlayer](#audioplayer) | 返回AudioPlayer类实例,失败时返回null。可用于音频播放、暂停、停止等操作。 |
Z
zengyawen 已提交
36

W
wusongqing 已提交
37
**示例:**
Z
zengyawen 已提交
38

39
```js
Z
zengyawen 已提交
40
let audioPlayer = media.createAudioPlayer();
Z
zengyawen 已提交
41
```
42

43 44 45 46
## media.createVideoPlayer<sup>8+</sup>

createVideoPlayer(callback: AsyncCallback\<[VideoPlayer](#videoplayer8)>): void

W
wusongqing 已提交
47
异步方式创建视频播放实例,通过注册回调函数获取返回值。
48

Z
zengyawen 已提交
49 50
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
51
**参数:**
Z
zengyawen 已提交
52

W
wusongqing 已提交
53
| 参数名   | 类型                                        | 必填 | 说明                           |
Z
zengyawen 已提交
54
| -------- | ------------------------------------------- | ---- | ------------------------------ |
W
wusongqing 已提交
55
| callback | AsyncCallback<[VideoPlayer](#videoplayer8)> | 是   | 异步创建视频播放实例回调方法。 |
56

W
wusongqing 已提交
57
**示例:**
58 59

```js
Z
zengyawen 已提交
60 61
let videoPlayer

62 63 64 65 66 67 68 69 70 71 72 73
media.createVideoPlayer((error, video) => {
   if (typeof(video) != 'undefined') {
       videoPlayer = video;
       console.info('video createVideoPlayer success');
   } else {
       console.info(`video createVideoPlayer fail, error:${error.message}`);
   }
});
```

## media.createVideoPlayer<sup>8+</sup>

Z
zengyawen 已提交
74
createVideoPlayer(): Promise<[VideoPlayer](#videoplayer8)>
75

W
wusongqing 已提交
76
异步方式创建视频播放实例,通过Promise获取返回值。
77

Z
zengyawen 已提交
78 79
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
80
**返回值:**
Z
zengyawen 已提交
81

W
wusongqing 已提交
82
| 类型                                  | 说明                                |
Z
zengyawen 已提交
83
| ------------------------------------- | ----------------------------------- |
W
wusongqing 已提交
84
| Promise<[VideoPlayer](#videoplayer8)> | 异步创建视频播放实例Promise返回值。 |
85

W
wusongqing 已提交
86
**示例:**
87 88

```js
Z
zengyawen 已提交
89 90
let videoPlayer

91 92
media.createVideoPlayer().then((video) => {
   if (typeof(video) != 'undefined') {
93 94 95 96 97
       videoPlayer = video;
       console.info('video createVideoPlayer success');
   } else {
       console.info('video createVideoPlayer fail');
   }
98 99 100
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
101 102
```

Z
zengyawen 已提交
103
## media.createAudioRecorder
104

Z
zengyawen 已提交
105
createAudioRecorder(): AudioRecorder
Z
zengyawen 已提交
106

W
wusongqing 已提交
107
创建音频录制的实例来控制音频的录制。
Z
zengyawen 已提交
108

Z
zengyawen 已提交
109 110
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder

W
wusongqing 已提交
111
**返回值:**
Z
zengyawen 已提交
112

W
wusongqing 已提交
113
| 类型                            | 说明                                      |
Z
zengyawen 已提交
114
| ------------------------------- | ----------------------------------------- |
W
wusongqing 已提交
115
| [AudioRecorder](#audiorecorder) | 返回AudioRecorder类实例,失败时返回null。 |
Z
zengyawen 已提交
116

W
wusongqing 已提交
117
**示例:**
118

119
```js
A
amr  
abc12133 已提交
120
let audiorecorder = media.createAudioRecorder();
Z
zengyawen 已提交
121
```
Z
zengyawen 已提交
122

123
## media.createVideoRecorder<sup>9+</sup>
W
wusongqing 已提交
124

125
createVideoRecorder(callback: AsyncCallback\<[VideoRecorder](#videorecorder9)>): void
W
wusongqing 已提交
126 127 128

异步方式创建视频录制实例。通过注册回调函数获取返回值。

Z
zengyawen 已提交
129 130
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
131 132
**参数:**

Z
zengyawen 已提交
133 134
| 参数名   | 类型                                            | 必填 | 说明                           |
| -------- | ----------------------------------------------- | ---- | ------------------------------ |
135
| callback | AsyncCallback<[VideoRecorder](#videorecorder9)> | 是   | 异步创建视频录制实例回调方法。 |
W
wusongqing 已提交
136 137 138 139

**示例:**

```js
Z
zengyawen 已提交
140 141 142
let videoRecorder

media.createVideoRecorder((error, video) => {
143 144
   if (typeof(video) != 'undefined') {
       videoRecorder = video;
Z
zengyawen 已提交
145
       console.info('video createVideoRecorder success');
146
   } else {
Z
zengyawen 已提交
147
       console.info(`video createVideoRecorder fail, error:${error.message}`);
148 149 150 151
   }
});
```

152
## media.createVideoRecorder<sup>9+</sup>
153

154
createVideoRecorder(): Promise<[VideoRecorder](#videorecorder9)>
155

W
wusongqing 已提交
156
异步方式创建视频录制实例。通过Promise获取返回值。
Z
zengyawen 已提交
157

Z
zengyawen 已提交
158 159
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
160
**返回值:**
161

Z
zengyawen 已提交
162 163
| 类型                                      | 说明                                |
| ----------------------------------------- | ----------------------------------- |
164
| Promise<[VideoRecorder](#videorecorder9)> | 异步创建视频录制实例Promise返回值。 |
165

W
wusongqing 已提交
166
**示例:**
167 168

```js
Z
zengyawen 已提交
169 170
let videoRecorder

171
media.createVideoRecorder().then((video) => {
172 173
    if (typeof(video) != 'undefined') {
       videoRecorder = video;
Z
zengyawen 已提交
174
       console.info('video createVideoRecorder success');
175
   } else {
Z
zengyawen 已提交
176
       console.info('video createVideoRecorder fail');
177
   }
178 179 180
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
181 182 183 184
```



185 186
## MediaErrorCode<sup>8+</sup>

Z
zengyawen 已提交
187 188 189
媒体服务错误类型枚举。

**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。
W
wusongqing 已提交
190 191 192 193 194 195 196 197 198 199 200 201 202

| 名称                       | 值   | 说明                                   |
| -------------------------- | ---- | -------------------------------------- |
| MSERR_OK                   | 0    | 表示操作成功。                         |
| MSERR_NO_MEMORY            | 1    | 表示申请内存失败,系统可能无可用内存。 |
| MSERR_OPERATION_NOT_PERMIT | 2    | 表示无权限执行此操作。                 |
| MSERR_INVALID_VAL          | 3    | 表示传入入参无效。                     |
| MSERR_IO                   | 4    | 表示发生IO错误。                       |
| MSERR_TIMEOUT              | 5    | 表示操作超时。                         |
| MSERR_UNKNOWN              | 6    | 表示未知错误。                         |
| MSERR_SERVICE_DIED         | 7    | 表示服务端失效。                       |
| MSERR_INVALID_STATE        | 8    | 表示在当前状态下,不允许执行此操作。   |
| MSERR_UNSUPPORTED          | 9    | 表示在当前版本下,不支持此操作。       |
203 204 205

## MediaType<sup>8+</sup>

Z
zengyawen 已提交
206 207 208
媒体类型枚举。

**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。
209

Z
zengyawen 已提交
210 211 212 213
| 名称           | 值   | 说明       |
| -------------- | ---- | ---------- |
| MEDIA_TYPE_AUD | 0    | 表示音频。 |
| MEDIA_TYPE_VID | 1    | 表示视频。 |
214 215 216

## CodecMimeType<sup>8+</sup>

Z
zengyawen 已提交
217 218 219
Codec MIME类型枚举。

**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。
220

Z
zengyawen 已提交
221 222 223 224 225 226 227
| 名称         | 值                    | 说明                     |
| ------------ | --------------------- | ------------------------ |
| VIDEO_H263   | 'video/h263'          | 表示视频/h263类型。      |
| VIDEO_AVC    | 'video/avc'           | 表示视频/avc类型。       |
| VIDEO_MPEG2  | 'video/mpeg2'         | 表示视频/mpeg2类型。     |
| VIDEO_MPEG4  | 'video/mp4v-es'       | 表示视频/mpeg4类型。     |
| VIDEO_VP8    | 'video/x-vnd.on2.vp8' | 表示视频/vp8类型。       |
228
| AUDIO_AAC    | "audio/mp4a-latm"     | 表示音频/mp4a-latm类型。 |
Z
zengyawen 已提交
229 230
| AUDIO_VORBIS | 'audio/vorbis'        | 表示音频/vorbis类型。    |
| AUDIO_FLAC   | 'audio/flac'          | 表示音频/flac类型。      |
231 232 233

## MediaDescriptionKey<sup>8+</sup>

Z
zengyawen 已提交
234 235 236
媒体信息描述枚举。

**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。
237

W
wusongqing 已提交
238
| 名称                     | 值              | 说明                                                         |
239
| ------------------------ | --------------- | ------------------------------------------------------------ |
W
wusongqing 已提交
240 241 242
| MD_KEY_TRACK_INDEX       | "track_index"   | 表示轨道序号,其对应键值类型为number。                       |
| MD_KEY_TRACK_TYPE        | "track_type"    | 表示轨道类型,其对应键值类型为number,参考[MediaType](#mediatype8)。 |
| MD_KEY_CODEC_MIME        | "codec_mime"    | 表示codec_mime类型,其对应键值类型为string。                 |
Z
zengyawen 已提交
243 244 245 246 247
| MD_KEY_DURATION          | "duration"      | 表示媒体时长,其对应键值类型为number,单位为毫秒(ms)。     |
| MD_KEY_BITRATE           | "bitrate"       | 表示比特率,其对应键值类型为number,单位为比特率(bps)。    |
| MD_KEY_WIDTH             | "width"         | 表示视频宽度,其对应键值类型为number,单位为像素(px)。     |
| MD_KEY_HEIGHT            | "height"        | 表示视频高度,其对应键值类型为number,单位为像素(px)。     |
| MD_KEY_FRAME_RATE        | "frame_rate"    | 表示视频帧率,其对应键值类型为number,单位为100帧每秒(100fps)。 |
W
wusongqing 已提交
248
| MD_KEY_AUD_CHANNEL_COUNT | "channel_count" | 表示声道数,其对应键值类型为number。                         |
Z
zengyawen 已提交
249
| MD_KEY_AUD_SAMPLE_RATE   | "sample_rate"   | 表示采样率,其对应键值类型为number,单位为赫兹(Hz)。       |
250 251 252

## BufferingInfoType<sup>8+</sup>

Z
zengyawen 已提交
253 254 255
缓存事件类型枚举。

**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。
256

Z
zengyawen 已提交
257 258 259 260 261 262
| 名称              | 值   | 说明                             |
| ----------------- | ---- | -------------------------------- |
| BUFFERING_START   | 1    | 表示开始缓存。                   |
| BUFFERING_END     | 2    | 表示结束缓存。                   |
| BUFFERING_PERCENT | 3    | 表示缓存百分比。                 |
| CACHED_DURATION   | 4    | 表示缓存时长,单位为毫秒(ms)。 |
263

Z
zengyawen 已提交
264
## AudioPlayer
Z
zengyawen 已提交
265

Z
zengyawen 已提交
266
音频播放管理类,用于管理和播放音频媒体。在调用AudioPlayer的方法前,需要先通过[createAudioPlayer()](#mediacreateaudioplayer)构建一个[AudioPlayer](#audioplayer)实例。
Z
zengyawen 已提交
267

W
wusongqing 已提交
268
音频播放demo可参考:[音频播放开发指导](../../media/audio-playback.md)
Z
zengyawen 已提交
269

W
wusongqing 已提交
270
### 属性<a name=audioplayer_属性></a>
Z
zengyawen 已提交
271

Z
zengyawen 已提交
272 273
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.AudioPlayer。

W
wusongqing 已提交
274
| 名称        | 类型                      | 可读 | 可写 | 说明                                                         |
275
| ----------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ |
Z
zengyawen 已提交
276
| src         | string                    | 是   | 是   | 音频媒体URI,支持当前主流的音频格式(mp4、aac、mp3、ogg、wav)。<br>**支持路径示例**<br>1、fd类型播放:fd://xx<br>![](figures/zh-cn_image_url.png)<br>2、http网络播放: http://xx<br>3、hls网络播放路径:开发中<br>**注意事项**<br>使用媒体素材需要获取读权限,否则无法正常播放。 |
Z
zengyawen 已提交
277 278 279 280
| loop        | boolean                   | 是   | 是   | 音频循环播放属性,设置为'true'表示循环播放。                 |
| currentTime | number                    | 是   | 否   | 音频的当前播放位置。                                         |
| duration    | number                    | 是   | 否   | 音频时长。                                                   |
| state       | [AudioState](#audiostate) | 是   | 否   | 音频播放的状态。                                             |
Z
zengyawen 已提交
281

282
### play<a name=audioplayer_play></a>
Z
zengyawen 已提交
283

Z
zengyawen 已提交
284
play(): void
Z
zengyawen 已提交
285

286
开始播放音频资源,需在[dataLoad](#audioplayer_on)事件成功触发后,才能调用。
Z
zengyawen 已提交
287

Z
zengyawen 已提交
288 289
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
290
**示例:**
Z
zengyawen 已提交
291

292
```js
W
wusongqing 已提交
293
audioPlayer.on('play', () => {    //设置'play'事件回调
294
    console.log('audio play success');
Z
zengyawen 已提交
295
});
296
audioPlayer.play();
Z
zengyawen 已提交
297
```
Z
zengyawen 已提交
298

299
### pause<a name=audioplayer_pause></a>
Z
zengyawen 已提交
300

Z
zengyawen 已提交
301
pause(): void
Z
zengyawen 已提交
302

W
wusongqing 已提交
303
暂停播放音频资源。
B
bird_j 已提交
304

Z
zengyawen 已提交
305 306
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
307
**示例:**
Z
zengyawen 已提交
308

309
```js
W
wusongqing 已提交
310
audioPlayer.on('pause', () => {    //设置'pause'事件回调
311
    console.log('audio pause success');
Z
zengyawen 已提交
312
});
313
audioPlayer.pause();
Z
zengyawen 已提交
314
```
Z
zengyawen 已提交
315

316
### stop<a name=audioplayer_stop></a>
Z
zengyawen 已提交
317

Z
zengyawen 已提交
318
stop(): void
Z
zengyawen 已提交
319

W
wusongqing 已提交
320
停止播放音频资源。
Z
zengyawen 已提交
321

Z
zengyawen 已提交
322 323
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
324
**示例:**
Z
zengyawen 已提交
325

326
```js
W
wusongqing 已提交
327
audioPlayer.on('stop', () => {    //设置'stop'事件回调
328 329 330
    console.log('audio stop success');
});
audioPlayer.stop();
Z
zengyawen 已提交
331
```
332 333 334 335 336

### reset<sup>7+</sup><a name=audioplayer_reset></a>

reset(): void

W
wusongqing 已提交
337
切换播放音频资源。
B
bird_j 已提交
338

Z
zengyawen 已提交
339 340
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
341
**示例:**
342 343

```js
W
wusongqing 已提交
344
audioPlayer.on('reset', () => {    //设置'reset'事件回调
345
    console.log('audio reset success');
Z
zengyawen 已提交
346
});
347
audioPlayer.reset();
Z
zengyawen 已提交
348
```
Z
zengyawen 已提交
349

350
### seek<a name=audioplayer_seek></a>
Z
zengyawen 已提交
351

Z
zengyawen 已提交
352
seek(timeMs: number): void
Z
zengyawen 已提交
353

W
wusongqing 已提交
354
跳转到指定播放位置。
Z
zengyawen 已提交
355

Z
zengyawen 已提交
356 357
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
358
**参数:**
B
bird_j 已提交
359

Z
zengyawen 已提交
360 361 362
| 参数名 | 类型   | 必填 | 说明                                 |
| ------ | ------ | ---- | ------------------------------------ |
| timeMs | number | 是   | 指定的跳转时间节点,单位毫秒(ms)。 |
Z
zengyawen 已提交
363

W
wusongqing 已提交
364
**示例:**
Z
zengyawen 已提交
365

366
```js
W
wusongqing 已提交
367
audioPlayer.on('timeUpdate', (seekDoneTime) => {    //设置'timeUpdate'事件回调
368 369 370 371 372
    if (typeof (seekDoneTime) == 'undefined') {
        console.info('audio seek fail');
        return;
    }
    console.log('audio seek success. seekDoneTime: ' + seekDoneTime);
Z
zengyawen 已提交
373
});
W
wusongqing 已提交
374
audioPlayer.seek(30000);    //seek到30000ms的位置
Z
zengyawen 已提交
375
```
Z
zengyawen 已提交
376

377
### setVolume<a name=audioplayer_setvolume></a>
Z
zengyawen 已提交
378

Z
zengyawen 已提交
379
setVolume(vol: number): void
Z
zengyawen 已提交
380

W
wusongqing 已提交
381
设置音量。
B
bird_j 已提交
382

Z
zengyawen 已提交
383 384
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
385
**参数:**
Z
zengyawen 已提交
386

W
wusongqing 已提交
387
| 参数名 | 类型   | 必填 | 说明                                                         |
388
| ------ | ------ | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
389
| vol    | number | 是   | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |
Z
zengyawen 已提交
390

W
wusongqing 已提交
391
**示例:**
Z
zengyawen 已提交
392

393
```js
W
wusongqing 已提交
394
audioPlayer.on('volumeChange', () => {    //设置'volumeChange'事件回调
395
    console.log('audio volumeChange success');
Z
zengyawen 已提交
396
});
W
wusongqing 已提交
397
audioPlayer.setVolume(1);    //设置音量到100%
Z
zengyawen 已提交
398
```
Z
zengyawen 已提交
399

400
### release<a name=audioplayer_release></a>
Z
zengyawen 已提交
401

402
release(): void
Z
zengyawen 已提交
403

W
wusongqing 已提交
404
释放音频资源。
B
bird_j 已提交
405

Z
zengyawen 已提交
406 407
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
408
**示例:**
Z
zengyawen 已提交
409

410 411 412
```js
audioPlayer.release();
audioPlayer = undefined;
Z
zengyawen 已提交
413
```
Z
zengyawen 已提交
414

415
### getTrackDescription<sup>8+</sup><a name=audioplayer_gettrackdescription1></a>
Z
zengyawen 已提交
416

Z
zengyawen 已提交
417
getTrackDescription(callback: AsyncCallback<Array\<MediaDescription>>): void
Z
zengyawen 已提交
418

419
通过回调方式获取音频轨道信息。需在[dataLoad](#audioplayer_on)事件成功触发后,才能调用。
420

Z
zengyawen 已提交
421 422
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
423
**参数:**
B
bird_j 已提交
424

W
wusongqing 已提交
425
| 参数名   | 类型                                                         | 必填 | 说明                       |
426
| -------- | ------------------------------------------------------------ | ---- | -------------------------- |
W
wusongqing 已提交
427
| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是   | 获取音频轨道信息回调方法。 |
Z
zengyawen 已提交
428

W
wusongqing 已提交
429
**示例:**
Z
zengyawen 已提交
430

431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448
```js
function printfDescription(obj) {
    for (let item in obj) {
        let property = obj[item];
        console.info('audio key is ' + item);
        console.info('audio value is ' + property);
    }
}

audioPlayer.getTrackDescription((error, arrlist) => {
    if (typeof (arrlist) != 'undefined') {
        for (let i = 0; i < arrlist.length; i++) {
            printfDescription(arrlist[i]);
        }
    } else {
        console.log(`audio getTrackDescription fail, error:${error.message}`);
    }
});
Z
zengyawen 已提交
449
```
450 451 452

### getTrackDescription<sup>8+</sup><a name=audioplayer_gettrackdescription2></a>

Z
zengyawen 已提交
453
getTrackDescription(): Promise<Array\<MediaDescription>>
454

455
通过Promise方式获取音频轨道信息。需在[dataLoad](#audioplayer_on)事件成功触发后,才能调用
B
bird_j 已提交
456

Z
zengyawen 已提交
457 458
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
459
**返回值:**
460

W
wusongqing 已提交
461
| 类型                                                   | 说明                            |
462
| ------------------------------------------------------ | ------------------------------- |
W
wusongqing 已提交
463
| Promise<Array<[MediaDescription](#mediadescription8)>> | 获取音频轨道信息Promise返回值。 |
464

W
wusongqing 已提交
465
**示例:**
466 467 468 469 470 471 472 473 474 475

```js
function printfDescription(obj) {
    for (let item in obj) {
        let property = obj[item];
        console.info('audio key is ' + item);
        console.info('audio value is ' + property);
    }
}

476
audioPlayer.getTrackDescription().then((arrlist) => {
477 478 479 480 481
    if (typeof (arrlist) != 'undefined') {
        arrayDescription = arrlist;
    } else {
        console.log('audio getTrackDescription fail');
    }
482 483 484 485
}).catch((error) => {
   console.info(`audio catchCallback, error:${error.message}`);
});

486 487 488
for (let i = 0; i < arrayDescription.length; i++) {
    printfDescription(arrayDescription[i]);
}
Z
zengyawen 已提交
489 490
```

491
### on('bufferingUpdate')<sup>8+</sup>
Z
zengyawen 已提交
492

493
on(type: 'bufferingUpdate', callback: (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void): void
Z
zengyawen 已提交
494

W
wusongqing 已提交
495
开始订阅音频缓存更新事件。
Z
zengyawen 已提交
496

Z
zengyawen 已提交
497 498
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
499
**参数:**
B
bird_j 已提交
500

Z
zengyawen 已提交
501 502 503 504
| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 音频缓存事件回调类型,支持的事件:'bufferingUpdate'。        |
| callback | function | 是   | 音频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时,value值有效,否则固定为0。 |
Z
zengyawen 已提交
505

W
wusongqing 已提交
506
**示例:**
Z
zengyawen 已提交
507

508 509 510 511 512
```js
audioPlayer.on('bufferingUpdate', (infoType, value) => {
    console.log('audio bufferingInfo type: ' + infoType);
    console.log('audio bufferingInfo value: ' + value);
});
Z
zengyawen 已提交
513
```
514

Z
zengyawen 已提交
515
 ### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')<a name = audioplayer_on></a>
516 517 518

on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void): void

W
wusongqing 已提交
519
开始订阅音频播放事件。
B
bird_j 已提交
520

Z
zengyawen 已提交
521 522
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
523
**参数:**
524

W
wusongqing 已提交
525
| 参数名   | 类型       | 必填 | 说明                                                         |
526
| -------- | ---------- | ---- | ------------------------------------------------------------ |
Z
zengyawen 已提交
527
| 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)调用,播放音量改变后触发该事件。 |
W
wusongqing 已提交
528
| callback | () => void | 是   | 播放事件回调方法。                                           |
529

W
wusongqing 已提交
530
**示例:**
531 532

```js
W
wusongqing 已提交
533 534
let audioPlayer = media.createAudioPlayer();  //创建一个音频播放实例
audioPlayer.on('dataLoad', () => {            //设置'dataLoad'事件回调,src属性设置成功后,触发此回调
A
tab  
abc12133 已提交
535
    console.info('audio set source success');
W
wusongqing 已提交
536
    audioPlayer.play();                       //开始播放,并触发'play'事件回调
537
});
W
wusongqing 已提交
538
audioPlayer.on('play', () => {                //设置'play'事件回调
A
tab  
abc12133 已提交
539
    console.info('audio play success');
W
wusongqing 已提交
540
    audioPlayer.seek(30000);                  //调用seek方法,并触发'timeUpdate'事件回调
541
});
W
wusongqing 已提交
542
audioPlayer.on('pause', () => {               //设置'pause'事件回调
A
tab  
abc12133 已提交
543
    console.info('audio pause success');
W
wusongqing 已提交
544
    audioPlayer.stop();                       //停止播放,并触发'stop'事件回调
545
});
W
wusongqing 已提交
546
audioPlayer.on('reset', () => {               //设置'reset'事件回调
A
tab  
abc12133 已提交
547
    console.info('audio reset success');
W
wusongqing 已提交
548
    audioPlayer.release();                    //释放播放实例资源
549 550
    audioPlayer = undefined;
});
W
wusongqing 已提交
551
audioPlayer.on('timeUpdate', (seekDoneTime) => {  //设置'timeUpdate'事件回调
A
tab  
abc12133 已提交
552
    if (typeof(seekDoneTime) == "undefined") {
553 554 555 556
        console.info('audio seek fail');
        return;
    }
    console.info('audio seek success, and seek time is ' + seekDoneTime);
W
wusongqing 已提交
557
    audioPlayer.setVolume(0.5);                //设置音量为50%,并触发'volumeChange'事件回调
558
});
W
wusongqing 已提交
559
audioPlayer.on('volumeChange', () => {         //设置'volumeChange'事件回调
A
tab  
abc12133 已提交
560
    console.info('audio volumeChange success');
W
wusongqing 已提交
561
    audioPlayer.pause();                       //暂停播放,并触发'pause'事件回调
562
});
W
wusongqing 已提交
563
audioPlayer.on('finish', () => {               //设置'finish'事件回调
A
tab  
abc12133 已提交
564
    console.info('audio play finish');
W
wusongqing 已提交
565
    audioPlayer.stop();                        //停止播放,并触发'stop'事件回调
566
});
W
wusongqing 已提交
567
audioPlayer.on('error', (error) => {           //设置'error'事件回调
A
tab  
abc12133 已提交
568
    console.info(`audio error called, errName is ${error.name}`);
569 570
    console.info(`audio error called, errCode is ${error.code}`);
    console.info(`audio error called, errMessage is ${error.message}`);
Z
zengyawen 已提交
571
});
Z
zengyawen 已提交
572 573 574

// 用户选择视频设置fd(本地播放)
let fdPath = 'fd://'
575 576
// path路径的码流可通过"hdc file send D:\xxx\01.mp3 /data/accounts/account_0/appdata" 命令,将其推送到设备上
let path = '/data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3';
577
fileIO.open(path).then(fdNumber) => {
Z
zengyawen 已提交
578
   fdPath = fdPath + '' + fdNumber;
JoyboyCZ's avatar
JoyboyCZ 已提交
579
   console.info('open fd succsess fd is' + fdPath);
Z
zengyawen 已提交
580 581
}, (err) => {
   console.info('open fd failed err is' + err);
582
}).catch((err) => {
Z
zengyawen 已提交
583 584 585
   console.info('open fd failed err is' + err);
});
audioPlayer.src = fdPath;  //设置src属性,并触发'dataLoad'事件回调
Z
zengyawen 已提交
586 587 588 589 590
```

### on('timeUpdate')

on(type: 'timeUpdate', callback: Callback\<number>): void
Z
zengyawen 已提交
591

W
wusongqing 已提交
592
开始订阅音频播放[seek()](#seek)时间更新事件。
Z
zengyawen 已提交
593

Z
zengyawen 已提交
594 595
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
596
**参数:**
B
bird_j 已提交
597

W
wusongqing 已提交
598
| 参数名   | 类型              | 必填 | 说明                                                         |
599
| -------- | ----------------- | ---- | ------------------------------------------------------------ |
Z
zengyawen 已提交
600
| type     | string            | 是   | 播放事件回调类型,支持的事件包括:'timeUpdate'。<br>- 'timeUpdate':[seek()](#audioplayer_seek)调用完成,触发该事件。 |
W
wusongqing 已提交
601
| callback | Callback\<number> | 是   | 播放事件回调方法。回调方法入参为成功seek的时间。             |
Z
zengyawen 已提交
602

W
wusongqing 已提交
603
**示例:**
Z
zengyawen 已提交
604

605
```js
W
wusongqing 已提交
606
audioPlayer.on('timeUpdate', (seekDoneTime) => {    //设置'timeUpdate'事件回调
607 608 609 610 611
    if (typeof (seekDoneTime) == 'undefined') {
        console.info('audio seek fail');
        return;
    }
    console.log('audio seek success. seekDoneTime: ' + seekDoneTime);
Z
zengyawen 已提交
612
});
W
wusongqing 已提交
613
audioPlayer.seek(30000);    //seek到30000ms的位置
Z
zengyawen 已提交
614 615 616 617 618
```

### on('error')

on(type: 'error', callback: ErrorCallback): void
Z
zengyawen 已提交
619

W
wusongqing 已提交
620
开始订阅音频播放错误事件。
B
bird_j 已提交
621

Z
zengyawen 已提交
622 623
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer

W
wusongqing 已提交
624
**参数:**
Z
zengyawen 已提交
625

W
wusongqing 已提交
626
| 参数名   | 类型          | 必填 | 说明                                                         |
627
| -------- | ------------- | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
628 629
| type     | string        | 是   | 播放错误事件回调类型,支持的事件包括:'error'。<br>- 'error':音频播放中发生错误,触发该事件。 |
| callback | ErrorCallback | 是   | 播放错误事件回调方法。                                       |
Z
zengyawen 已提交
630

W
wusongqing 已提交
631
**示例:**
Z
zengyawen 已提交
632

633
```js
W
wusongqing 已提交
634
audioPlayer.on('error', (error) => {      //设置'error'事件回调
A
tab  
abc12133 已提交
635
    console.info(`audio error called, errName is ${error.name}`);      //打印错误类型名称
W
wusongqing 已提交
636 637
    console.info(`audio error called, errCode is ${error.code}`);      //打印错误码
    console.info(`audio error called, errMessage is ${error.message}`);//打印错误类型详细描述
Z
zengyawen 已提交
638
});
W
wusongqing 已提交
639
audioPlayer.setVolume(3);  //设置volume为无效值,触发'error'事件
Z
zengyawen 已提交
640 641 642
```

## AudioState
Z
zengyawen 已提交
643

W
wusongqing 已提交
644
音频播放的状态机。可通过state属性获取当前状态。
645

Z
zengyawen 已提交
646 647
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.AudioPlayer。

W
wusongqing 已提交
648 649 650 651 652 653 654
| 名称               | 类型   | 描述           |
| ------------------ | ------ | -------------- |
| idle               | string | 音频播放空闲。 |
| playing            | string | 音频正在播放。 |
| paused             | string | 音频暂停播放。 |
| stopped            | string | 音频播放停止。 |
| error<sup>8+</sup> | string | 错误状态。     |
655

656 657
## VideoPlayer<sup>8+</sup>

Z
zengyawen 已提交
658
视频播放管理类,用于管理和播放视频媒体。在调用VideoPlayer的方法前,需要先通过[createVideoPlayer()](#mediacreatevideoplayer8)构建一个[VideoPlayer](#videoplayer8)实例。
659

W
wusongqing 已提交
660
视频播放demo可参考:[视频播放开发指导](../../media/video-playback.md)
661

Z
zengyawen 已提交
662
### 属性<a name=videoplayer_属性></a>
663

Z
zengyawen 已提交
664 665 666 667
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoPlayer。

| 名称                     | 类型                               | 可读 | 可写 | 说明                                                         |
| ------------------------ | ---------------------------------- | ---- | ---- | ------------------------------------------------------------ |
Z
zengyawen 已提交
668
| url<sup>8+</sup>         | string                             | 是   | 是   | 视频媒体URL,支持当前主流的视频格式(mp4、mpeg-ts、webm、mkv)。<br>**支持路径示例**<br>1. fd类型播放:fd://xx<br>![](figures/zh-cn_image_url.png)<br>2、http网络播放: http://xx<br/>3、hls网络播放路径:开发中<br/>**注意事项**<br>使用媒体素材需要获取读权限,否则无法正常播放。 |
Z
zengyawen 已提交
669 670 671 672 673 674
| loop<sup>8+</sup>        | boolean                            | 是   | 是   | 视频循环播放属性,设置为'true'表示循环播放。                 |
| currentTime<sup>8+</sup> | number                             | 是   | 否   | 视频的当前播放位置。                                         |
| duration<sup>8+</sup>    | number                             | 是   | 否   | 视频时长,返回-1表示直播模式。                               |
| state<sup>8+</sup>       | [VideoPlayState](#videoplaystate8) | 是   | 否   | 视频播放的状态。                                             |
| width<sup>8+</sup>       | number                             | 是   | 否   | 视频宽。                                                     |
| height<sup>8+</sup>      | number                             | 是   | 否   | 视频高。                                                     |
675 676 677 678 679

### setDisplaySurface<sup>8+</sup>

setDisplaySurface(surfaceId: string, callback: AsyncCallback\<void>): void

W
wusongqing 已提交
680
通过回调方式设置SurfaceId。
B
bird_j 已提交
681

Z
zengyawen 已提交
682 683
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
684
**参数:**
685

W
wusongqing 已提交
686
| 参数名    | 类型     | 必填 | 说明                      |
687
| --------- | -------- | ---- | ------------------------- |
W
wusongqing 已提交
688 689
| surfaceId | string   | 是   | SurfaceId                 |
| callback  | function | 是   | 设置SurfaceId的回调方法。 |
690

W
wusongqing 已提交
691
**示例:**
692 693 694

```js
videoPlayer.setDisplaySurface(surfaceId, (err) => {
A
tab  
abc12133 已提交
695 696 697
    if (typeof (err) == 'undefined') {
        console.info('setDisplaySurface success!');
    } else {
698 699 700 701 702 703 704 705 706
        console.info('setDisplaySurface fail!');
    }
});
```

### setDisplaySurface<sup>8+</sup>

setDisplaySurface(surfaceId: string): Promise\<void>

W
wusongqing 已提交
707
通过Promise方式设置SurfaceId。
708

Z
zengyawen 已提交
709 710
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
711
**参数:**
B
bird_j 已提交
712

W
wusongqing 已提交
713
| 参数名    | 类型   | 必填 | 说明      |
714
| --------- | ------ | ---- | --------- |
W
wusongqing 已提交
715
| surfaceId | string | 是   | SurfaceId |
716

W
wusongqing 已提交
717
**返回值:**
718

W
wusongqing 已提交
719
| 类型          | 说明                           |
720
| ------------- | ------------------------------ |
W
wusongqing 已提交
721
| Promise<void> | 设置SurfaceId的Promise返回值。 |
722

W
wusongqing 已提交
723
**示例:**
724 725

```js
726
videoPlayer.setDisplaySurface(surfaceId).then(() => {
727
    console.info('setDisplaySurface success');
728 729 730
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
731 732 733 734 735 736
```

### prepare<sup>8+</sup>

prepare(callback: AsyncCallback\<void>): void

W
wusongqing 已提交
737
通过回调方式准备播放视频。
B
bird_j 已提交
738

Z
zengyawen 已提交
739 740
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
741
**参数:**
742

W
wusongqing 已提交
743
| 参数名   | 类型     | 必填 | 说明                     |
744
| -------- | -------- | ---- | ------------------------ |
W
wusongqing 已提交
745
| callback | function | 是   | 准备播放视频的回调方法。 |
746

W
wusongqing 已提交
747
**示例:**
748 749 750

```js
videoPlayer.prepare((err) => {
A
tab  
abc12133 已提交
751 752 753
    if (typeof (err) == 'undefined') {
        console.info('prepare success!');
    } else {
754 755 756 757 758 759 760 761 762
        console.info('prepare fail!');
    }
});
```

### prepare<sup>8+</sup>

prepare(): Promise\<void>

W
wusongqing 已提交
763
通过Promise方式准备播放视频。
764

Z
zengyawen 已提交
765 766
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
767
**返回值:**
B
bird_j 已提交
768

W
wusongqing 已提交
769
| 类型           | 说明                          |
770
| -------------- | ----------------------------- |
W
wusongqing 已提交
771
| Promise\<void> | 准备播放视频的Promise返回值。 |
772

W
wusongqing 已提交
773
**示例:**
774 775

```js
776
videoPlayer.prepare().then(() => {
777
    console.info('prepare success');
778 779 780
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
781 782 783 784 785 786
```

### play<sup>8+</sup>

play(callback: AsyncCallback\<void>): void;

W
wusongqing 已提交
787
通过回调方式开始播放视频。
B
bird_j 已提交
788

Z
zengyawen 已提交
789 790
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
791
**参数:**
792

W
wusongqing 已提交
793
| 参数名   | 类型     | 必填 | 说明                     |
794
| -------- | -------- | ---- | ------------------------ |
W
wusongqing 已提交
795
| callback | function | 是   | 开始播放视频的回调方法。 |
796

W
wusongqing 已提交
797
**示例:**
798 799 800

```js
videoPlayer.play((err) => {
A
tab  
abc12133 已提交
801 802 803
    if (typeof (err) == 'undefined') {
        console.info('play success!');
    } else {
804 805 806 807 808 809 810 811 812
        console.info('play fail!');
    }
});
```

### play<sup>8+</sup>

play(): Promise\<void>;

W
wusongqing 已提交
813
通过Promise方式开始播放视频。
814

Z
zengyawen 已提交
815 816
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
817
**返回值:**
B
bird_j 已提交
818

W
wusongqing 已提交
819
| 类型           | 说明                          |
820
| -------------- | ----------------------------- |
W
wusongqing 已提交
821
| Promise\<void> | 开始播放视频的Promise返回值。 |
822

W
wusongqing 已提交
823
**示例:**
824 825

```js
826
videoPlayer.play().then(() => {
827
    console.info('play success');
828 829 830
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
831 832 833 834 835 836
```

### pause<sup>8+</sup>

pause(callback: AsyncCallback\<void>): void

W
wusongqing 已提交
837
通过回调方式暂停播放视频。
B
bird_j 已提交
838

Z
zengyawen 已提交
839 840
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
841
**参数:**
842

W
wusongqing 已提交
843
| 参数名   | 类型     | 必填 | 说明                     |
844
| -------- | -------- | ---- | ------------------------ |
W
wusongqing 已提交
845
| callback | function | 是   | 暂停播放视频的回调方法。 |
846

W
wusongqing 已提交
847
**示例:**
848 849 850

```js
videoPlayer.pause((err) => {
A
tab  
abc12133 已提交
851 852 853
    if (typeof (err) == 'undefined') {
        console.info('pause success!');
    } else {
854 855 856 857 858 859 860 861 862
        console.info('pause fail!');
    }
});
```

### pause<sup>8+</sup>

pause(): Promise\<void>

W
wusongqing 已提交
863
通过Promise方式暂停播放视频。
864

Z
zengyawen 已提交
865 866
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
867
**返回值:**
B
bird_j 已提交
868

W
wusongqing 已提交
869
| 类型           | 说明                          |
870
| -------------- | ----------------------------- |
W
wusongqing 已提交
871
| Promise\<void> | 暂停播放视频的Promise返回值。 |
872

W
wusongqing 已提交
873
**示例:**
874 875

```js
876
videoPlayer.pause().then(() => {
877
    console.info('pause success');
878 879 880
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
881 882 883 884 885 886
```

### stop<sup>8+</sup>

stop(callback: AsyncCallback\<void>): void

W
wusongqing 已提交
887
通过回调方式停止播放视频。
B
bird_j 已提交
888

Z
zengyawen 已提交
889 890
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
891
**参数:**
892

W
wusongqing 已提交
893
| 参数名   | 类型     | 必填 | 说明                     |
894
| -------- | -------- | ---- | ------------------------ |
W
wusongqing 已提交
895
| callback | function | 是   | 停止播放视频的回调方法。 |
896

W
wusongqing 已提交
897
**示例:**
898 899 900

```js
videoPlayer.stop((err) => {
A
tab  
abc12133 已提交
901 902 903
    if (typeof (err) == 'undefined') {
        console.info('stop success!');
    } else {
904 905 906 907 908 909 910 911 912
        console.info('stop fail!');
    }
});
```

### stop<sup>8+</sup>

stop(): Promise\<void>

W
wusongqing 已提交
913
通过Promise方式停止播放视频。
B
bird_j 已提交
914

Z
zengyawen 已提交
915 916
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
917
**返回值:**
918

W
wusongqing 已提交
919
| 类型           | 说明                          |
920
| -------------- | ----------------------------- |
W
wusongqing 已提交
921
| Promise\<void> | 停止播放视频的Promise返回值。 |
922

W
wusongqing 已提交
923
**示例:**
924 925

```js
926
videoPlayer.stop().then(() => {
927
    console.info('stop success');
928 929 930
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
931 932 933 934 935 936
```

### reset<sup>8+</sup>

reset(callback: AsyncCallback\<void>): void

W
wusongqing 已提交
937
通过回调方式切换播放视频。
938

Z
zengyawen 已提交
939 940
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
941
**参数:**
B
bird_j 已提交
942

W
wusongqing 已提交
943
| 参数名   | 类型     | 必填 | 说明                     |
944
| -------- | -------- | ---- | ------------------------ |
W
wusongqing 已提交
945
| callback | function | 是   | 切换播放视频的回调方法。 |
946

W
wusongqing 已提交
947
**示例:**
948 949 950

```js
videoPlayer.reset((err) => {
A
tab  
abc12133 已提交
951 952 953
    if (typeof (err) == 'undefined') {
        console.info('reset success!');
    } else {
954 955 956 957 958 959 960 961 962
        console.info('reset fail!');
    }
});
```

### reset<sup>8+</sup>

reset(): Promise\<void>

W
wusongqing 已提交
963
通过Promise方式切换播放视频。
B
bird_j 已提交
964

Z
zengyawen 已提交
965 966
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
967
**返回值:**
968

W
wusongqing 已提交
969
| 类型           | 说明                          |
970
| -------------- | ----------------------------- |
W
wusongqing 已提交
971
| Promise\<void> | 切换播放视频的Promise返回值。 |
972

W
wusongqing 已提交
973
**示例:**
974 975

```js
976
videoPlayer.reset().then(() => {
977
    console.info('reset success');
978 979 980
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
981 982 983 984 985 986
```

### seek<sup>8+</sup>

seek(timeMs: number, callback: AsyncCallback\<number>): void

W
wusongqing 已提交
987
通过回调方式跳转到指定播放位置,默认跳转到指定时间点的下一个关键帧。
988

Z
zengyawen 已提交
989 990
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
991
**参数:**
B
bird_j 已提交
992

Z
zengyawen 已提交
993 994 995 996
| 参数名   | 类型     | 必填 | 说明                                 |
| -------- | -------- | ---- | ------------------------------------ |
| timeMs   | number   | 是   | 指定的跳转时间节点,单位毫秒(ms)。 |
| callback | function | 是   | 跳转到指定播放位置的回调方法。       |
997

W
wusongqing 已提交
998
**示例:**
999 1000 1001

```js
videoPlayer.seek((seekTime, err) => {
A
tab  
abc12133 已提交
1002 1003 1004
    if (typeof (err) == 'undefined') {
        console.info('seek success!');
    } else {
1005 1006 1007 1008 1009 1010 1011 1012 1013
        console.info('seek fail!');
    }
});
```

### seek<sup>8+</sup>

seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\<number>): void

W
wusongqing 已提交
1014
通过回调方式跳转到指定播放位置。
B
bird_j 已提交
1015

Z
zengyawen 已提交
1016 1017
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1018
**参数:**
1019

Z
zengyawen 已提交
1020 1021 1022 1023 1024
| 参数名   | 类型                   | 必填 | 说明                                 |
| -------- | ---------------------- | ---- | ------------------------------------ |
| timeMs   | number                 | 是   | 指定的跳转时间节点,单位毫秒(ms)。 |
| mode     | [SeekMode](#seekmode8) | 是   | 跳转模式。                           |
| callback | function               | 是   | 跳转到指定播放位置的回调方法。       |
1025

W
wusongqing 已提交
1026
**示例:**
1027 1028 1029

```js
videoPlayer.seek((seekTime, seekMode, err) => {
A
tab  
abc12133 已提交
1030 1031 1032
    if (typeof (err) == 'undefined') {
        console.info('seek success!');
    } else {
1033 1034 1035 1036 1037 1038 1039 1040 1041
        console.info('seek fail!');
    }
});
```

### seek<sup>8+</sup>

seek(timeMs: number, mode?:SeekMode): Promise\<number>

W
wusongqing 已提交
1042
通过Promise方式跳转到指定播放位置,如果没有设置mode则跳转到指定时间点的下一个关键帧。
1043

Z
zengyawen 已提交
1044 1045
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1046
**参数:**
B
bird_j 已提交
1047

Z
zengyawen 已提交
1048 1049 1050 1051
| 参数名 | 类型                   | 必填 | 说明                                 |
| ------ | ---------------------- | ---- | ------------------------------------ |
| timeMs | number                 | 是   | 指定的跳转时间节点,单位毫秒(ms)。 |
| mode   | [SeekMode](#seekmode8) | 否   | 跳转模式。                           |
1052

W
wusongqing 已提交
1053
**返回值:**
1054

W
wusongqing 已提交
1055
| 类型           | 说明                                |
1056
| -------------- | ----------------------------------- |
W
wusongqing 已提交
1057
| Promise\<void> | 跳转到指定播放位置的Promise返回值。 |
1058

W
wusongqing 已提交
1059
**示例:**
1060 1061

```js
1062
videoPlayer.seek(seekTime).then((seekDoneTime) => { // seekDoneTime表示seek完成后的时间点
1063
    console.info('seek success');
1064 1065 1066
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
1067

1068
videoPlayer.seek(seekTime, seekMode).then((seekDoneTime) => {
1069
    console.info('seek success');
1070 1071 1072
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
1073 1074 1075 1076 1077 1078
```

### setVolume<sup>8+</sup>

setVolume(vol: number, callback: AsyncCallback\<void>): void

W
wusongqing 已提交
1079
通过回调方式设置音量。
B
bird_j 已提交
1080

Z
zengyawen 已提交
1081 1082
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1083
**参数:**
1084

W
wusongqing 已提交
1085
| 参数名   | 类型     | 必填 | 说明                                                         |
1086
| -------- | -------- | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
1087 1088
| vol      | number   | 是   | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |
| callback | function | 是   | 设置音量的回调方法。                                         |
1089

W
wusongqing 已提交
1090
**示例:**
1091 1092 1093

```js
videoPlayer.setVolume((vol, err) => {
A
tab  
abc12133 已提交
1094 1095 1096
    if (typeof (err) == 'undefined') {
        console.info('setVolume success!');
    } else {
1097 1098 1099 1100 1101 1102 1103 1104 1105
        console.info('setVolume fail!');
    }
});
```

### setVolume<sup>8+</sup>

setVolume(vol: number): Promise\<void>

W
wusongqing 已提交
1106
通过Promise方式设置音量。
1107

Z
zengyawen 已提交
1108 1109
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1110
**参数:**
B
bird_j 已提交
1111

W
wusongqing 已提交
1112
| 参数名 | 类型   | 必填 | 说明                                                         |
1113
| ------ | ------ | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
1114
| vol    | number | 是   | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |
1115

W
wusongqing 已提交
1116
**返回值:**
1117

W
wusongqing 已提交
1118
| 类型           | 说明                      |
1119
| -------------- | ------------------------- |
W
wusongqing 已提交
1120
| Promise\<void> | 设置音量的Promise返回值。 |
1121

W
wusongqing 已提交
1122
**示例:**
1123 1124

```js
1125
videoPlayer.setVolume(vol).then() => {
1126
    console.info('setVolume success');
1127 1128 1129
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
1130 1131 1132 1133 1134 1135
```

### release<sup>8+</sup>

release(callback: AsyncCallback\<void>): void

W
wusongqing 已提交
1136
通过回调方式释放视频资源。
B
bird_j 已提交
1137

Z
zengyawen 已提交
1138 1139
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1140
**参数:**
1141

W
wusongqing 已提交
1142
| 参数名   | 类型     | 必填 | 说明                     |
1143
| -------- | -------- | ---- | ------------------------ |
W
wusongqing 已提交
1144
| callback | function | 是   | 释放视频资源的回调方法。 |
1145

W
wusongqing 已提交
1146
**示例:**
1147 1148 1149

```js
videoPlayer.release((err) => {
A
tab  
abc12133 已提交
1150 1151 1152
    if (typeof (err) == 'undefined') {
        console.info('release success!');
    } else {
1153 1154 1155 1156 1157 1158 1159 1160 1161
        console.info('release fail!');
    }
});
```

### release<sup>8+</sup>

release(): Promise\<void>

W
wusongqing 已提交
1162
通过Promise方式释放视频资源。
B
bird_j 已提交
1163

Z
zengyawen 已提交
1164 1165
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1166
**返回值:**
1167

W
wusongqing 已提交
1168
| 类型           | 说明                          |
1169
| -------------- | ----------------------------- |
W
wusongqing 已提交
1170
| Promise\<void> | 释放视频资源的Promise返回值。 |
1171

W
wusongqing 已提交
1172
**示例:**
1173 1174

```js
1175
videoPlayer.release().then() => {
1176
    console.info('release success');
1177 1178 1179
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
1180 1181 1182 1183
```

### getTrackDescription<sup>8+</sup>

Z
zengyawen 已提交
1184
getTrackDescription(callback: AsyncCallback<Array\<MediaDescription>>): void
1185

W
wusongqing 已提交
1186
通过回调方式获取视频轨道信息。
1187

Z
zengyawen 已提交
1188 1189
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1190
**参数:**
B
bird_j 已提交
1191

Z
zengyawen 已提交
1192 1193 1194
| 参数名   | 类型                                                         | 必填 | 说明                       |
| -------- | ------------------------------------------------------------ | ---- | -------------------------- |
| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是   | 获取视频轨道信息回调方法。 |
1195

W
wusongqing 已提交
1196
**示例:**
1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219

```js
function printfDescription(obj) {
    for (let item in obj) {
        let property = obj[item];
        console.info('video key is ' + item);
        console.info('video value is ' + property);
    }
}

videoPlayer.getTrackDescription((error, arrlist) => {
    if (typeof (arrlist) != 'undefined') {
        for (let i = 0; i < arrlist.length; i++) {
            printfDescription(arrlist[i]);
        }
    } else {
        console.log(`video getTrackDescription fail, error:${error.message}`);
    }
});
```

### getTrackDescription<sup>8+</sup>

Z
zengyawen 已提交
1220
getTrackDescription(): Promise<Array\<MediaDescription>>
1221

W
wusongqing 已提交
1222
通过Promise方式获取视频轨道信息。
B
bird_j 已提交
1223

Z
zengyawen 已提交
1224 1225
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1226
**返回值:**
1227

Z
zengyawen 已提交
1228 1229 1230
| 类型                                                   | 说明                            |
| ------------------------------------------------------ | ------------------------------- |
| Promise<Array<[MediaDescription](#mediadescription8)>> | 获取视频轨道信息Promise返回值。 |
1231

W
wusongqing 已提交
1232
**示例:**
1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243

```js
function printfDescription(obj) {
    for (let item in obj) {
        let property = obj[item];
        console.info('video key is ' + item);
        console.info('video value is ' + property);
    }
}

let arrayDescription;
1244
videoPlayer.getTrackDescription().then((arrlist) => {
1245 1246 1247 1248 1249
    if (typeof (arrlist) != 'undefined') {
        arrayDescription = arrlist;
    } else {
        console.log('video getTrackDescription fail');
    }
1250 1251 1252
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
1253 1254 1255 1256 1257 1258 1259 1260 1261
for (let i = 0; i < arrayDescription.length; i++) {
    printfDescription(arrayDescription[i]);
}
```

### setSpeed<sup>8+</sup>

setSpeed(speed:number, callback: AsyncCallback\<number>): void

W
wusongqing 已提交
1262
通过回调方式设置播放速度。
1263

Z
zengyawen 已提交
1264 1265
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1266
**参数:**
B
bird_j 已提交
1267

W
wusongqing 已提交
1268
| 参数名   | 类型     | 必填 | 说明                                                       |
1269
| -------- | -------- | ---- | ---------------------------------------------------------- |
W
wusongqing 已提交
1270 1271
| speed    | number   | 是   | 指定播放视频速度,具体见[PlaybackSpeed](#playbackspeed8)。 |
| callback | function | 是   | 设置播放速度的回调方法。                                   |
1272

W
wusongqing 已提交
1273
**示例:**
1274 1275 1276

```js
videoPlayer.setSpeed((speed:number, err) => {
A
tab  
abc12133 已提交
1277 1278 1279
    if (typeof (err) == 'undefined') {
        console.info('setSpeed success!');
    } else {
1280 1281 1282 1283 1284 1285 1286 1287 1288
        console.info('setSpeed fail!');
    }
});
```

### setSpeed<sup>8+</sup>

setSpeed(speed:number): Promise\<number>

W
wusongqing 已提交
1289
通过Promise方式设置播放速度。
B
bird_j 已提交
1290

Z
zengyawen 已提交
1291 1292
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1293
**参数:**
1294

W
wusongqing 已提交
1295
| 参数名 | 类型   | 必填 | 说明                                                       |
1296
| ------ | ------ | ---- | ---------------------------------------------------------- |
W
wusongqing 已提交
1297
| speed  | number | 是   | 指定播放视频速度,具体见[PlaybackSpeed](#playbackspeed8)。 |
1298

Z
zengyawen 已提交
1299 1300 1301 1302 1303 1304
**返回值:**

| 类型             | 说明                      |
| ---------------- | ------------------------- |
| Promise\<number> | 通过Promise获取设置结果。 |

W
wusongqing 已提交
1305
**示例:**
1306 1307

```js
1308
videoPlayer.setSpeed(speed).then() => {
1309
    console.info('setSpeed success');
1310 1311 1312
}).catch((error) => {
   console.info(`video catchCallback, error:${error.message}`);
});
1313 1314 1315 1316 1317 1318
```

### on('playbackCompleted')<sup>8+</sup>

on(type: 'playbackCompleted', callback: Callback\<void>): void

W
wusongqing 已提交
1319
开始监听视频播放完成事件。
1320

Z
zengyawen 已提交
1321 1322
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1323
**参数:**
B
bird_j 已提交
1324

W
wusongqing 已提交
1325
| 参数名   | 类型     | 必填 | 说明                                                        |
1326
| -------- | -------- | ---- | ----------------------------------------------------------- |
W
wusongqing 已提交
1327 1328
| type     | string   | 是   | 视频播放完成事件回调类型,支持的事件:'playbackCompleted'。 |
| callback | function | 是   | 视频播放完成事件回调方法。                                  |
1329

W
wusongqing 已提交
1330
**示例:**
1331 1332 1333

```js
videoPlayer.on('playbackCompleted', () => {
A
tab  
abc12133 已提交
1334
    console.info('playbackCompleted success!');
1335 1336 1337 1338 1339 1340 1341
});
```

### on('bufferingUpdate')<sup>8+</sup>

on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void

W
wusongqing 已提交
1342
开始监听视频缓存更新事件。
B
bird_j 已提交
1343

Z
zengyawen 已提交
1344 1345
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1346
**参数:**
1347

W
wusongqing 已提交
1348
| 参数名   | 类型     | 必填 | 说明                                                         |
1349
| -------- | -------- | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
1350 1351
| type     | string   | 是   | 视频缓存事件回调类型,支持的事件:'bufferingUpdate'。        |
| callback | function | 是   | 视频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时,value值有效,否则固定为0。 |
1352

W
wusongqing 已提交
1353
**示例:**
1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365

```js
videoPlayer.on('bufferingUpdate', (infoType, value) => {
    console.log('video bufferingInfo type: ' + infoType);
    console.log('video bufferingInfo value: ' + value);
});
```

### on('startRenderFrame')<sup>8+</sup>

on(type: 'startRenderFrame', callback: Callback\<void>): void

W
wusongqing 已提交
1366
开始监听视频播放首帧送显上报事件。
1367

Z
zengyawen 已提交
1368 1369
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1370
**参数:**
B
bird_j 已提交
1371

Z
zengyawen 已提交
1372 1373 1374 1375
| 参数名   | 类型            | 必填 | 说明                                                         |
| -------- | --------------- | ---- | ------------------------------------------------------------ |
| type     | string          | 是   | 视频播放首帧送显上报事件回调类型,支持的事件:'startRenderFrame'。 |
| callback | Callback\<void> | 是   | 视频播放首帧送显上报事件回调方法。                           |
1376

W
wusongqing 已提交
1377
**示例:**
1378 1379 1380

```js
videoPlayer.on('startRenderFrame', () => {
A
tab  
abc12133 已提交
1381
    console.info('startRenderFrame success!');
1382 1383 1384 1385 1386 1387 1388
});
```

### on('videoSizeChanged')<sup>8+</sup>

on(type: 'videoSizeChanged', callback: (width: number, height: number) => void): void

W
wusongqing 已提交
1389
开始监听视频播放宽高变化事件。
B
bird_j 已提交
1390

Z
zengyawen 已提交
1391 1392
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1393
**参数:**
1394

W
wusongqing 已提交
1395
| 参数名   | 类型     | 必填 | 说明                                                         |
1396
| -------- | -------- | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
1397 1398
| type     | string   | 是   | 视频播放宽高变化事件回调类型,支持的事件:'videoSizeChanged'。 |
| callback | function | 是   | 视频播放宽高变化事件回调方法,width表示宽,height表示高。    |
1399

W
wusongqing 已提交
1400
**示例:**
1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412

```js
videoPlayer.on('videoSizeChanged', (width, height) => {
    console.log('video width is: ' + width);
    console.log('video height is: ' + height);
});
```

### on('error')<sup>8+</sup>

on(type: 'error', callback: ErrorCallback): void

W
wusongqing 已提交
1413
开始监听视频播放错误事件。
B
bird_j 已提交
1414

Z
zengyawen 已提交
1415 1416
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

W
wusongqing 已提交
1417
**参数:**
1418

Z
zengyawen 已提交
1419 1420 1421 1422
| 参数名   | 类型          | 必填 | 说明                                                         |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type     | string        | 是   | 播放错误事件回调类型,支持的事件包括:'error'。<br>- 'error':视频播放中发生错误,触发该事件。 |
| callback | ErrorCallback | 是   | 播放错误事件回调方法。                                       |
1423

W
wusongqing 已提交
1424
**示例:**
1425 1426

```js
W
wusongqing 已提交
1427
videoPlayer.on('error', (error) => {      // 设置'error'事件回调
A
tab  
abc12133 已提交
1428
    console.info(`video error called, errName is ${error.name}`);      // 打印错误类型名称
W
wusongqing 已提交
1429 1430
    console.info(`video error called, errCode is ${error.code}`);      // 打印错误码
    console.info(`video error called, errMessage is ${error.message}`);// 打印错误类型详细描述
1431
});
W
wusongqing 已提交
1432
videoPlayer.setVolume(3);  //设置volume为无效值,触发'error'事件
1433 1434 1435 1436
```

## VideoPlayState<sup>8+</sup>

W
wusongqing 已提交
1437
视频播放的状态机,可通过state属性获取当前状态。
1438

Z
zengyawen 已提交
1439 1440
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoPlayer。

W
wusongqing 已提交
1441 1442 1443 1444 1445 1446 1447 1448
| 名称     | 类型   | 描述           |
| -------- | ------ | -------------- |
| idle     | string | 视频播放空闲。 |
| prepared | string | 视频播放准备。 |
| playing  | string | 视频正在播放。 |
| paused   | string | 视频暂停播放。 |
| stopped  | string | 视频播放停止。 |
| error    | string | 错误状态。     |
1449 1450 1451

## SeekMode<sup>8+</sup>

W
wusongqing 已提交
1452
视频播放的Seek模式枚举,可通过seek方法作为参数传递下去。
1453

Z
zengyawen 已提交
1454 1455 1456 1457 1458 1459
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。

| 名称           | 值   | 描述                                                         |
| -------------- | ---- | ------------------------------------------------------------ |
| SEEK_NEXT_SYNC | 0    | 表示跳转到指定时间点的下一个关键帧,建议向后快进的时候用这个枚举值。 |
| SEEK_PREV_SYNC | 1    | 表示跳转到指定时间点的上一个关键帧,建议向前快进的时候用这个枚举值。 |
1460 1461 1462

## PlaybackSpeed<sup>8+</sup>

W
wusongqing 已提交
1463
视频播放的倍速枚举,可通过setSpeed方法作为参数传递下去。
1464

Z
zengyawen 已提交
1465 1466
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoPlayer。

W
wusongqing 已提交
1467 1468 1469 1470 1471 1472 1473
| 名称                 | 值   | 描述                           |
| -------------------- | ---- | ------------------------------ |
| SPEED_FORWARD_0_75_X | 0    | 表示视频播放正常播速的0.75倍。 |
| SPEED_FORWARD_1_00_X | 1    | 表示视频播放正常播速。         |
| SPEED_FORWARD_1_25_X | 2    | 表示视频播放正常播速的1.25倍。 |
| SPEED_FORWARD_1_75_X | 3    | 表示视频播放正常播速的1.75倍。 |
| SPEED_FORWARD_2_00_X | 4    | 表示视频播放正常播速的2.00倍。 |
1474

1475 1476
## MediaDescription<sup>8+</sup>

Z
zengyawen 已提交
1477
### [key : string] : Object
Z
zengyawen 已提交
1478

Z
zengyawen 已提交
1479 1480 1481
通过key-value方式获取媒体信息。

**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。
1482

W
wusongqing 已提交
1483
| 名称  | 类型   | 说明                                                         |
1484
| ----- | ------ | ------------------------------------------------------------ |
W
wusongqing 已提交
1485 1486
| key   | string | 通过key值获取对应的value。key值具体可见[MediaDescriptionKey](#mediadescriptionkey8)。 |
| value | any    | 对应key值得value。其类型可为任意类型,具体key对应value的类型可参考[MediaDescriptionKey](#mediadescriptionkey8)的描述信息。 |
1487

W
wusongqing 已提交
1488
**示例:**
1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499

```js
function printfItemDescription(obj, key) {
    let property = obj[key];
    console.info('audio key is ' + key);
    console.info('audio value is ' + property);
}

audioPlayer.getTrackDescription((error, arrlist) => {
    if (typeof (arrlist) != 'undefined') {
        for (let i = 0; i < arrlist.length; i++) {
W
wusongqing 已提交
1500
            printfItemDescription(arrlist[i], MD_KEY_TRACK_TYPE);  //打印出每条轨道MD_KEY_TRACK_TYPE的值
1501 1502 1503 1504 1505 1506
        }
    } else {
        console.log(`audio getTrackDescription fail, error:${error.message}`);
    }
});
```
Z
zengyawen 已提交
1507 1508 1509

## AudioRecorder

Z
zengyawen 已提交
1510
音频录制管理类,用于录制音频媒体。在调用AudioRecorder的方法前,需要先通过[createAudioRecorder()](#mediacreateaudiorecorder) 构建一个[AudioRecorder](#audiorecorder)实例。
Z
zengyawen 已提交
1511

W
wusongqing 已提交
1512
音频录制demo可参考:[音频录制开发指导](../../media/audio-recorder.md)
1513 1514

### prepare<a name=audiorecorder_prepare></a>
Z
zengyawen 已提交
1515 1516 1517

prepare(config: AudioRecorderConfig): void

W
wusongqing 已提交
1518
录音准备。
Z
zengyawen 已提交
1519

Z
zengyawen 已提交
1520 1521 1522 1523
**需要权限:** ohos.permission.MICROPHONE

**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder

W
wusongqing 已提交
1524
**参数:**
B
bird_j 已提交
1525

W
wusongqing 已提交
1526
| 参数名 | 类型                                        | 必填 | 说明                                                         |
Z
zengyawen 已提交
1527
| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
1528
| config | [AudioRecorderConfig](#audiorecorderconfig) | 是   | 配置录音的相关参数,包括音频输出URI、[编码格式](#audioencoder)、采样率、声道数、[输出格式](#audiooutputformat)等。 |
Z
zengyawen 已提交
1529

W
wusongqing 已提交
1530
**示例:**
Z
zengyawen 已提交
1531

1532
```js
Z
zengyawen 已提交
1533
let audioRecorderConfig = {
1534
    audioEncoder : media.AudioEncoder.AAC_LC,
Z
zengyawen 已提交
1535 1536 1537
    audioEncodeBitRate : 22050,
    audioSampleRate : 22050,
    numberOfChannels : 2,
1538
    format : media.AudioOutputFormat.AAC_ADTS,
Z
zengyawen 已提交
1539
    uri : 'fd://1',       // 文件需先由调用者创建,并给予适当的权限
1540
    location : { latitude : 30, longitude : 130},
Z
zengyawen 已提交
1541
}
W
wusongqing 已提交
1542
audioRecorder.on('prepare', () => {    //设置'prepare'事件回调
1543 1544
    console.log('prepare success');
});
B
bird_j 已提交
1545
audioRecorder.prepare(audioRecorderConfig);
Z
zengyawen 已提交
1546 1547 1548
```


1549
### start<a name=audiorecorder_start></a>
Z
zengyawen 已提交
1550 1551 1552

start(): void

W
wusongqing 已提交
1553
开始录制,需在[prepare](#audiorecorder_on)事件成功触发后,才能调用start方法。
B
bird_j 已提交
1554

Z
zengyawen 已提交
1555 1556
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder

W
wusongqing 已提交
1557
**示例:**
Z
zengyawen 已提交
1558

1559
```js
W
wusongqing 已提交
1560
audioRecorder.on('start', () => {    //设置'start'事件回调
1561 1562 1563
    console.log('audio recorder start success');
});
audioRecorder.start();
Z
zengyawen 已提交
1564
```
1565 1566 1567 1568 1569

### pause<a name=audiorecorder_pause></a>

pause():void

W
wusongqing 已提交
1570
暂停录制,需要在[start](#audiorecorder_on)事件成功触发后,才能调用pause方法。
1571

Z
zengyawen 已提交
1572 1573
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder

W
wusongqing 已提交
1574
**示例:**
1575 1576

```js
W
wusongqing 已提交
1577
audioRecorder.on('pause', () => {    //设置'pause'事件回调
1578 1579 1580 1581 1582 1583 1584 1585 1586
    console.log('audio recorder pause success');
});
audioRecorder.pause();
```

### resume<a name=audiorecorder_resume></a>

resume():void

Z
zengyawen 已提交
1587
恢复录制,需要在[pause](#audiorecorder_on)事件成功触发后,才能调用resume方法。
B
bird_j 已提交
1588

Z
zengyawen 已提交
1589 1590
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder

W
wusongqing 已提交
1591
**示例:**
1592 1593

```js
W
wusongqing 已提交
1594
audioRecorder.on('resume', () => {    //设置'resume'事件回调
1595 1596 1597
    console.log('audio recorder resume success');
});
audioRecorder.resume();
Z
zengyawen 已提交
1598 1599
```

1600
### stop<a name=audiorecorder_stop></a>
Z
zengyawen 已提交
1601 1602 1603

stop(): void

W
wusongqing 已提交
1604
停止录音。
Z
zengyawen 已提交
1605

Z
zengyawen 已提交
1606 1607
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder

W
wusongqing 已提交
1608
**示例:**
Z
zengyawen 已提交
1609

1610
```js
W
wusongqing 已提交
1611
audioRecorder.on('stop', () => {    //设置'stop'事件回调
1612 1613 1614
    console.log('audio recorder stop success');
});
audioRecorder.stop();
Z
zengyawen 已提交
1615 1616
```

1617
### release<a name=audiorecorder_release></a>
Z
zengyawen 已提交
1618 1619 1620

release(): void

W
wusongqing 已提交
1621
释放录音资源。
B
bird_j 已提交
1622

Z
zengyawen 已提交
1623 1624
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder

W
wusongqing 已提交
1625
**示例:**
Z
zengyawen 已提交
1626

1627
```js
W
wusongqing 已提交
1628
audioRecorder.on('release', () => {    //设置'release'事件回调
B
bird_j 已提交
1629 1630
    console.log('audio recorder release success');
});
1631 1632
audioRecorder.release();
audioRecorder = undefined;
Z
zengyawen 已提交
1633 1634
```

1635
### reset<a name=audiorecorder_reset></a>
Z
zengyawen 已提交
1636 1637 1638

reset(): void

W
wusongqing 已提交
1639
重置录音。
Z
zengyawen 已提交
1640

W
wusongqing 已提交
1641
进行重置录音之前,需要先调用[stop()](#audiorecorder_stop)停止录音。重置录音之后,需要调用[prepare()](#audiorecorder_prepare)设置录音参数项,才能再次进行录音。
B
bird_j 已提交
1642

Z
zengyawen 已提交
1643 1644
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder

W
wusongqing 已提交
1645
**示例:**
Z
zengyawen 已提交
1646

B
bird_j 已提交
1647
```js
W
wusongqing 已提交
1648
audioRecorder.on('reset', () => {    //设置'reset'事件回调
B
bird_j 已提交
1649 1650 1651
    console.log('audio recorder reset success');
});
audioRecorder.reset();
Z
zengyawen 已提交
1652 1653
```

B
bird_j 已提交
1654
### on('prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset')<a name=audiorecorder_on></a>
Z
zengyawen 已提交
1655

1656
on(type: 'prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset', callback: () => void): void
Z
zengyawen 已提交
1657

W
wusongqing 已提交
1658
开始订阅音频录制事件。
Z
zengyawen 已提交
1659

Z
zengyawen 已提交
1660 1661
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder

W
wusongqing 已提交
1662
**参数:**
B
bird_j 已提交
1663

W
wusongqing 已提交
1664
| 参数名   | 类型     | 必填 | 说明                                                         |
Z
zengyawen 已提交
1665
| -------- | -------- | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
1666 1667
| type     | string   | 是   | 录制事件回调类型,支持的事件包括:'prepare'&nbsp;\|&nbsp;'start'&nbsp;\|  'pause' \| ’resume‘ \|&nbsp;'stop'&nbsp;\|&nbsp;'release'&nbsp;\|&nbsp;'reset'。<br/>-&nbsp;'prepare'&nbsp;:完成[prepare](#audiorecorder_prepare)调用,音频录制参数设置完成,触发该事件。<br/>-&nbsp;'start'&nbsp;:完成[start](#audiorecorder_start)调用,音频录制开始,触发该事件。<br/>-&nbsp;'pause': 完成[pause](#audiorecorder_pause)调用,音频暂停录制,触发该事件。<br/>-&nbsp;'resume': 完成[resume](#audiorecorder_resume)调用,音频恢复录制,触发该事件。<br/>-&nbsp;'stop'&nbsp;:完成[stop](#audiorecorder_stop)调用,音频停止录制,触发该事件。<br/>-&nbsp;'release'&nbsp;:完成[release](#audiorecorder_release)调用,音频释放录制资源,触发该事件。<br/>-&nbsp;'reset':完成[reset](#audiorecorder_reset)调用,音频重置为初始状态,触发该事件。 |
| callback | ()=>void | 是   | 录制事件回调方法。                                           |
Z
zengyawen 已提交
1668

W
wusongqing 已提交
1669
**示例:**
Z
zengyawen 已提交
1670

1671
```js
A
tab  
abc12133 已提交
1672
let audiorecorder = media.createAudioRecorder();                                  // 创建一个音频录制实例
1673 1674 1675 1676 1677 1678
let audioRecorderConfig = {
    audioEncoder : media.AudioEncoder.AAC_LC, ,
    audioEncodeBitRate : 22050,
    audioSampleRate : 22050,
    numberOfChannels : 2,
    format : media.AudioOutputFormat.AAC_ADTS,
Z
zengyawen 已提交
1679
    uri : 'fd://xx',                                                            // 文件需先由调用者创建,并给予适当的权限
1680 1681
    location : { latitude : 30, longitude : 130},
}
A
tab  
abc12133 已提交
1682 1683
audioRecorder.on('error', (error) => {                                             // 设置'error'事件回调
    console.info(`audio error called, errName is ${error.name}`);
1684 1685 1686
    console.info(`audio error called, errCode is ${error.code}`);
    console.info(`audio error called, errMessage is ${error.message}`);
});
A
tab  
abc12133 已提交
1687
audioRecorder.on('prepare', () => {                                              // 设置'prepare'事件回调
1688
    console.log('prepare success');
A
tab  
abc12133 已提交
1689
    audioRecorder.start();                                                       // 开始录制,并触发'start'事件回调
1690
});
A
tab  
abc12133 已提交
1691
audioRecorder.on('start', () => {                                                 // 设置'start'事件回调
1692 1693
    console.log('audio recorder start success');
});
A
tab  
abc12133 已提交
1694
audioRecorder.on('pause', () => {                                                 // 设置'pause'事件回调
1695 1696
    console.log('audio recorder pause success');
});
A
tab  
abc12133 已提交
1697
audioRecorder.on('resume', () => {                                                 // 设置'resume'事件回调
1698 1699
    console.log('audio recorder resume success');
});
A
tab  
abc12133 已提交
1700
audioRecorder.on('stop', () => {                                                 // 设置'stop'事件回调
1701 1702
    console.log('audio recorder stop success');
});
A
tab  
abc12133 已提交
1703
audioRecorder.on('release', () => {                                                 // 设置'release'事件回调
1704 1705
    console.log('audio recorder release success');
});
A
tab  
abc12133 已提交
1706
audioRecorder.on('reset', () => {                                                 // 设置'reset'事件回调
1707
    console.log('audio recorder reset success');
Z
zengyawen 已提交
1708
});
A
tab  
abc12133 已提交
1709
audioRecorder.prepare(audioRecorderConfig)                                       // 设置录制参数 ,并触发'prepare'事件回调
Z
zengyawen 已提交
1710 1711 1712 1713 1714 1715
```

### on('error')

on(type: 'error', callback: ErrorCallback): void

W
wusongqing 已提交
1716
开始订阅音频录制错误事件。
B
bird_j 已提交
1717

Z
zengyawen 已提交
1718 1719
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder

W
wusongqing 已提交
1720
**参数:**
Z
zengyawen 已提交
1721

W
wusongqing 已提交
1722
| 参数名   | 类型          | 必填 | 说明                                                         |
Z
zengyawen 已提交
1723
| -------- | ------------- | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
1724 1725
| type     | string        | 是   | 录制错误事件回调类型'error'。<br/>-&nbsp;'error':音频录制过程中发生错误,触发该事件。 |
| callback | ErrorCallback | 是   | 录制错误事件回调方法。                                       |
Z
zengyawen 已提交
1726

W
wusongqing 已提交
1727
**示例:**
1728 1729

```js
A
tab  
abc12133 已提交
1730 1731
audioRecorder.on('error', (error) => {                                  // 设置'error'事件回调
    console.info(`audio error called, errName is ${error.name}`);       // 打印错误类型名称
W
wusongqing 已提交
1732 1733
    console.info(`audio error called, errCode is ${error.code}`);       // 打印错误码
    console.info(`audio error called, errMessage is ${error.message}`); // 打印错误类型详细描述
1734
});
A
tab  
abc12133 已提交
1735
audioRecorder.prepare();                                                  // prepare不设置参数,触发'error'事件
1736
```
Z
zengyawen 已提交
1737 1738 1739

## AudioRecorderConfig

W
wusongqing 已提交
1740
表示音频的录音配置。
Z
zengyawen 已提交
1741

Z
zengyawen 已提交
1742 1743
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.AudioRecorder。

W
wusongqing 已提交
1744
| 名称                  | 参数类型                                | 必填 | 说明                                                         |
1745
| --------------------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
1746 1747 1748 1749
| audioEncoder          | [AudioEncoder](#audioencoder)           | 否   | 音频编码格式,默认设置为AAC_LC。                             |
| audioEncodeBitRate    | number                                  | 否   | 音频编码比特率,默认值为48000。                              |
| audioSampleRate       | number                                  | 否   | 音频采集采样率,默认值为48000。                              |
| numberOfChannels      | number                                  | 否   | 音频采集声道数,默认值为2。                                  |
A
abc 已提交
1750
| format                | [AudioOutputFormat](#audiooutputformat) | 否   | 音频输出封装格式,默认设置为MPEG_4。                         |
1751 1752
| location              | [Location](#location)                   | 否   | 音频采集的地理位置。                                         |
| uri                   | string                                  | 是   | 音频输出URI:fd://xx&nbsp;(fd&nbsp;number)<br/>![zh-cn_image_0000001164217678](figures/zh-cn_image_url.png) <br/>文件需要由调用者创建,并赋予适当的权限。 |
Z
zengyawen 已提交
1753
| audioEncoderMime      | [CodecMimeType](#codecmimetype8)        | 否   | 音频编码格式。                                               |
Z
zengyawen 已提交
1754 1755


A
1  
abc12133 已提交
1756
## AudioEncoder<sup>(deprecated)</sup>
Z
zengyawen 已提交
1757

A
add dep  
abc12133 已提交
1758 1759 1760
> **说明:**
> 从 API Version 8 开始废弃,建议使用[CodecMimeType](#codecmimetype8)替代。

W
wusongqing 已提交
1761
表示音频编码格式的枚举。
Z
zengyawen 已提交
1762

Z
zengyawen 已提交
1763 1764
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.AudioRecorder。

W
wusongqing 已提交
1765
| 名称    | 默认值 | 说明                                                         |
B
bird_j 已提交
1766
| ------- | ------ | ------------------------------------------------------------ |
A
abc 已提交
1767 1768 1769
| DEFAULT | 0      | 默认编码格式。<br/>仅做接口定义,暂不支持使用。 |
| AMR_NB  | 1      | AMR-NB(Adaptive Multi Rate-Narrow Band Speech Codec) 编码格式。<br/>仅做接口定义,暂不支持使用。 |
| AMR_WB  | 2      | AMR-WB(Adaptive Multi Rate-Wide Band Speech Codec) 编码格式。<br/>仅做接口定义,暂不支持使用。 |
Z
zengyawen 已提交
1770
| AAC_LC  | 3      | AAC-LC(Advanced&nbsp;Audio&nbsp;Coding&nbsp;Low&nbsp;Complexity)编码格式。 |
A
abc 已提交
1771
| HE_AAC  | 4      | HE_AAC(High-Efficiency Advanced&nbsp;Audio&nbsp;Coding)编码格式。<br/>仅做接口定义,暂不支持使用。 |
Z
zengyawen 已提交
1772 1773


A
1  
abc12133 已提交
1774
## AudioOutputFormat<sup>(deprecated)</sup>
Z
zengyawen 已提交
1775

A
add dep  
abc12133 已提交
1776 1777 1778
> **说明:**
> 从 API Version 8 开始废弃,建议使用[ContainerFormatType ](#containerformattype8)替代。

W
wusongqing 已提交
1779
表示音频封装格式的枚举。
Z
zengyawen 已提交
1780

Z
zengyawen 已提交
1781 1782
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.AudioRecorder。

W
wusongqing 已提交
1783
| 名称     | 默认值 | 说明                                                         |
Z
zengyawen 已提交
1784
| -------- | ------ | ------------------------------------------------------------ |
A
abc 已提交
1785
| DEFAULT  | 0      | 默认封装格式。<br/>仅做接口定义,暂不支持使用。 |
Z
zengyawen 已提交
1786
| MPEG_4   | 2      | 封装为MPEG-4格式。                                           |
A
abc 已提交
1787 1788
| AMR_NB   | 3      | 封装为AMR_NB格式。<br/>仅做接口定义,暂不支持使用。 |
| AMR_WB   | 4      | 封装为AMR_WB格式。<br/>仅做接口定义,暂不支持使用。 |
Z
zengyawen 已提交
1789
| AAC_ADTS | 6      | 封装为ADTS(Audio&nbsp;Data&nbsp;Transport&nbsp;Stream)格式,是AAC音频的传输流格式。 |
1790

1791
## VideoRecorder<sup>9+</sup>
1792

1793
视频录制管理类,用于录制视频媒体。在调用VideoRecorder的方法前,需要先通过[createVideoRecorder()](#mediacreatevideorecorder9)构建一个[VideoRecorder](#videorecorder9)实例。
1794

W
wusongqing 已提交
1795
视频录制demo可参考:[视频录制开发指导](../../media/video-recorder.md)
1796

W
wusongqing 已提交
1797
### 属性
1798

Z
zengyawen 已提交
1799 1800 1801 1802
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoRecorder。

| 名称               | 类型                                   | 可读 | 可写 | 说明             |
| ------------------ | -------------------------------------- | ---- | ---- | ---------------- |
1803
| state<sup>8+</sup> | [VideoRecordState](#videorecordstate9) | 是   | 否   | 视频录制的状态。 |
1804

1805
### prepare<sup>9+</sup><a name=videorecorder_prepare1></a>
1806 1807 1808

prepare(config: VideoRecorderConfig, callback: AsyncCallback\<void>): void;

W
wusongqing 已提交
1809
异步方式进行视频录制的参数设置。通过注册回调函数获取返回值。
1810

A
1  
abc12133 已提交
1811
**需要权限:** ohos.permission.MICROPHONE
Z
zengyawen 已提交
1812 1813 1814

**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
1815
**参数:**
B
bird_j 已提交
1816

1817 1818
| 参数名   | 类型                                         | 必填 | 说明                                |
| -------- | -------------------------------------------- | ---- | ----------------------------------- |
1819
| config   | [VideoRecorderConfig](#videorecorderconfig9) | 是   | 配置视频录制的相关参数。            |
1820
| callback | AsyncCallback\<void>                         | 是   | 异步视频录制prepare方法的回调方法。 |
1821

W
wusongqing 已提交
1822
**示例:**
1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841

```js
let videoProfile = {
    audioBitrate : 48000,
    audioChannels : 2,
    audioCodec : 'audio/mp4a-latm',
    audioSampleRate : 48000,
    fileFormat : 'mp4',
    videoBitrate : 48000,
    videoCodec : 'video/mp4v-es',
    videoFrameWidth : 640,
    videoFrameHeight : 480,
    videoFrameRate : 30
}

let videoConfig = {
    audioSourceType : 1,
    videoSourceType : 0,
    profile : videoProfile,
Z
zengyawen 已提交
1842
    url : 'fd://xx',   // 文件需先由调用者创建,并给予适当的权限
1843 1844 1845 1846 1847 1848 1849
    orientationHint : 0,
    location : { latitude : 30, longitude : 130 },
}

// asyncallback
let videoRecorder = null;
let events = require('events');
A
amr  
abc12133 已提交
1850
let eventEmitter = new events.EventEmitter();
1851 1852 1853 1854

eventEmitter.on('prepare', () => {
    videoRecorder.prepare(videoConfig, (err) => {
        if (typeof (err) == 'undefined') {
B
bird_j 已提交
1855
            console.info('prepare success');
1856
        } else {
B
bird_j 已提交
1857
            console.info('prepare failed and error is ' + err.message);
1858 1859 1860 1861 1862 1863
        }
    });
});

media.createVideoRecorder((err, recorder) => {
    if (typeof (err) == 'undefined' && typeof (recorder) != 'undefined') {
B
bird_j 已提交
1864 1865
        videoRecorder = recorder;
        console.info('createVideoRecorder success');
W
wusongqing 已提交
1866
        eventEmitter.emit('prepare');                                        // prepare事件触发
1867
    } else {
B
bird_j 已提交
1868
        console.info('createVideoRecorder failed and error is ' + err.message);
1869 1870 1871 1872
    }
});
```

1873
### prepare<sup>9+</sup><a name=videorecorder_prepare2></a>
1874 1875 1876

prepare(config: VideoRecorderConfig): Promise\<void>;

W
wusongqing 已提交
1877
异步方式进行视频录制的参数设置。通过Promise获取返回值。
B
bird_j 已提交
1878

Z
zengyawen 已提交
1879
**需要权限:** ohos.permission.MICROPHONE,ohos.permission.CAMERA
Z
zengyawen 已提交
1880 1881 1882

**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
1883
**参数:**
1884

1885 1886
| 参数名 | 类型                                         | 必填 | 说明                     |
| ------ | -------------------------------------------- | ---- | ------------------------ |
1887
| config | [VideoRecorderConfig](#videorecorderconfig9) | 是   | 配置视频录制的相关参数。 |
1888

W
wusongqing 已提交
1889
**返回值:**
1890

W
wusongqing 已提交
1891
| 类型           | 说明                                     |
1892
| -------------- | ---------------------------------------- |
W
wusongqing 已提交
1893
| Promise\<void> | 异步视频录制prepare方法的Promise返回值。 |
1894

W
wusongqing 已提交
1895
**示例:**
1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914

```js
let videoProfile = {
    audioBitrate : 48000,
    audioChannels : 2,
    audioCodec : 'audio/mp4a-latm',
    audioSampleRate : 48000,
    fileFormat : 'mp4',
    videoBitrate : 48000,
    videoCodec : 'video/mp4v-es',
    videoFrameWidth : 640,
    videoFrameHeight : 480,
    videoFrameRate : 30
}

let videoConfig = {
    audioSourceType : 1,
    videoSourceType : 0,
    profile : videoProfile,
Z
zengyawen 已提交
1915
    url : 'fd://xx',   // 文件需先由调用者创建,并给予适当的权限
1916 1917 1918 1919 1920 1921
    orientationHint : 0,
    location : { latitude : 30, longitude : 130 },
}

// promise
let videoRecorder = null;
1922
media.createVideoRecorder().then((recorder) => {
1923 1924 1925 1926 1927 1928 1929 1930 1931 1932
    if (typeof (recorder) != 'undefined') {
        videoRecorder = recorder;
        console.info('createVideoRecorder success');
    } else {
        console.info('createVideoRecorder failed');
    }
}).catch((err) => {
    console.info('catch err error message is ' + err.message);
});

1933
videoRecorder.prepare(videoConfig).then(() => {
1934 1935 1936 1937 1938 1939
    console.info('prepare success');
}).catch((err) => {
    console.info('prepare failed and catch error is ' + err.message);
});
```

1940
### getInputSurface<sup>9+</sup>
1941 1942 1943

getInputSurface(callback: AsyncCallback\<string>): void;

W
wusongqing 已提交
1944
异步方式获得录制需要的surface。此surface提供给调用者,调用者从此surface中获取surfaceBuffer,填入相应的数据。
1945

W
wusongqing 已提交
1946
应当注意,填入的视频数据需要携带时间戳(单位ns),buffersize。时间戳的起始时间请以系统启动时间为基准。
1947

W
wusongqing 已提交
1948
只能在[prepare()](#videorecorder_prepare1)接口调用后调用。
1949

Z
zengyawen 已提交
1950 1951
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
1952
**参数:**
B
bird_j 已提交
1953

W
wusongqing 已提交
1954
| 参数名   | 类型                   | 必填 | 说明                        |
1955
| -------- | ---------------------- | ---- | --------------------------- |
W
wusongqing 已提交
1956
| callback | AsyncCallback\<string> | 是   | 异步获得surface的回调方法。 |
1957

W
wusongqing 已提交
1958
**示例:**
1959 1960 1961

```js
// asyncallback
A
tab  
abc12133 已提交
1962
let surfaceID = null;                                               // 传递给外界的surfaceID
B
bird_j 已提交
1963 1964 1965
videoRecorder.getInputSurface((err, surfaceId) => {
    if (typeof (err) == 'undefined') {
        console.info('getInputSurface success');
B
bird_j 已提交
1966
        surfaceID = surfaceId;
B
bird_j 已提交
1967 1968 1969
    } else {
        console.info('getInputSurface failed and error is ' + err.message);
    }
1970 1971 1972
});
```

1973
### getInputSurface<sup>9+</sup>
1974 1975 1976

getInputSurface(): Promise\<string>;

W
wusongqing 已提交
1977
 异步方式获得录制需要的surface。此surface提供给调用者,调用者从此surface中获取surfaceBuffer,填入相应的数据。
1978

W
wusongqing 已提交
1979
应当注意,填入的视频数据需要携带时间戳(单位ns),buffersize。时间戳的起始时间请以系统启动时间为基准。
1980

W
wusongqing 已提交
1981
只能在[prepare()](#videorecorder_prepare1)接口调用后调用。
B
bird_j 已提交
1982

Z
zengyawen 已提交
1983 1984
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
1985
**返回值:**
1986

W
wusongqing 已提交
1987
| 类型             | 说明                             |
1988
| ---------------- | -------------------------------- |
W
wusongqing 已提交
1989
| Promise\<string> | 异步获得surface的Promise返回值。 |
1990

W
wusongqing 已提交
1991
**示例:**
1992 1993 1994

```js
// promise
A
tab  
abc12133 已提交
1995
let surfaceID = null;                                               // 传递给外界的surfaceID
1996
videoRecorder.getInputSurface().then((surfaceId) => {
1997
    console.info('getInputSurface success');
B
bird_j 已提交
1998
    surfaceID = surfaceId;
1999 2000 2001 2002 2003
}).catch((err) => {
    console.info('getInputSurface failed and catch error is ' + err.message);
});
```

2004
### start<sup>9+</sup><a name=videorecorder_start1></a>
2005 2006 2007

start(callback: AsyncCallback\<void>): void;

W
wusongqing 已提交
2008
异步方式开始视频录制。通过注册回调函数获取返回值。
2009

Z
zengyawen 已提交
2010 2011 2012
[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface8)后调用,需要依赖数据源先给surface传递数据。

**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
B
bird_j 已提交
2013

W
wusongqing 已提交
2014
**参数:**
2015

W
wusongqing 已提交
2016
| 参数名   | 类型                 | 必填 | 说明                         |
2017
| -------- | -------------------- | ---- | ---------------------------- |
W
wusongqing 已提交
2018
| callback | AsyncCallback\<void> | 是   | 异步开始视频录制的回调方法。 |
2019

W
wusongqing 已提交
2020
**示例:**
2021 2022 2023

```js
// asyncallback
B
bird_j 已提交
2024 2025 2026 2027 2028 2029
videoRecorder.start((err) => {
    if (typeof (err) == 'undefined') {
        console.info('start videorecorder success');
    } else {
        console.info('start videorecorder failed and error is ' + err.message);
    }
2030 2031 2032
});
```

2033
### start<sup>9+</sup><a name=videorecorder_start2></a>
2034 2035 2036

start(): Promise\<void>;

W
wusongqing 已提交
2037
异步方式开始视频录制。通过Promise获取返回值。
2038

Z
zengyawen 已提交
2039 2040 2041
[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface8)后调用,需要依赖数据源先给surface传递数据。

**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
2042

W
wusongqing 已提交
2043
**返回值:**
B
bird_j 已提交
2044

W
wusongqing 已提交
2045
| 类型           | 说明                                  |
2046
| -------------- | ------------------------------------- |
W
wusongqing 已提交
2047
| Promise\<void> | 异步开始视频录制方法的Promise返回值。 |
2048

W
wusongqing 已提交
2049
**示例:**
2050 2051 2052

```js
// promise
2053
videoRecorder.start().then(() => {
2054 2055 2056 2057 2058 2059
    console.info('start videorecorder success');
}).catch((err) => {
    console.info('start videorecorder failed and catch error is ' + err.message);
});
```

2060
### pause<sup>9+</sup><a name=videorecorder_pause1></a>
2061 2062 2063

pause(callback: AsyncCallback\<void>): void;

W
wusongqing 已提交
2064
异步方式暂停视频录制。通过注册回调函数获取返回值。
2065

W
wusongqing 已提交
2066
[start()](#videorecorder_start1)后调用。可以通过调用[resume()](#videorecorder_resume1)接口来恢复录制。
B
bird_j 已提交
2067

Z
zengyawen 已提交
2068 2069
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
2070
**参数:**
2071

W
wusongqing 已提交
2072
| 参数名   | 类型                 | 必填 | 说明                         |
2073
| -------- | -------------------- | ---- | ---------------------------- |
W
wusongqing 已提交
2074
| callback | AsyncCallback\<void> | 是   | 异步暂停视频录制的回调方法。 |
2075

W
wusongqing 已提交
2076
**示例:**
2077 2078 2079

```js
// asyncallback
B
bird_j 已提交
2080 2081 2082 2083 2084 2085
videoRecorder.pause((err) => {
    if (typeof (err) == 'undefined') {
        console.info('pause videorecorder success');
    } else {
        console.info('pause videorecorder failed and error is ' + err.message);
    }
2086 2087 2088
});
```

2089
### pause<sup>9+</sup><a name=videorecorder_pause2></a>
2090 2091 2092

pause(): Promise\<void>;

W
wusongqing 已提交
2093
异步方式暂停视频录制。通过Promise获取返回值。
2094

W
wusongqing 已提交
2095
[start()](#videorecorder_start1)后调用。可以通过调用[resume()](#videorecorder_resume1)接口来恢复录制。
2096

Z
zengyawen 已提交
2097 2098
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
2099
**返回值:**
B
bird_j 已提交
2100

W
wusongqing 已提交
2101
| 类型           | 说明                                  |
2102
| -------------- | ------------------------------------- |
W
wusongqing 已提交
2103
| Promise\<void> | 异步暂停视频录制方法的Promise返回值。 |
2104

W
wusongqing 已提交
2105
**示例:**
2106 2107 2108

```js
// promise
2109
videoRecorder.pause().then(() => {
2110 2111 2112 2113 2114 2115
    console.info('pause videorecorder success');
}).catch((err) => {
    console.info('pause videorecorder failed and catch error is ' + err.message);
});
```

2116
### resume<sup>9+</sup><a name=videorecorder_resume1></a>
2117 2118 2119

resume(callback: AsyncCallback\<void>): void;

W
wusongqing 已提交
2120
异步方式恢复视频录制。通过注册回调函数获取返回值。
B
bird_j 已提交
2121

Z
zengyawen 已提交
2122 2123
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
2124
**参数:**
2125

W
wusongqing 已提交
2126
| 参数名   | 类型                 | 必填 | 说明                         |
2127
| -------- | -------------------- | ---- | ---------------------------- |
W
wusongqing 已提交
2128
| callback | AsyncCallback\<void> | 是   | 异步恢复视频录制的回调方法。 |
2129

W
wusongqing 已提交
2130
**示例:**
2131 2132 2133

```js
// asyncallback
B
bird_j 已提交
2134 2135 2136 2137 2138 2139
videoRecorder.resume((err) => {
    if (typeof (err) == 'undefined') {
        console.info('resume videorecorder success');
    } else {
        console.info('resume videorecorder failed and error is ' + err.message);
    }
2140 2141 2142
});
```

2143
### resume<sup>9+</sup><a name=videorecorder_resume2></a>
2144 2145 2146

resume(): Promise\<void>;

W
wusongqing 已提交
2147
异步方式恢复视频录制。通过Promise获取返回值。
2148

Z
zengyawen 已提交
2149 2150
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
2151
**返回值:**
B
bird_j 已提交
2152

W
wusongqing 已提交
2153
| 类型           | 说明                                  |
2154
| -------------- | ------------------------------------- |
W
wusongqing 已提交
2155
| Promise\<void> | 异步恢复视频录制方法的Promise返回值。 |
2156

W
wusongqing 已提交
2157
**示例:**
2158 2159 2160

```js
// promise
2161
videoRecorder.resume().then(() => {
2162 2163 2164 2165 2166 2167
    console.info('resume videorecorder success');
}).catch((err) => {
    console.info('resume videorecorder failed and catch error is ' + err.message);
});
```

2168
### stop<sup>9+</sup><a name=videorecorder_stop1></a>
2169 2170 2171

stop(callback: AsyncCallback\<void>): void;

W
wusongqing 已提交
2172
异步方式停止视频录制。通过注册回调函数获取返回值。
2173

Z
zengyawen 已提交
2174 2175 2176
需要重新调用[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface8)接口才能重新录制。

**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
B
bird_j 已提交
2177

W
wusongqing 已提交
2178
**参数:**
2179

W
wusongqing 已提交
2180
| 参数名   | 类型                 | 必填 | 说明                         |
2181
| -------- | -------------------- | ---- | ---------------------------- |
W
wusongqing 已提交
2182
| callback | AsyncCallback\<void> | 是   | 异步停止视频录制的回调方法。 |
2183

W
wusongqing 已提交
2184
**示例:**
2185 2186 2187

```js
// asyncallback
B
bird_j 已提交
2188 2189 2190 2191 2192 2193
videoRecorder.stop((err) => {
    if (typeof (err) == 'undefined') {
        console.info('stop videorecorder success');
    } else {
        console.info('stop videorecorder failed and error is ' + err.message);
    }
2194 2195 2196
});
```

2197
### stop<sup>9+</sup><a name=videorecorder_stop2></a>
2198 2199 2200

stop(): Promise\<void>;

W
wusongqing 已提交
2201
异步方式停止视频录制。通过Promise获取返回值。
2202

Z
zengyawen 已提交
2203 2204 2205
需要重新调用[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface8)接口才能重新录制。

**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
2206

W
wusongqing 已提交
2207
**返回值:**
B
bird_j 已提交
2208

W
wusongqing 已提交
2209
| 类型           | 说明                                  |
2210
| -------------- | ------------------------------------- |
W
wusongqing 已提交
2211
| Promise\<void> | 异步停止视频录制方法的Promise返回值。 |
2212

W
wusongqing 已提交
2213
**示例:**
2214 2215 2216

```js
// promise
2217
videoRecorder.stop().then(() => {
2218 2219 2220 2221 2222 2223
    console.info('stop videorecorder success');
}).catch((err) => {
    console.info('stop videorecorder failed and catch error is ' + err.message);
});
```

2224
### release<sup>9+</sup><a name=videorecorder_release1></a>
2225 2226 2227

release(callback: AsyncCallback\<void>): void;

W
wusongqing 已提交
2228
异步方式释放视频录制资源。通过注册回调函数获取返回值。
B
bird_j 已提交
2229

Z
zengyawen 已提交
2230 2231
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
2232
**参数:**
2233

W
wusongqing 已提交
2234
| 参数名   | 类型                 | 必填 | 说明                             |
2235
| -------- | -------------------- | ---- | -------------------------------- |
W
wusongqing 已提交
2236
| callback | AsyncCallback\<void> | 是   | 异步释放视频录制资源的回调方法。 |
2237

W
wusongqing 已提交
2238
**示例:**
2239 2240 2241

```js
// asyncallback
B
bird_j 已提交
2242 2243 2244 2245 2246 2247
videoRecorder.release((err) => {
    if (typeof (err) == 'undefined') {
        console.info('release videorecorder success');
    } else {
        console.info('release videorecorder failed and error is ' + err.message);
    }
2248 2249 2250
});
```

2251
### release<sup>9+</sup><a name=videorecorder_release2></a>
2252 2253 2254

release(): Promise\<void>;

W
wusongqing 已提交
2255
异步方式释放视频录制资源。通过Promise获取返回值。
B
bird_j 已提交
2256

Z
zengyawen 已提交
2257 2258
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
2259
**返回值:**
2260

W
wusongqing 已提交
2261
| 类型           | 说明                                      |
2262
| -------------- | ----------------------------------------- |
W
wusongqing 已提交
2263
| Promise\<void> | 异步释放视频录制资源方法的Promise返回值。 |
2264

W
wusongqing 已提交
2265
**示例:**
2266 2267 2268

```js
// promise
2269
videoRecorder.release().then(() => {
2270 2271 2272 2273 2274 2275
    console.info('release videorecorder success');
}).catch((err) => {
    console.info('release videorecorder failed and catch error is ' + err.message);
});
```

2276
### reset<sup>9+</sup><a name=videorecorder_reset1></a>
2277 2278 2279

reset(callback: AsyncCallback\<void>): void;

W
wusongqing 已提交
2280
异步方式重置视频录制。通过注册回调函数获取返回值。
2281

Z
zengyawen 已提交
2282 2283 2284
需要重新调用[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface8)接口才能重新录制。

**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
2285

W
wusongqing 已提交
2286
**参数:**
B
bird_j 已提交
2287

W
wusongqing 已提交
2288
| 参数名   | 类型                 | 必填 | 说明                         |
2289
| -------- | -------------------- | ---- | ---------------------------- |
W
wusongqing 已提交
2290
| callback | AsyncCallback\<void> | 是   | 异步重置视频录制的回调方法。 |
2291

W
wusongqing 已提交
2292
**示例:**
2293 2294 2295

```js
// asyncallback
B
bird_j 已提交
2296 2297 2298 2299 2300 2301
videoRecorder.reset((err) => {
    if (typeof (err) == 'undefined') {
        console.info('reset videorecorder success');
    } else {
        console.info('reset videorecorder failed and error is ' + err.message);
    }
2302 2303 2304
});
```

2305
### reset<sup>9+</sup><a name=videorecorder_reset2></a>
2306 2307 2308

reset(): Promise\<void>;

W
wusongqing 已提交
2309
异步方式重置视频录制。通过Promise获取返回值。
2310

Z
zengyawen 已提交
2311 2312 2313
需要重新调用[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface8)接口才能重新录制。

**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
B
bird_j 已提交
2314

W
wusongqing 已提交
2315
**返回值:**
2316

W
wusongqing 已提交
2317
| 类型           | 说明                                  |
2318
| -------------- | ------------------------------------- |
W
wusongqing 已提交
2319
| Promise\<void> | 异步重置视频录制方法的Promise返回值。 |
2320

W
wusongqing 已提交
2321
**示例:**
2322 2323 2324

```js
// promise
2325
videoRecorder.reset().then(() => {
2326 2327 2328 2329 2330 2331
    console.info('reset videorecorder success');
}).catch((err) => {
    console.info('reset videorecorder failed and catch error is ' + err.message);
});
```

2332
### on('error')<sup>9+</sup>
2333 2334 2335

on(type: 'error', callback: ErrorCallback): void

W
wusongqing 已提交
2336
开始订阅视频录制错误事件。
2337

Z
zengyawen 已提交
2338 2339
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

W
wusongqing 已提交
2340
**参数:**
B
bird_j 已提交
2341

W
wusongqing 已提交
2342
| 参数名   | 类型          | 必填 | 说明                                                         |
2343
| -------- | ------------- | ---- | ------------------------------------------------------------ |
Z
zengyawen 已提交
2344
| type     | string        | 是   | 录制错误事件回调类型'error'。<br/>-&nbsp;'error':视频录制过程中发生错误,触发该事件。 |
W
wusongqing 已提交
2345
| callback | ErrorCallback | 是   | 录制错误事件回调方法。                                       |
2346

W
wusongqing 已提交
2347
**示例:**
2348 2349

```js
A
tab  
abc12133 已提交
2350 2351
videoRecorder.on('error', (error) => {                                  // 设置'error'事件回调
    console.info(`audio error called, errName is ${error.name}`);       // 打印错误类型名称
W
wusongqing 已提交
2352 2353
    console.info(`audio error called, errCode is ${error.code}`);       // 打印错误码
    console.info(`audio error called, errMessage is ${error.message}`); // 打印错误类型详细描述
2354
});
W
wusongqing 已提交
2355
// 当获取videoRecordState接口出错时通过此订阅事件上报
2356 2357
```

2358
## VideoRecordState<sup>9+</sup>
2359

W
wusongqing 已提交
2360
视频录制的状态机。可通过state属性获取当前状态。
2361

Z
zengyawen 已提交
2362 2363
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoRecorder。

W
wusongqing 已提交
2364 2365 2366 2367 2368 2369 2370 2371
| 名称     | 类型   | 描述                   |
| -------- | ------ | ---------------------- |
| idle     | string | 视频录制空闲。         |
| prepared | string | 视频录制参数设置完成。 |
| playing  | string | 视频正在录制。         |
| paused   | string | 视频暂停录制。         |
| stopped  | string | 视频录制停止。         |
| error    | string | 错误状态。             |
2372

2373
## VideoRecorderConfig<sup>9+</sup>
2374

W
wusongqing 已提交
2375
表示视频录制的参数设置。
2376

Z
zengyawen 已提交
2377 2378
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoRecorder。

Z
zengyawen 已提交
2379 2380
| 名称            | 参数类型                                       | 必填 | 说明                                                         |
| --------------- | ---------------------------------------------- | ---- | ------------------------------------------------------------ |
2381 2382 2383
| audioSourceType | [AudioSourceType](#audiosourcetype9)           | 是   | 视频录制的音频源类型。                                       |
| videoSourceType | [VideoSourceType](#videosourcetype9)           | 是   | 视频录制的视频源类型。                                       |
| profile         | [VideoRecorderProfile](#videorecorderprofile9) | 是   | 视频录制的profile。                                          |
Z
zengyawen 已提交
2384
| rotation        | number                                         | 否   | 录制视频的旋转角度。                                         |
2385
| location        | [Location](#location)                          | 否   | 录制视频的地理位置。                                         |
Z
zengyawen 已提交
2386
| url             | string                                         | 是   | 视频输出URL:fd://xx&nbsp;(fd&nbsp;number)<br/>![](figures/zh-cn_image_url.png) <br/>文件需要由调用者创建,并赋予适当的权限。 |
2387

2388
## AudioSourceType<sup>9+</sup>
2389

W
wusongqing 已提交
2390
表示视频录制中音频源类型的枚举。
2391

Z
zengyawen 已提交
2392 2393 2394 2395 2396 2397
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoRecorder。

| 名称                      | 值   | 说明                   |
| ------------------------- | ---- | ---------------------- |
| AUDIO_SOURCE_TYPE_DEFAULT | 0    | 默认的音频输入源类型。 |
| AUDIO_SOURCE_TYPE_MIC     | 1    | 表示MIC的音频输入源。  |
2398

2399
## VideoSourceType<sup>9+</sup>
2400

W
wusongqing 已提交
2401
表示视频录制中视频源类型的枚举。
2402

Z
zengyawen 已提交
2403 2404
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoRecorder。

W
wusongqing 已提交
2405 2406 2407 2408
| 名称                          | 值   | 说明                            |
| ----------------------------- | ---- | ------------------------------- |
| VIDEO_SOURCE_TYPE_SURFACE_YUV | 0    | 输入surface中携带的是raw data。 |
| VIDEO_SOURCE_TYPE_SURFACE_ES  | 1    | 输入surface中携带的是ES data。  |
2409

2410
## VideoRecorderProfile<sup>9+</sup>
2411

W
wusongqing 已提交
2412
视频录制的配置文件。
2413

Z
zengyawen 已提交
2414 2415
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.VideoRecorder。

W
wusongqing 已提交
2416 2417 2418 2419
| 名称             | 参数类型                                     | 必填 | 说明             |
| ---------------- | -------------------------------------------- | ---- | ---------------- |
| audioBitrate     | number                                       | 是   | 音频编码比特率。 |
| audioChannels    | number                                       | 是   | 音频采集声道数。 |
Z
zengyawen 已提交
2420
| audioCodec       | [CodecMimeType](#codecmimetype8)             | 是   | 音频编码格式。   |
W
wusongqing 已提交
2421 2422
| audioSampleRate  | number                                       | 是   | 音频采样率。     |
| fileFormat       | [ContainerFormatType](#containerformattype8) | 是   | 文件的容器格式。 |
2423
| videoBitrate     | number                                       | 是   | 视频编码比特率。 |
Z
zengyawen 已提交
2424
| videoCodec       | [CodecMimeType](#codecmimetype8)             | 是   | 视频编码格式。   |
W
wusongqing 已提交
2425 2426
| videoFrameWidth  | number                                       | 是   | 录制视频帧的宽。 |
| videoFrameHeight | number                                       | 是   | 录制视频帧的高。 |
2427
| videoFrameRate   | number                                       | 是   | 录制视频帧率。   |
2428 2429 2430

## ContainerFormatType<sup>8+</sup>

W
wusongqing 已提交
2431
表示容器格式类型的枚举,缩写为CFT。
2432

Z
zengyawen 已提交
2433 2434
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。

W
wusongqing 已提交
2435 2436 2437 2438
| 名称        | 值    | 说明                  |
| ----------- | ----- | --------------------- |
| CFT_MPEG_4  | "mp4" | 视频的容器格式,MP4。 |
| CFT_MPEG_4A | "m4a" | 音频的容器格式,M4A。 |
2439

2440
## Location
2441

W
wusongqing 已提交
2442
视频录制的地理位置。
2443

Z
zengyawen 已提交
2444 2445
**系统能力:** 以下各项对应的系统能力均为 SystemCapability.Multimedia.Media.Core。

W
wusongqing 已提交
2446 2447 2448 2449
| 名称      | 参数类型 | 必填 | 说明             |
| --------- | -------- | ---- | ---------------- |
| latitude  | number   | 是   | 地理位置的纬度。 |
| longitude | number   | 是   | 地理位置的经度。 |