js-apis-media.md 191.7 KB
Newer Older
Z
zengyawen 已提交
1
# @ohos.multimedia.media (媒体服务)
2

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

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

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

Z
zengyawen 已提交
10 11 12 13 14
- 音视频播放([AVPlayer](#avplayer9)<sup>9+</sup>),[AudioPlayer](#audioplayerdeprecated)<sup>6+</sup>[VideoPlayer](#videoplayer)<sup>8+</sup>整合,升级了状态机和错误码,推荐使用
- 音视频录制([AVRecorder](#avrecorder9)<sup>9+</sup>),[AudioRecorder](#audiorecorderdeprecated)<sup>6+</sup>[VideoRecorder](#videorecorder9)<sup>9+</sup>整合,推荐使用
- 音频播放([AudioPlayer](#audioplayerdeprecated)<sup>6+</sup>),[AVPlayer](#avplayer9)<sup>9+</sup>发布后停止维护,请使用[AVPlayer](#avplayer9)<sup>9+</sup>
- 视频播放([VideoPlayer](#videoplayerdeprecated)<sup>8+</sup>),[AVPlayer](#avplayer9)<sup>9+</sup>发布后停止维护,请使用[AVPlayer](#avplayer9)<sup>9+</sup>
- 音频录制([AudioRecorder](#audiorecorderdeprecated)<sup>6+</sup>),[AVRecorder](#avrecorder9)<sup>9+</sup>发布后停止维护,请使用[AVRecorder](#avrecorder9)<sup>9+</sup>
15
- 视频录制([VideoRecorder](#videorecorder9)<sup>9+</sup>),[AVRecorder](#avrecorder9)<sup>9+</sup>发布后停止维护,请使用[AVRecorder](#avrecorder9)<sup>9+</sup>
16

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

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

23 24 25 26 27 28 29 30 31 32 33 34
## media.createAVPlayer<sup>9+</sup>

createAVPlayer(callback: AsyncCallback\<AVPlayer>): void

异步方式创建音视频播放实例,通过注册回调函数获取返回值。

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

**参数:**

| 参数名   | 类型                                  | 必填 | 说明                                                         |
| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
Z
zengyawen 已提交
35
| callback | AsyncCallback\<[AVPlayer](#avplayer9)> | 是   | 回调函数。异步返回AVPlayer实例,失败时返回null。可用于音视频播放。 |
36 37 38 39 40 41 42 43 44 45 46 47

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                       |
| -------- | ------------------------------ |
| 5400101  | No memory. Return by callback. |

**示例:**

```js
48
let avPlayer;
49 50

media.createAVPlayer((error, video) => {
51 52 53 54 55 56
  if (video != null) {
    avPlayer = video;
    console.info('createAVPlayer success');
  } else {
    console.error(`createAVPlayer fail, error message:${error.message}`);
  }
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
});
```

## media.createAVPlayer<sup>9+</sup>

createAVPlayer(): Promise\<AVPlayer>

异步方式创建音视频播放实例,通过Promise获取返回值。

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

**返回值:**

| 类型                            | 说明                                                         |
| ------------------------------- | ------------------------------------------------------------ |
Z
zengyawen 已提交
72
| Promise\<[AVPlayer](#avplayer9)> | Promise对象。异步返回AVPlayer实例,失败时返回null。可用于音视频播放。 |
73 74 75 76 77 78 79 80 81 82 83 84

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                      |
| -------- | ----------------------------- |
| 5400101  | No memory. Return by promise. |

**示例:**

```js
85
let avPlayer;
86 87

media.createAVPlayer().then((video) => {
88 89 90 91 92 93
  if (video != null) {
    avPlayer = video;
    console.info('createAVPlayer success');
  } else {
    console.error('createAVPlayer fail');
  }
94
}).catch((error) => {
95
  console.error(`AVPlayer catchCallback, error message:${error.message}`);
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124
});
```

## media.createAVRecorder<sup>9+</sup>

createAVRecorder(callback: AsyncCallback\<AVRecorder>): void

异步方式创建音视频录制实例。通过注册回调函数获取返回值。
一台设备只允许创建一个录制实例。

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

**参数:**

| 参数名   | 类型                                       | 必填 | 说明                                                         |
| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback\<[AVRecorder](#avrecorder9)> | 是   | 回调函数。异步返回AVRecorder实例,失败时返回null。可用于录制音视频媒体。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                       |
| -------- | ------------------------------ |
| 5400101  | No memory. Return by callback. |

**示例:**

```js
125
let avRecorder;
126 127

media.createAVRecorder((error, recorder) => {
128 129 130 131 132 133
  if (recorder != null) {
    avRecorder = recorder;
    console.info('createAVRecorder success');
  } else {
    console.error(`createAVRecorder fail, error message:${error.message}`);
  }
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
});
```

## media.createAVRecorder<sup>9+</sup>

createAVRecorder(): Promise\<AVRecorder>

异步方式创建音视频录制实例。通过Promise获取返回值。
一台设备只允许创建一个录制实例。

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

**返回值:**

| 类型                                 | 说明                                                         |
| ------------------------------------ | ------------------------------------------------------------ |
| Promise\<[AVRecorder](#avrecorder9)> | Promise对象。异步返回AVRecorder实例,失败时返回null。可用于录制音视频媒体。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                      |
| -------- | ----------------------------- |
| 5400101  | No memory. Return by promise. |

**示例:**

```js
163
let avRecorder;
164 165

media.createAVRecorder().then((recorder) => {
166 167 168 169 170 171
  if (recorder != null) {
    avRecorder = recorder;
    console.info('createAVRecorder success');
  } else {
    console.error('createAVRecorder fail');
  }
172
}).catch((error) => {
173
  console.error(`createAVRecorder catchCallback, error message:${error.message}`);
174 175 176
});
```

177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204
## media.createVideoRecorder<sup>9+</sup>

createVideoRecorder(callback: AsyncCallback\<VideoRecorder>): void

异步方式创建视频录制实例。通过注册回调函数获取返回值。
一台设备只允许创建一个录制实例。

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

**系统接口:** 该接口为系统接口

**参数:**

| 参数名   | 类型                                            | 必填 | 说明                                                         |
| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<[VideoRecorder](#videorecorder9)> | 是   | 回调函数。异步返回VideoRecorder实例,失败时返回null。可用于录制视频媒体。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                       |
| -------- | ------------------------------ |
| 5400101  | No memory. Return by callback. |

**示例:**

```js
205
let videoRecorder;
206 207

media.createVideoRecorder((error, video) => {
208 209 210 211 212 213
  if (video != null) {
    videoRecorder = video;
    console.info('video createVideoRecorder success');
  } else {
    console.error(`video createVideoRecorder fail, error message:${error.message}`);
  }
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244
});
```

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

createVideoRecorder(): Promise\<VideoRecorder>

异步方式创建视频录制实例。通过Promise获取返回值。
一台设备只允许创建一个录制实例。

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

**系统接口:** 该接口为系统接口

**返回值:**

| 类型                                      | 说明                                                         |
| ----------------------------------------- | ------------------------------------------------------------ |
| Promise<[VideoRecorder](#videorecorder9)> | Promise对象。异步返回VideoRecorder实例,失败时返回null。可用于录制视频媒体。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                      |
| -------- | ----------------------------- |
| 5400101  | No memory. Return by promise. |

**示例:**

```js
245
let videoRecorder;
246 247

media.createVideoRecorder().then((video) => {
248 249 250 251 252 253
  if (video != null) {
    videoRecorder = video;
    console.info('video createVideoRecorder success');
  } else {
    console.error('video createVideoRecorder fail');
  }
254
}).catch((error) => {
255
  console.error(`video catchCallback, error message:${error.message}`);
256 257 258
});
```

259
## AVErrorCode<sup>9+</sup><a name=averrorcode></a>
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320

[媒体错误码](../errorcodes/errorcode-media.md)类型枚举

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

| 名称                       | 值      | 说明                                 |
| :------------------------- | ------- | ------------------------------------ |
| AVERR_OK                   | 0       | 表示操作成功。                       |
| AVERR_NO_PERMISSION        | 201     | 表示无权限执行此操作。               |
| AVERR_INVALID_PARAMETER    | 401     | 表示传入入参无效。                   |
| AVERR_UNSUPPORT_CAPABILITY | 801     | 表示当前版本不支持该API能力。        |
| AVERR_NO_MEMORY            | 5400101 | 表示系统内存不足或服务数量达到上限。 |
| AVERR_OPERATE_NOT_PERMIT   | 5400102 | 表示当前状态不允许或无权执行此操作。 |
| AVERR_IO                   | 5400103 | 表示数据流异常信息。                 |
| AVERR_TIMEOUT              | 5400104 | 表示系统或网络响应超时。             |
| AVERR_SERVICE_DIED         | 5400105 | 表示服务进程死亡。                   |
| AVERR_UNSUPPORT_FORMAT     | 5400106 | 表示不支持当前媒体资源的格式。       |

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

媒体类型枚举。

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

| 名称           | 值   | 说明       |
| -------------- | ---- | ---------- |
| MEDIA_TYPE_AUD | 0    | 表示音频。 |
| MEDIA_TYPE_VID | 1    | 表示视频。 |

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

Codec MIME类型枚举。

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

| 名称         | 值                    | 说明                     |
| ------------ | --------------------- | ------------------------ |
| 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类型。       |
| AUDIO_AAC    | 'audio/mp4a-latm'     | 表示音频/mp4a-latm类型。 |
| AUDIO_VORBIS | 'audio/vorbis'        | 表示音频/vorbis类型。    |
| AUDIO_FLAC   | 'audio/flac'          | 表示音频/flac类型。      |

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

媒体信息描述枚举。

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

| 名称                     | 值              | 说明                                                         |
| ------------------------ | --------------- | ------------------------------------------------------------ |
| 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。                 |
| MD_KEY_DURATION          | 'duration'      | 表示媒体时长,其对应键值类型为number,单位为毫秒(ms)。     |
| MD_KEY_BITRATE           | 'bitrate'       | 表示比特率,其对应键值类型为number,单位为比特率(bps)。    |
| MD_KEY_WIDTH             | 'width'         | 表示视频宽度,其对应键值类型为number,单位为像素(px)。     |
| MD_KEY_HEIGHT            | 'height'        | 表示视频高度,其对应键值类型为number,单位为像素(px)。     |
321
| MD_KEY_FRAME_RATE        | 'frame_rate'    | 表示视频帧率,其对应键值类型为number,单位为帧每秒(fps)。  |
322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352
| MD_KEY_AUD_CHANNEL_COUNT | 'channel_count' | 表示声道数,其对应键值类型为number。                         |
| MD_KEY_AUD_SAMPLE_RATE   | 'sample_rate'   | 表示采样率,其对应键值类型为number,单位为赫兹(Hz)。       |

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

缓存事件类型枚举。

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

| 名称              | 值   | 说明                             |
| ----------------- | ---- | -------------------------------- |
| BUFFERING_START   | 1    | 表示开始缓存。                   |
| BUFFERING_END     | 2    | 表示结束缓存。                   |
| BUFFERING_PERCENT | 3    | 表示缓存百分比。                 |
| CACHED_DURATION   | 4    | 表示缓存时长,单位为毫秒(ms)。 |

## StateChangeReason<sup>9+</sup>

表示播放或录制实例状态机切换原因的枚举,伴随state一起上报。

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

| 名称       | 值   | 说明                                                         |
| ---------- | ---- | ------------------------------------------------------------ |
| USER       | 1    | 表示用户行为造成的状态切换,由用户或客户端主动调用接口产生。 |
| BACKGROUND | 2    | 表示系统行为造成的状态切换,比如应用未注册播控中心权限,退到后台时被系统强制暂停或停止。 |

## AVPlayer<sup>9+</sup>

播放管理类,用于管理和播放媒体资源。在调用AVPlayer的方法前,需要先通过[createAVPlayer()](#mediacreateavplayer9)构建一个AVPlayer实例。

Z
zengyawen 已提交
353
Audio/Video播放demo可参考:[音频播放开发指导](../../media/using-avplayer-for-playback.md)[视频播放开发指导](../../media/video-playback.md)
354 355 356 357 358

### 属性<a name=avplayer_属性></a>

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

359 360
| 名称                                                | 类型                                                         | 可读 | 可写 | 说明                                                         |
| --------------------------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ |
M
magnificGH 已提交
361 362 363
| url<sup>9+</sup>                                    | string                                                       | 是   | 是   | 媒体URL,只允许在**idle**状态下设置,静态属性。<br/>支持的视频格式(mp4、mpeg-ts、webm、mkv)。<br>支持的音频格式(m4a、aac、mp3、ogg、wav、flac)。<br/>**支持路径示例**<br>1. fd类型播放:fd://xx。<br>![](figures/zh-cn_image_url.png)<br>2. http网络播放: http://xx。<br/>3. https网络播放: https://xx。<br/>4. hls网络播放路径:http://xx或者https://xx。 |
| fdSrc<sup>9+</sup>                                  | [AVFileDescriptor](#avfiledescriptor9)                       | 是   | 是   | 媒体文件描述,只允许在**idle**状态下设置,静态属性。<br/>使用场景:应用中的媒体资源被连续存储在同一个文件中。<br/>支持的视频格式(mp4、mpeg-ts、webm、mkv)。<br>支持的音频格式(m4a、aac、mp3、ogg、wav、flac)。<br/>**使用示例**<br/>假设一个连续存储的媒体文件: <br/>视频1(地址偏移:0,字节长度:100);<br/>视频2(地址偏移:101,字节长度:50);<br/>视频3(地址偏移:151,字节长度:150);<br/>1. 播放视频1:AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。<br/>2. 播放视频2:AVFileDescriptor { fd = 资源句柄; offset = 101; length = 50; }。<br/>3. 播放视频3:AVFileDescriptor { fd = 资源句柄; offset = 151; length = 150; }。<br/>假设是一个独立的媒体文件: 请使用src=fd://xx。 |
| dataSrc<sup>10+</sup>                               | [AVDataSrcDescriptor](#avdatasrcdescriptor10)                | 是   | 是   | 流式媒体资源描述,只允许在**idle**状态下设置,静态属性。<br/>使用场景:应用播放从远端下载到本地的文件,在应用未下载完整音视频资源时,提前播放已获取的资源文件。<br/>支持的视频格式(mp4、mpeg-ts、webm、mkv)。<br>支持的音频格式(m4a、aac、mp3、ogg、wav、flac)。<br/>**使用示例**<br/>假设用户正在从远端服务器获取音视频媒体文件,希望下载到本地的同时播放已经下载好的部分: <br/>1.用户需要获取媒体文件的总大小size(单位为字节),获取不到时设置为-1。<br/>2.用户需要实现回调函数func用于填写数据,如果size = -1,则func形式为:func(buffer: ArrayBuffer, length: number),此时播放器只会按照顺序获取数据;否则func形式为:func(buffer: ArrayBuffer, length: number, pos: number),播放器会按需跳转并获取数据。<br/>3.用户设置AVDataSrcDescriptor {fileSize = size, callback = func}。<br/>**注意事项**<br/>如果播放的是mp4/m4a格式用户需要保证moov字段(媒体信息字段)在mdat字段(媒体数据字段)之前,或者moov之前的字段小于10M,否则会导致解析失败无法播放。 |
364
| surfaceId<sup>9+</sup>                              | string                                                       | 是   | 是   | 视频窗口ID,默认无窗口,只允许在**initialized**状态下设置,静态属性。<br/>使用场景:视频播放的窗口渲染,纯音频播放不用设置。<br/>**使用示例**<br/>[通过Xcomponent创建surfaceId](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid)。 |
X
live  
xxb-wzy 已提交
365
| loop<sup>9+</sup>                                   | boolean                                                      | 是   | 是   | 视频循环播放属性,默认'false',设置为'true'表示循环播放,动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。<br/>直播场景不支持loop设置。 |
366 367
| videoScaleType<sup>9+</sup>                         | [VideoScaleType](#videoscaletype9)                           | 是   | 是   | 视频缩放模式,默认VIDEO_SCALE_TYPE_FIT_CROP,动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。 |
| audioInterruptMode<sup>9+</sup>                     | [audio.InterruptMode](js-apis-audio.md#interruptmode9)       | 是   | 是   | 音频焦点模型,默认SHARE_MODE,动态属性。<br/>只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。 |
368
| audioRendererInfo<sup>10+</sup>                     | [audio.AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | 是   | 是   | 设置音频渲染信息,默认值contentType为CONTENT_TYPE_MUSIC,streamUsage为STREAM_USAGE_MEDIA。<br/>只允许在**initialized**状态下设置 |
369
| audioEffectMode<sup>10+</sup>                       | [audio.AudioEffectMode](js-apis-audio.md#audioeffectmode10)  | 是   | 是   | 设置音频音效模式,audioRendererInfo的contentType和streamUsage变动时会恢复为默认值,默认值参考[audio.AudioEffectMode](js-apis-audio.md#audioeffectmode10),动态属性。只允许在**prepared**/**playing**/**paused**/**completed**状态下设置。 |
370
| state<sup>9+</sup>                                  | [AVPlayerState](#avplayerstate9)                             | 是   | 否   | 音视频播放的状态,全状态有效,可查询参数。                   |
X
live  
xxb-wzy 已提交
371
| currentTime<sup>9+</sup>                            | number                                                       | 是   | 否   | 视频的当前播放位置,单位为毫秒(ms),可查询参数。<br/>返回为(-1)表示无效值,**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。 |
372 373 374
| duration<sup>9+</sup><a name=avplayer_duration></a> | number                                                       | 是   | 否   | 视频时长,单位为毫秒(ms),可查询参数。<br/>返回为(-1)表示无效值,**prepared**/**playing**/**paused**/**completed**状态下有效。<br/>直播场景默认返回(-1)。 |
| width<sup>9+</sup>                                  | number                                                       | 是   | 否   | 视频宽,单位为像素(px),可查询参数。<br/>返回为(0)表示无效值,**prepared**/**playing**/**paused**/**completed**状态下有效。 |
| height<sup>9+</sup>                                 | number                                                       | 是   | 否   | 视频高,单位为像素(px),可查询参数。<br/>返回为(0)表示无效值,**prepared**/**playing**/**paused**/**completed**状态下有效。 |
375

376 377
**说明:**

378
将资源句柄(fd)传递给媒体播放器之后,请不要通过该资源句柄做其他读写操作,包括但不限于将同一个资源句柄传递给多个媒体播放器。同一时间通过同一个资源句柄读写文件时存在竞争关系,将导致播放异常。
379

380 381 382 383 384 385 386 387 388 389 390 391 392
### on('stateChange')<sup>9+</sup><a name = stateChange_on></a>

on(type: 'stateChange', callback: (state: AVPlayerState, reason: StateChangeReason) => void): void

监听播放状态机AVPlayerState切换的事件。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 状态机切换事件回调类型,支持的事件:'stateChange',用户操作和系统都会触发此事件。 |
Z
zengyawen 已提交
393
| callback | function | 是   | 状态机切换事件回调方法:<br/>state: [AVPlayerState](#avplayerstate9),表示当前播放状态;<br/>reason: [StateChangeReason](#statechangereason9),表示当前播放状态的切换原因。 |
394 395 396 397 398

**示例:**

```js
avPlayer.on('stateChange', async (state, reason) => {
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430
  switch (state) {
    case 'idle':
      console.info('state idle called')
      break;
    case 'initialized':
      console.info('initialized prepared called')
      break;
    case 'prepared':
      console.info('state prepared called')
      break;
    case 'playing':
      console.info('state playing called')
      break;
    case 'paused':
      console.info('state paused called')
      break;
    case 'completed':
      console.info('state completed called')
      break;
    case 'stopped':
      console.info('state stopped called')
      break;
    case 'released':
      console.info('state released called')
      break;
    case 'error':
      console.info('state error called')
      break;
    default:
      console.info('unkown state :' + state)
      break;
  }
431 432 433 434 435 436 437
})
```

### off('stateChange')<sup>9+</sup><a name = stateChange_off></a>

off(type: 'stateChange'): void

Z
zengyawen 已提交
438
取消监听播放状态机[AVPlayerState](#avplayerstate9)切换的事件。
439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                  |
| ------ | ------ | ---- | ----------------------------------------------------- |
| type   | string | 是   | 状态机切换事件回调类型,取消注册的事件:'stateChange' |

**示例:**

```js
avPlayer.off('stateChange')
```

### on('error')<sup>9+</sup><a name = error_on></a>

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

Z
zengyawen 已提交
458
监听[AVPlayer](#avplayer9)的错误事件,该事件仅用于错误提示,不需要用户停止播控动作。如果此时[AVPlayerState](#avplayerstate9)也切至error状态,用户需要通过reset()或者release()退出播放操作。
459 460 461 462 463 464 465 466 467 468 469 470 471 472

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 错误事件回调类型,支持的事件:'error',用户操作和系统都会触发此事件。 |
| callback | function | 是   | 错误事件回调方法:使用播放器的过程中发生错误,会提供错误码ID和错误信息。 |

AVPlayer回调的**错误分类**<a name = error_info></a>可以分为以下几种:

| 错误码ID | 错误信息              | 说明                                                         |
| -------- | --------------------- | ------------------------------------------------------------ |
Z
zengyawen 已提交
473
| 201      | No Permission:        | 无权限执行此操作,[AVPlayerState](#avplayerstate9)会进入error状态。 |
474 475
| 401      | Invalid Parameter:    | 入参错误,表示调用无效。                                     |
| 801      | Unsupport Capability: | 不支持该API能力,表示调用无效。                              |
Z
zengyawen 已提交
476
| 5400101  | No Memory:            | 播放内存不足,[AVPlayerState](#avplayerstate9)会进入error状态。 |
477
| 5400102  | Operate Not Permit:   | 当前状态机不支持此操作,表示调用无效。                       |
478
| 5400103  | IO Error:             | 播放中发现码流异常,[AVPlayerState](#avplayerstate9)会进入error状态。 |
Z
zengyawen 已提交
479
| 5400104  | Network Timeout:      | 网络原因超时响应,[AVPlayerState](#avplayerstate9)会进入error状态。 |
480
| 5400105  | Service Died:         | 播放进程死亡,[AVPlayerState](#avplayerstate9)会进入error状态,需要调用release后重新创建实例。 |
Z
zengyawen 已提交
481
| 5400106  | Unsupport Format:     | 不支持的文件格式,[AVPlayerState](#avplayerstate9)会进入error状态。 |
482 483 484 485 486

**示例:**

```js
avPlayer.on('error', (error) => {
487 488
  console.error('error happened,and error message is :' + error.message)
  console.error('error happened,and error code is :' + error.code)
489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538
})
```

### off('error')<sup>9+</sup><a name = error_off></a>

off(type: 'error'): void

取消监听播放的错误事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                      |
| ------ | ------ | ---- | ----------------------------------------- |
| type   | string | 是   | 错误事件回调类型,取消注册的事件:'error' |

**示例:**

```js
avPlayer.off('error')
```

### prepare<sup>9+</sup><a name=avplayer_prepare></a>

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

通过回调方式准备播放视频,需在[stateChange](#stateChange_on)事件成功触发至initialized状态后,才能调用。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                 |
| -------- | -------- | ---- | -------------------- |
| callback | function | 是   | 准备播放的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |
| 5400106  | Unsupport format. Return by callback.      |

**示例:**

```js
avPlayer.prepare((err) => {
539 540 541 542 543
  if (err == null) {
    console.info('prepare success');
  } else {
    console.error('prepare filed,error message is :' + err.message)
  }
544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573
})
```

### prepare<sup>9+</sup>

prepare(): Promise\<void>

通过Promise方式准备播放视频,需在[stateChange](#stateChange_on)事件成功触发至initialized状态后,才能调用。

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

**返回值:**

| 类型           | 说明                      |
| -------------- | ------------------------- |
| Promise\<void> | 准备播放的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |
| 5400106  | Unsupport format. Return by promise.      |

**示例:**

```js
avPlayer.prepare().then(() => {
574
  console.info('prepare success');
575
}, (err) => {
576
  console.error('prepare filed,error message is :' + err.message)
577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605
})
```

### play<sup>9+</sup><a name=avplayer_play></a>

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

通过回调方式开始播放音视频资源,只能在prepared/paused/complete状态调用。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                 |
| -------- | -------- | ---- | -------------------- |
| callback | function | 是   | 开始播放的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |

**示例:**

```js
avPlayer.play((err) => {
606 607 608 609 610
  if (err == null) {
    console.info('play success');
  } else {
    console.error('play filed,error message is :' + err.message)
  }
611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639
})
```

### play<sup>9+</sup>

play(): Promise\<void>

通过Promise方式开始播放音视频资源,只能在prepared/paused/complete状态调用。

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

**返回值:**

| 类型           | 说明                      |
| -------------- | ------------------------- |
| Promise\<void> | 开始播放的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |

**示例:**

```js
avPlayer.play().then(() => {
640
  console.info('play success');
641
}, (err) => {
642
  console.error('play filed,error message is :' + err.message)
643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671
})
```

### pause<sup>9+</sup><a name=avplayer_pause></a>

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

通过回调方式暂停播放音视频资源,只能在playing状态调用。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                 |
| -------- | -------- | ---- | -------------------- |
| callback | function | 是   | 暂停播放的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |

**示例:**

```js
avPlayer.pause((err) => {
672 673 674 675 676
  if (err == null) {
    console.info('pause success');
  } else {
    console.error('pause filed,error message is :' + err.message)
  }
677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705
})
```

### pause<sup>9+</sup>

pause(): Promise\<void>

通过Promise方式暂停播放音视频资源,只能在playing状态调用。

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

**返回值:**

| 类型           | 说明                      |
| -------------- | ------------------------- |
| Promise\<void> | 暂停播放的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |

**示例:**

```js
avPlayer.pause().then(() => {
706
  console.info('pause success');
707
}, (err) => {
708
  console.error('pause filed,error message is :' + err.message)
709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737
})
```

### stop<sup>9+</sup><a name=avplayer_stop></a>

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

通过回调方式停止播放音视频资源,只能在prepared/playing/paused/complete状态调用。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                 |
| -------- | -------- | ---- | -------------------- |
| callback | function | 是   | 停止播放的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |

**示例:**

```js
avPlayer.stop((err) => {
738 739 740 741 742
  if (err == null) {
    console.info('stop success');
  } else {
    console.error('stop filed,error message is :' + err.message)
  }
743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771
})
```

### stop<sup>9+</sup>

stop(): Promise\<void>

通过Promise方式停止播放音视频资源,只能在prepared/playing/paused/complete状态调用。

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

**返回值:**

| 类型           | 说明                      |
| -------------- | ------------------------- |
| Promise\<void> | 停止播放的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |

**示例:**

```js
avPlayer.stop().then(() => {
772
  console.info('stop success');
773
}, (err) => {
774
  console.error('stop filed,error message is :' + err.message)
775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803
})
```

### reset<sup>9+</sup><a name=avplayer_reset></a>

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

通过回调方式重置播放,只能在initialized/prepared/playing/paused/complete/stopped/error状态调用。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                 |
| -------- | -------- | ---- | -------------------- |
| callback | function | 是   | 重置播放的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |

**示例:**

```js
avPlayer.reset((err) => {
804 805 806 807 808
  if (err == null) {
    console.info('reset success');
  } else {
    console.error('reset filed,error message is :' + err.message)
  }
809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837
})
```

### reset<sup>9+</sup>

reset(): Promise\<void>

通过Promise方式通过Promise方式重置播放,只能在initialized/prepared/playing/paused/complete/stopped/error状态调用。

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

**返回值:**

| 类型           | 说明                      |
| -------------- | ------------------------- |
| Promise\<void> | 重置播放的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |

**示例:**

```js
avPlayer.reset().then(() => {
838
  console.info('reset success');
839
}, (err) => {
840
  console.error('reset filed,error message is :' + err.message)
841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869
})
```

### release<sup>9+</sup><a name=avplayer_release></a>

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

通过回调方式销毁播放资源,除released状态,都可以调用。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                 |
| -------- | -------- | ---- | -------------------- |
| callback | function | 是   | 销毁播放的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |

**示例:**

```js
avPlayer.release((err) => {
870 871 872 873 874
  if (err == null) {
    console.info('reset success');
  } else {
    console.error('release filed,error message is :' + err.message)
  }
875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903
})
```

### release<sup>9+</sup>

release(): Promise\<void>

通过Promise方式通过Promise方式销毁播放,除released状态,都可以调用。

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

**返回值:**

| 类型           | 说明                      |
| -------------- | ------------------------- |
| Promise\<void> | 销毁播放的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |

**示例:**

```js
avPlayer.release().then(() => {
904
  console.info('release success');
905
}, (err) => {
906
  console.error('release filed,error message is :' + err.message)
907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934
})
```

### getTrackDescription<sup>9+</sup>

getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void

通过回调方式获取音视频轨道信息,可以在prepared/playing/paused状态调用。

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

**参数:**

| 参数名   | 类型                                                         | 必填 | 说明                                         |
| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- |
| callback | AsyncCallback<Array<[MediaDescription](#mediadescription8)>> | 是   | 音视频轨道信息MediaDescription数组回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |

**示例:**

```js
935 936 937 938 939 940
function printfDescription(obj) {
  for (let item in obj) {
    let property = obj[item];
    console.info('audio key is ' + item);
    console.info('audio value is ' + property);
  }
941 942
}

943
avPlayer.getTrackDescription((error, arrList) => {
944 945 946
  if ((arrList) != null) {
    for (let i = 0; i < arrList.length; i++) {
      printfDescription(arrList[i]);
947
    }
948 949 950
  } else {
    console.log(`video getTrackDescription fail, error:${error}`);
  }
951 952 953 954 955 956 957
});
```

### getTrackDescription<sup>9+</sup>

getTrackDescription(): Promise\<Array\<MediaDescription>>

958
通过Promise方式获取音视频轨道信息,可以在prepared/playing/paused状态调用。
959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979

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

**返回值:**

| 类型                                                   | 说明                                              |
| ------------------------------------------------------ | ------------------------------------------------- |
| Promise<Array<[MediaDescription](#mediadescription8)>> | 音视频轨道信息MediaDescription数组Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |

**示例:**

```js
let arrayDescription;
980

981 982 983 984 985 986
function printfDescription(obj) {
  for (let item in obj) {
    let property = obj[item];
    console.info('audio key is ' + item);
    console.info('audio value is ' + property);
  }
987
}
988
avPlayer.getTrackDescription().then((arrList) => {
989 990 991 992 993
  if (arrList != null) {
    arrayDescription = arrList;
  } else {
    console.log('video getTrackDescription fail');
  }
994
}).catch((error) => {
995
  console.info(`video catchCallback, error:${error}`);
996 997
});
for (let i = 0; i < arrayDescription.length; i++) {
998
  printfDescription(arrayDescription[i]);
999 1000 1001
}
```

1002
### seek<sup>9+</sup><a name=avplayer_seek></a>
1003 1004 1005 1006

seek(timeMs: number, mode?:SeekMode): void

跳转到指定播放位置,只能在prepared/playing/paused/complete状态调用,可以通过[seekDone事件](#seekDone_on)确认是否生效。
X
live  
xxb-wzy 已提交
1007
注:直播场景不支持seek。
1008 1009 1010 1011 1012 1013 1014 1015

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

**参数:**

| 参数名 | 类型                   | 必填 | 说明                                                         |
| ------ | ---------------------- | ---- | ------------------------------------------------------------ |
| timeMs | number                 | 是   | 指定的跳转时间节点,单位毫秒(ms),取值范围为[0, [duration](#avplayer_duration)]。 |
1016
| mode   | [SeekMode](#seekmode8) | 否   | 基于视频I帧的跳转模式,默认为SEEK_PREV_SYNC模式,**仅在视频资源播放时设置**。 |
1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037

**示例:**

```js
let seekTime = 1000
avPlayer.seek(seekTime, media.SeekMode.SEEK_PREV_SYNC)
```

### on('seekDone')<sup>9+</sup><a name = seekDone_on></a>

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

监听seek生效的事件。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | seek生效的事件回调类型,支持的事件:'seekDone',每次调用seek后都会回调此事件。 |
Z
zengyawen 已提交
1038
| callback | Callback\<number> | 是   | seek生效的事件回调方法,只会上报用户请求的time位置。<br/>**视频播放:**[SeekMode](#seekmode8)会造成实际跳转位置与用户设置产生偏差,精准位置需要通过currentTime获取,事件回调的time仅代表完成用户某一次请求。 |
1039 1040 1041 1042 1043

**示例:**

```js
avPlayer.on('seekDone', (seekDoneTime:number) => {
1044
  console.info('seekDone success,and seek time is:' + seekDoneTime)
1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072
})
```

### off('seekDone')<sup>9+</sup><a name = seekDone_off></a>

off(type: 'seekDone'): void

取消监听seek生效的事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                 |
| ------ | ------ | ---- | ---------------------------------------------------- |
| type   | string | 是   | seek生效的事件回调类型,取消注册的事件:'seekDone'。 |

**示例:**

```js
avPlayer.off('seekDone')
```

### setSpeed<sup>9+</sup>

setSpeed(speed: PlaybackSpeed): void

设置倍速模式,只能在prepared/playing/paused/complete状态调用,可以通过[speedDone事件](#speedDone_on)确认是否生效。
X
live  
xxb-wzy 已提交
1073
注:直播场景不支持setSpeed。
1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085

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

**参数:**

| 参数名 | 类型                             | 必填 | 说明               |
| ------ | -------------------------------- | ---- | ------------------ |
| speed  | [PlaybackSpeed](#playbackspeed8) | 是   | 指定播放倍速模式。 |

**示例:**

```js
1086
avPlayer.setSpeed(media.PlaybackSpeed.SPEED_FORWARD_2_00_X)
1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101
```

### on('speedDone')<sup>9+</sup><a name = speedDone_on></a>

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

监听setSpeed生效的事件

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | setSpeed生效的事件回调类型,支持的事件:'speedDone',每次调用setSpeed后都会回调此事件。 |
Z
zengyawen 已提交
1102
| callback | Callback\<number> | 是   | setSpeed生效的事件回调方法,上报生效的倍速模式,具体见[PlaybackSpeed](#playbackspeed8)。 |
1103 1104 1105 1106 1107

**示例:**

```js
avPlayer.on('speedDone', (speed:number) => {
1108
  console.info('speedDone success,and speed value is:' + speed)
1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143
})
```

### off('speedDone')<sup>9+</sup><a name = speedDone_off></a>

off(type: 'speedDone'): void

取消监听setSpeed生效的事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                      |
| ------ | ------ | ---- | --------------------------------------------------------- |
| type   | string | 是   | setSpeed生效的事件回调类型,取消注册的事件:'speedDone'。 |

**示例:**

```js
avPlayer.off('speedDone')
```

### setBitrate<sup>9+</sup>

setBitrate(bitrate: number): void

选择要播放的指定比特率,仅对**HLS协议网络流**有效,只能在prepared/playing/paused/complete状态调用,可以通过[bitrateDone](#bitrateDone_on)事件确认是否生效。

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

**参数:**

| 参数名  | 类型   | 必填 | 说明                                                         |
| ------- | ------ | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
1144
| bitrate | number | 是   | 指定比特率,可以通过[availableBitrates](#availableBitrates_on)事件获得当前HLS协议流可用的比特率,如果用户指定的比特率不在此列表中,则播放器将从可用比特率列表中选择最小和最接近的比特率。如果通过availableBitrates事件获得的比特率列表长度为0,则不支持指定比特率,也不会产生bitrateDone回调。 |
1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171

**示例:**

```js
let bitrate = 96000
avPlayer.setBitrate(bitrate)
```

### on('bitrateDone')<sup>9+</sup><a name = bitrateDone_on></a>

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

监听setBitrate生效的事件。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | setBitrate生效的事件回调类型,支持的事件:'bitrateDone',每次调用setBitrate后都会回调此事件。 |
| callback | function | 是   | setBitrate生效的事件回调方法,上报生效的比特率。             |

**示例:**

```js
avPlayer.on('bitrateDone', (bitrate:number) => {
1172
  console.info('bitrateDone success,and bitrate value is:' + bitrate)
1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208
})
```

### off('bitrateDone')<sup>9+</sup><a name = bitrateDone_off></a>

off(type: 'bitrateDone'): void

取消监听setBitrate生效的事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type   | string | 是   | setBitrate生效的事件回调类型,取消注册的事件:'bitrateDone'。 |

**示例:**

```js
avPlayer.off('bitrateDone')
```

### on('availableBitrates')<sup>9+</sup><a name = availableBitrates_on></a>

on(type: 'availableBitrates', callback: (bitrates: Array\<number>) => void): void

监听HLS协议流可用的比特率列表,只会在切换prepared状态后上报。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | HLS协议可用比特率上报事件回调类型,支持的事件:'availableBitrates',只会在prepared之后上报一次。 |
1209
| callback | function | 是   | HLS协议可用比特率上报事件回调方法,使用数组存放支持的比特率。如果数组长度为0,则不支持指定比特率。 |
1210 1211 1212 1213 1214

**示例:**

```js
avPlayer.on('availableBitrates', (bitrates: Array<number>) => {
1215
  console.info('availableBitrates success,and availableBitrates length is:' + bitrates.length)
1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278
})
```

### off('availableBitrates')<sup>9+</sup><a name = availableBitrates_off></a>

off(type: 'availableBitrates'): void

取消监听HLS协议流可用的比特率列表。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type   | string | 是   | HLS协议可用比特率上报事件回调类型,取消注册的事件:'availableBitrates'。 |

**示例:**

```js
avPlayer.off('availableBitrates')
```

### setVolume<sup>9+</sup>

setVolume(volume: number): void

设置媒体播放音量,只能在prepared/playing/paused/complete状态调用,可以通过[volumeChange事件](#volumeChange_on)确认是否生效。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| volume | number | 是   | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |

**示例:**

```js
let volume = 1.0
avPlayer.setVolume(volume)
```

### on('volumeChange')<sup>9+</sup><a name = volumeChange_on></a>

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

监听setVolume生效的事件。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | setVolume生效的事件回调类型,支持的事件:'volumeChange',每次调用setVolume后都会回调此事件。 |
| callback | function | 是   | setVolume生效的事件回调方法,上报生效的媒体音量。            |

**示例:**

```js
avPlayer.on('volumeChange', (vol:number) => {
1279
  console.info('volumeChange success,and new volume is :' + vol)
1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294
})
```

### off('volumeChange')<sup>9+</sup><a name = volumeChange_off></a>

off(type: 'volumeChange'): void

取消监听setVolume生效的事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
W
wusongqing 已提交
1295
| type   | string | 是   | setVolume生效的事件回调类型,取消注册的事件:'volumeChange'。 |
1296 1297 1298 1299 1300 1301 1302 1303 1304

**示例:**

```js
avPlayer.off('volumeChange')
```

### on('endOfStream')<sup>9+</sup><a name = endOfStream_on></a>

Z
zengyawen 已提交
1305
on(type: 'endOfStream', callback: Callback\<void>): void
1306 1307 1308 1309 1310 1311 1312 1313 1314 1315

监听资源播放至结尾的事件;如果用户设置**loop=1**,播放会跳转至开头重播;如果用户没有设置loop,会通过[stateChange](#stateChange_on)上报completed状态。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 资源播放至结尾的事件回调类型,支持的事件:'endOfStream',当播放至结尾时会上报此事件。 |
Z
zengyawen 已提交
1316
| callback | Callback\<void> | 是   | 资源播放至结尾的事件回调方法。                               |
1317 1318 1319 1320 1321

**示例:**

```js
avPlayer.on('endOfStream', () => {
1322
  console.info('endOfStream success')
1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350
})
```

### off('endOfStream')<sup>9+</sup><a name = endOfStream_off></a>

off(type: 'endOfStream'): void

取消监听资源播放至结尾的事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type   | string | 是   | 资源播放至结尾的事件回调类型,取消注册的事件:'endOfStream'。 |

**示例:**

```js
avPlayer.off('endOfStream')
```

### on('timeUpdate')<sup>9+</sup><a name = timeUpdate_on></a>

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

监听资源播放当前时间,单位为毫秒(ms),用于刷新进度条当前位置,默认间隔1s时间上报,因用户操作(seek)产生的时间变化会立刻上报。
X
live  
xxb-wzy 已提交
1351
注:直播场景不支持timeUpdate上报。
1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                           |
| -------- | -------- | ---- | ---------------------------------------------- |
| type     | string   | 是   | 时间更新的回调类型,支持的事件:'timeUpdate'。 |
| callback | function | 是   | 当前时间。                                     |

**示例:**

```js
avPlayer.on('timeUpdate', (time:number) => {
1366
  console.info('timeUpdate success,and new time is :' + time)
1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394
})
```

### off('timeUpdate')<sup>9+</sup><a name = timeUpdate_off></a>

off(type: 'timeUpdate'): void

取消监听资源播放当前时间。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                               |
| ------ | ------ | ---- | -------------------------------------------------- |
| type   | string | 是   | 时间更新的回调类型,取消注册的事件:'timeUpdate'。 |

**示例:**

```js
avPlayer.off('timeUpdate')
```

### on('durationUpdate')<sup>9+</sup><a name = durationUpdate_on></a>

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

监听资源播放资源的时长,单位为毫秒(ms),用于刷新进度条长度,默认只在prepared上报一次,同时允许一些特殊码流刷新多次时长。
X
live  
xxb-wzy 已提交
1395
注:直播场景不支持durationUpdate上报。
1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                               |
| -------- | -------- | ---- | -------------------------------------------------- |
| type     | string   | 是   | 时长更新的回调类型,支持的事件:'durationUpdate'。 |
| callback | function | 是   | 资源时长。                                         |

**示例:**

```js
avPlayer.on('durationUpdate', (duration) => {
1410
  console.info('durationUpdate success,new duration is :' + duration)
1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452
})
```

### off('durationUpdate')<sup>9+</sup><a name = durationUpdate_off></a>

off(type: 'durationUpdate'): void

取消监听资源播放资源的时长。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                   |
| ------ | ------ | ---- | ------------------------------------------------------ |
| type   | string | 是   | 时长更新的回调类型,取消注册的事件:'durationUpdate'。 |

**示例:**

```js
avPlayer.off('durationUpdate')
```

### on('bufferingUpdate')<sup>9+</sup><a name = bufferingUpdate_on></a>

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

订阅音视频缓存更新事件,仅网络播放支持该订阅事件。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 播放缓存事件回调类型,支持的事件:'bufferingUpdate'。        |
| callback | function | 是   | 播放缓存事件回调方法。<br/>[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时,value值有效,否则固定为0。 |

**示例:**

```js
avPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => {
1453
  console.info('bufferingUpdate success,and infoType value is:' + infoType + ', value is :' + value)
1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489
})
```

### off('bufferingUpdate')<sup>9+</sup><a name = bufferingUpdate_off></a>

off(type: 'bufferingUpdate'): void

取消监听音视频缓存更新事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                      |
| ------ | ------ | ---- | --------------------------------------------------------- |
| type   | string | 是   | 播放缓存事件回调类型,取消注册的事件:'bufferingUpdate'。 |

**示例:**

```js
avPlayer.off('bufferingUpdate')
```

### on('startRenderFrame')<sup>9+</sup><a name = startRenderFrame_on></a>

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

订阅视频播放开始首帧渲染的更新事件,仅视频播放支持该订阅事件,该事件仅代表播放服务将第一帧画面送显示模块,实际效果依赖显示服务渲染性能。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 视频播放开始首帧渲染事件回调类型,支持的事件:'startRenderFrame'。 |
Z
zengyawen 已提交
1490
| callback | Callback\<void> | 是   | 视频播放开始首帧渲染事件回调方法。                           |
1491 1492 1493 1494 1495

**示例:**

```js
avPlayer.on('startRenderFrame', () => {
1496
  console.info('startRenderFrame success')
1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538
})
```

### off('startRenderFrame')<sup>9+</sup><a name = startRenderFrame_off></a>

off(type: 'startRenderFrame'): void

取消监听视频播放开始首帧渲染的更新事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type   | string | 是   | 视频播放开始首帧渲染事件回调类型,取消注册的事件:'startRenderFrame'。 |

**示例:**

```js
avPlayer.off('startRenderFrame')
```

### on('videoSizeChange')<sup>9+</sup><a name = videoSizeChange_on></a>

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

监听视频播放宽高变化事件,仅视频播放支持该订阅事件,默认只在prepread状态上报一次,但HLS协议码流会在切换分辨率时上报;

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 视频播放宽高变化事件回调类型,支持的事件:'videoSizeChange'。 |
| callback | function | 是   | 视频播放宽高变化事件回调方法,width表示宽,height表示高。    |

**示例:**

```js
avPlayer.on('videoSizeChange', (width: number, height: number) => {
1539
  console.info('videoSizeChange success,and width is:' + width + ', height is :' + height)
1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580
})
```

### off('videoSizeChange')<sup>9+</sup><a name = videoSizeChange_off></a>

off(type: 'videoSizeChange'): void

取消监听视频播放宽高变化事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type   | string | 是   | 视频播放宽高变化事件回调类型,取消注册的事件:'videoSizeChange'。 |

**示例:**

```js
avPlayer.off('videoSizeChange')
```

### on('audioInterrupt')<sup>9+</sup><a name = audioInterrupt_on></a>

on(type: 'audioInterrupt', callback: (info: audio.InterruptEvent) => void): void

监听音频焦点变化事件,多个音视频资源同时播放时,会根据音频焦点模型[audio.InterruptMode](js-apis-audio.md#interruptmode9)触发此事件。

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

**参数:**

| 参数名   | 类型                                                         | 必填 | 说明                                                     |
| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- |
| type     | string                                                       | 是   | 音频焦点变化事件回调类型,支持的事件:'audioInterrupt'。 |
| callback | [audio.InterruptEvent<sup>9+</sup>](js-apis-audio.md#interruptevent9) | 是   | 音频焦点变化事件回调方法。                               |

**示例:**

```js
1581 1582
import audio from '@ohos.multimedia.audio';

1583
avPlayer.on('audioInterrupt', (info: audio.InterruptEvent) => {
1584
  console.info('audioInterrupt success,and InterruptEvent info is:' + info)
1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609
})
```

### off('audioInterrupt')<sup>9+</sup><a name = audioInterrupt_off></a>

off(type: 'audioInterrupt'): void

取消监听音频焦点变化事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type   | string | 是   | 音频焦点变化事件回调类型,取消注册的事件:'audioInterrupt'。 |

**示例:**

```js
avPlayer.off('audioInterrupt')
```

## AVPlayerState<sup>9+</sup><a name = avplayerstate></a>

Z
zengyawen 已提交
1610
[AVPlayer](#avplayer9)的状态机,可通过state属性主动获取当前状态,也可通过监听[stateChange](#stateChange_on)事件上报当前状态,状态机之间的切换规则,可参考[音频播放开发指导](../../media/using-avplayer-for-playback.md)
1611 1612 1613 1614 1615

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

|              名称               |  类型  | 说明                                                         |
| :-----------------------------: | :----: | :----------------------------------------------------------- |
1616
|              idle               | string | 闲置状态,AVPlayer刚被创建[createAVPlayer()](#mediacreateavplayer9)或者调用了reset()方法之后,进入Idle状态。<br/>首次创建createAVPlayer(),所有属性都为默认值。<br/>调用reset()方法,url<sup>9+</sup> 或 fdSrc<sup>9+</sup>或dataSrc<sup>10+</sup>属性及loop属性会被重置,其他用户设置的属性将被保留。 |
1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637
|           initialized           | string | 资源初始化,在Idle 状态设置 url<sup>9+</sup> 或 fdSrc<sup>9+</sup>属性,AVPlayer会进入initialized状态,此时可以配置窗口、音频等静态属性。 |
|            prepared             | string | 已准备状态,在initialized状态调用prepare()方法,AVPlayer会进入prepared状态,此时播放引擎的资源已准备就绪。 |
|             playing             | string | 正在播放状态,在prepared/paused/completed状态调用play()方法,AVPlayer会进入playing状态。 |
|             paused              | string | 暂停状态,在playing状态调用pause方法,AVPlayer会进入paused状态。 |
|            completed            | string | 播放至结尾状态,当媒体资源播放至结尾时,如果用户未设置循环播放(loop = 1),AVPlayer会进入completed状态,此时调用play()会进入playing状态和重播,调用stop()会进入stopped状态。 |
|             stopped             | string | 停止状态,在prepared/playing/paused/completed状态调用stop()方法,AVPlayer会进入stopped状态,此时播放引擎只会保留属性,但会释放内存资源,可以调用prepare()重新准备,也可以调用reset()重置,或者调用release()彻底销毁。 |
|            released             | string | 销毁状态,销毁与当前AVPlayer关联的播放引擎,无法再进行状态转换,调用release()方法后,会进入released状态,结束流程。 |
| error<a name = error_state></a> | string | 错误状态,当**播放引擎**发生**不可逆的错误**,详见[错误分类](#error_info),则会转换至当前状态,可以调用reset()重置,也可以调用release()销毁重建。<br/>**注意:** 区分error状态和 [on('error')](#error_on)<br/>1、进入error状态时,会触发[on('error')](#error_on)监听事件,可以通过[on('error')](#error_on)事件获取详细错误信息;<br/>2、处于error状态时,播放服务进入不可播控的状态,要求客户端设计容错机制,使用reset()重置或者release()销毁重建;<br/>3、如果客户端收到[on('error')](#error_on),但未进入error状态:<br/>原因1:客户端未按状态机调用API或传入参数错误,被AVPlayer拦截提醒,需要客户端调整代码逻辑;<br/>原因2:播放过程发现码流问题,导致容器、解码短暂异常,不影响连续播放和播控操作的,不需要客户端设计容错机制。 |

## AVFileDescriptor<sup>9+</sup>

音视频文件资源描述,一种特殊资源的播放方式,使用场景:应用中的音频资源被连续存储在同一个文件中,需要根据偏移量和长度进行播放。

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

| 名称   | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| fd     | number | 是   | 资源句柄,通过resourceManager.getRawFileDescriptor获取。     |
| offset | number | 是   | 资源偏移量,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误。 |
| length | number | 是   | 资源长度,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误。 |

1638 1639 1640 1641 1642 1643 1644 1645
## AVDataSrcDescriptor<sup>10+</sup>

音视频文件资源描述,用于DataSource播放方式,使用场景:应用在未获取完整音视频资源时,允许用户创建播放实例并开始播放,达到提前播放的目的。

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

| 名称   | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
1646
| fileSize     | number | 是   | 待播放文件大小(字节),-1代表大小未知。如果fileSize设置为-1, 播放模式类似于直播,不能进行seek及setSpeed操作,不能设置loop属性,因此不能重新播放。 |
1647 1648
| callback | function | 是   | 用户设置的回调函数,用于填写数据。<br>- buffer,ArrayBuffer类型,表示被填写的内存,必选。<br>- length,number类型,表示被填写内存的最大长度,必选。<br>- pos,number类型,表示填写的数据在资源文件中的位置,可选,当fileSize设置为-1时,该参数禁止被使用。 |

1649

1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696
## SeekMode<sup>8+</sup>

视频播放的Seek模式枚举,可通过seek方法作为参数传递下去。

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

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

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

视频播放的倍速枚举,可通过setSpeed方法作为参数传递下去。

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

| 名称                 | 值   | 说明                           |
| -------------------- | ---- | ------------------------------ |
| 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倍。 |

## VideoScaleType<sup>9+</sup>

枚举,视频缩放模式。

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

| 名称                      | 值   | 说明                                             |
| ------------------------- | ---- | ------------------------------------------------ |
| VIDEO_SCALE_TYPE_FIT      | 0    | 视频拉伸至与窗口等大。                           |
| VIDEO_SCALE_TYPE_FIT_CROP | 1    | 保持视频宽高比拉伸至填满窗口,内容可能会有裁剪。 |

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

通过key-value方式获取媒体信息。

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

**示例:**

```js
import media from '@ohos.multimedia.media'
function printfItemDescription(obj, key) {
1697 1698 1699
  let property = obj[key];
  console.info('audio key is ' + key); // 通过key值获取对应的value。key值具体可见[MediaDescriptionKey]
  console.info('audio value is ' + property); //对应key值得value。其类型可为任意类型,具体key对应value的类型可参考[MediaDescriptionKey]
1700 1701 1702
}
let audioPlayer = media.createAudioPlayer();
audioPlayer.getTrackDescription((error, arrList) => {
1703 1704 1705
  if (arrList != null) {
    for (let i = 0; i < arrList.length; i++) {
      printfItemDescription(arrList[i], media.MediaDescriptionKey.MD_KEY_TRACK_TYPE);  //打印出每条轨道MD_KEY_TRACK_TYPE的值
1706
    }
1707 1708 1709
  } else {
    console.log(`audio getTrackDescription fail, error:${error}`);
  }
1710 1711 1712 1713 1714 1715 1716
});
```

## AVRecorder<sup>9+</sup>

音视频录制管理类,用于音视频媒体录制。在调用AVRecorder的方法前,需要先通过createAVRecorder()构建一个AVRecorder实例。

Z
zengyawen 已提交
1717 1718 1719 1720 1721
音视频录制demo可参考:[音频录制开发指导](../../media/using-avrecorder-for-recording.md)[视频录制开发指导](../../media/video-recording.md)

> **说明:**
>
> 使用相机进行视频录制时,需要与相机模块配合,相机模块接口开放状态以及使用详情见[相机管理](js-apis-camera.md)。
1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738

### 属性

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

| 名称    | 类型                                 | 可读 | 可写 | 说明               |
| ------- | ------------------------------------ | ---- | ---- | ------------------ |
| state9+ | [AVRecorderState](#avrecorderstate9) | 是   | 否   | 音视频录制的状态。 |

### prepare<sup>9+</sup><a name=avrecorder_prepare></a>

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

异步方式进行音视频录制的参数设置。通过注册回调函数获取返回值。

**需要权限:** ohos.permission.MICROPHONE

1739 1740 1741
不涉及音频录制时,可以不需要获取ohos.permission.MICROPHONE权限。

使用相机视频录制还需要与相机模块配合,权限获取以及接口使用详见[相机管理](js-apis-camera.md)
1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765

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

**参数:**

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

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                |
| -------- | --------------------------------------- |
| 201      | Permission denied. Return by callback.  |
| 401      | Parameter error. Return by callback.    |
| 5400102  | Operate not permit. Return by callback. |
| 5400105  | Service died. Return by callback.       |

**示例:**

```js
1766
// 配置参数以实际硬件设备支持的范围为准
1767
let AVRecorderProfile = {
1768 1769 1770 1771 1772 1773 1774 1775 1776 1777
  audioBitrate : 48000,
  audioChannels : 2,
  audioCodec : media.CodecMimeType.AUDIO_AAC,
  audioSampleRate : 48000,
  fileFormat : media.ContainerFormatType.CFT_MPEG_4,
  videoBitrate : 2000000,
  videoCodec : media.CodecMimeType.VIDEO_AVC,
  videoFrameWidth : 640,
  videoFrameHeight : 480,
  videoFrameRate : 30
1778 1779
}
let AVRecorderConfig = {
1780 1781 1782 1783 1784 1785
  audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC,
  videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV,
  profile : AVRecorderProfile,
  url : 'fd://', // 文件需先由调用者创建,赋予读写权限,将文件fd传给此参数,eg.fd://45
  rotation : 0, // 合理值0、90、180、270,非合理值prepare接口将报错
  location : { latitude : 30, longitude : 130 }
1786 1787
}

1788
avRecorder.prepare(AVRecorderConfig, (err) => {
1789 1790 1791 1792 1793
  if (err == null) {
    console.info('prepare success');
  } else {
    console.error('prepare failed and error is ' + err.message);
  }
1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804
})
```

### prepare<sup>9+</sup>

prepare(config: AVRecorderConfig): Promise\<void>

异步方式进行音视频录制的参数设置。通过Promise获取返回值。

**需要权限:** ohos.permission.MICROPHONE

1805 1806 1807
不涉及音频录制时,可以不需要获ohos.permission.MICROPHONE权限。

使用相机视频录制还需要与相机模块配合,权限获取以及接口使用详见[相机管理](js-apis-camera.md)
1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836

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

**参数:**

| 参数名 | 类型                                   | 必填 | 说明                       |
| ------ | -------------------------------------- | ---- | -------------------------- |
| config | [AVRecorderConfig](#avrecorderconfig9) | 是   | 配置音视频录制的相关参数。 |

**返回值:**

| 类型           | 说明                                       |
| -------------- | ------------------------------------------ |
| Promise\<void> | 异步音视频录制prepare方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                               |
| -------- | -------------------------------------- |
| 201      | Permission denied. Return by promise.  |
| 401      | Parameter error. Return by promise.    |
| 5400102  | Operate not permit. Return by promise. |
| 5400105  | Service died. Return by promise.       |

**示例:**

```js
1837
// 配置参数以实际硬件设备支持的范围为准
1838
let AVRecorderProfile = {
1839 1840 1841 1842 1843 1844 1845 1846 1847 1848
  audioBitrate : 48000,
  audioChannels : 2,
  audioCodec : media.CodecMimeType.AUDIO_AAC,
  audioSampleRate : 48000,
  fileFormat : media.ContainerFormatType.CFT_MPEG_4,
  videoBitrate : 2000000,
  videoCodec : media.CodecMimeType.VIDEO_AVC,
  videoFrameWidth : 640,
  videoFrameHeight : 480,
  videoFrameRate : 30
1849 1850
}
let AVRecorderConfig = {
1851 1852 1853 1854 1855 1856
  audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC,
  videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV,
  profile : AVRecorderProfile,
  url : 'fd://',  // 文件需先由调用者创建,赋予读写权限,将文件fd传给此参数,eg.fd://45
  rotation : 0, // 合理值0、90、180、270,非合理值prepare接口报错
  location : { latitude : 30, longitude : 130 }
1857 1858
}

1859
avRecorder.prepare(AVRecorderConfig).then(() => {
1860
  console.info('prepare success');
1861
}).catch((err) => {
1862
  console.error('prepare failed and catch error is ' + err.message);
1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899
});

```

### getInputSurface<sup>9+</sup><a name=avrecorder_getinputsurface></a>

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

异步方式获得录制需要的surface。此surface提供给调用者,调用者从此surface中获取surfaceBuffer,填入相应的视频数据。

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

需在prepare()事件成功触发后,才能调用getInputSurface()方法。

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

**参数:**

| 参数名   | 类型                   | 必填 | 说明                        |
| -------- | ---------------------- | ---- | --------------------------- |
| callback | AsyncCallback\<string> | 是   | 异步获得surface的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                |
| -------- | --------------------------------------- |
| 5400102  | Operate not permit. Return by callback. |
| 5400103  | IO error. Return by callback.           |
| 5400105  | Service died. Return by callback.       |

**示例:**

```js
let surfaceID = null; // 该surfaceID用于传递给相机接口创造videoOutput

1900
avRecorder.getInputSurface((err, surfaceId) => {
1901 1902 1903 1904 1905 1906
  if (err == null) {
    console.info('getInputSurface success');
    surfaceID = surfaceId;
  } else {
    console.error('getInputSurface failed and error is ' + err.message);
  }
1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943
});

```

### getInputSurface<sup>9+</sup>

getInputSurface(): Promise\<string>

异步方式获得录制需要的surface。此surface提供给调用者,调用者从此surface中获取surfaceBuffer,填入相应的视频数据。

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

需在prepare()事件成功触发后,才能调用getInputSurface方法。

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

**返回值:**

| 类型             | 说明                             |
| ---------------- | -------------------------------- |
| Promise\<string> | 异步获得surface的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                               |
| -------- | -------------------------------------- |
| 5400102  | Operate not permit. Return by promise. |
| 5400103  | IO error. Return by promise.           |
| 5400105  | Service died. Return by promise.       |

**示例:**

```js
let surfaceID = null; // 该surfaceID用于传递给相机接口创造videoOutput

1944
avRecorder.getInputSurface().then((surfaceId) => {
1945 1946
  console.info('getInputSurface success');
  surfaceID = surfaceId;
1947
}).catch((err) => {
1948
  console.error('getInputSurface failed and catch error is ' + err.message);
1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980
});
```

### start<sup>9+</sup><a name=avrecorder_start></a>

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

异步方式开始视频录制。通过注册回调函数获取返回值。

纯音频录制需在prepare()事件成功触发后,才能调用start方法。纯视频录制,音视频录制需在getInputSurface()事件成功触发后,才能调用start方法。

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

**参数:**

| 参数名   | 类型                 | 必填 | 说明                         |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步开始视频录制的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                |
| -------- | --------------------------------------- |
| 5400102  | Operate not permit. Return by callback. |
| 5400103  | IO error. Return by callback.           |
| 5400105  | Service died. Return by callback.       |

**示例:**

```js
1981
avRecorder.start((err) => {
1982 1983 1984 1985 1986
  if (err == null) {
    console.info('start AVRecorder success');
  } else {
    console.error('start AVRecorder failed and error is ' + err.message);
  }
1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018
});
```

### start<sup>9+</sup>

start(): Promise\<void>

异步方式开始视频录制。通过Promise获取返回值。

纯音频录制需在prepare()事件成功触发后,才能调用start方法。纯视频录制,音视频录制需在getInputSurface()事件成功触发后,才能调用start方法。

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

**返回值:**

| 类型           | 说明                                  |
| -------------- | ------------------------------------- |
| Promise\<void> | 异步开始视频录制方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                               |
| -------- | -------------------------------------- |
| 5400102  | Operate not permit. Return by promise. |
| 5400103  | IO error. Return by promise.           |
| 5400105  | Service died. Return by promise.       |

**示例:**

```js
2019
avRecorder.start().then(() => {
2020
  console.info('start AVRecorder success');
2021
}).catch((err) => {
2022
  console.error('start AVRecorder failed and catch error is ' + err.message);
2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054
});
```

### pause<sup>9+</sup><a name=avrecorder_pause></a>

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

异步方式暂停视频录制。通过注册回调函数获取返回值。

需要start()事件成功触发后,才能调用pause方法,可以通过调用resume()接口来恢复录制。

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

**参数:**

| 参数名   | 类型                 | 必填 | 说明                        |
| -------- | -------------------- | ---- | --------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步获得surface的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                |
| -------- | --------------------------------------- |
| 5400102  | Operate not permit. Return by callback. |
| 5400103  | IO error. Return by callback.           |
| 5400105  | Service died. Return by callback.       |

**示例:**

```js
2055
avRecorder.pause((err) => {
2056 2057 2058 2059 2060
  if (err == null) {
    console.info('pause AVRecorder success');
  } else {
    console.error('pause AVRecorder failed and error is ' + err.message);
  }
2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092
});
```

### pause<sup>9+</sup>

pause(): Promise\<void>

异步方式暂停视频录制。通过Promise获取返回值。

需要start()事件成功触发后,才能调用pause方法,可以通过调用resume()接口来恢复录制。

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

**返回值:**

| 类型           | 说明                                  |
| -------------- | ------------------------------------- |
| Promise\<void> | 异步暂停视频录制方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                               |
| -------- | -------------------------------------- |
| 5400102  | Operate not permit. Return by promise. |
| 5400103  | IO error. Return by promise.           |
| 5400105  | Service died. Return by promise.       |

**示例:**

```js
2093
avRecorder.pause().then(() => {
2094
  console.info('pause AVRecorder success');
2095
}).catch((err) => {
2096
  console.error('pause AVRecorder failed and catch error is ' + err.message);
2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128
});
```

### resume<sup>9+</sup><a name=avrecorder_resume></a>

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

异步方式恢复视频录制。通过注册回调函数获取返回值。

需要在pause()事件成功触发后,才能调用resume方法。

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

**参数:**

| 参数名   | 类型                 | 必填 | 说明                         |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步恢复视频录制的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                |
| -------- | --------------------------------------- |
| 5400102  | Operate not permit. Return by callback. |
| 5400103  | IO error. Return by callback.           |
| 5400105  | Service died. Return by callback.       |

**示例:**

```js
2129
avRecorder.resume((err) => {
2130 2131 2132 2133 2134
  if (err == null) {
    console.info('resume AVRecorder success');
  } else {
    console.error('resume AVRecorder failed and error is ' + err.message);
  }
2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166
});
```

### resume<sup>9+</sup>

resume(): Promise\<void>

异步方式恢复视频录制。通过Promise获取返回值。

需要在pause()事件成功触发后,才能调用resume方法。

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

**返回值:**

| 类型           | 说明                                  |
| -------------- | ------------------------------------- |
| Promise\<void> | 异步恢复视频录制方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                               |
| -------- | -------------------------------------- |
| 5400102  | Operate not permit. Return by promise. |
| 5400103  | IO error. Return by promise.           |
| 5400105  | Service died. Return by promise.       |

**示例:**

```js
2167
avRecorder.resume().then(() => {
2168
  console.info('resume AVRecorder success');
2169
}).catch((err) => {
2170
  console.error('resume AVRecorder failed and catch error is ' + err.message);
2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204
});
```

### stop<sup>9+</sup><a name=avrecorder_stop></a>

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

异步方式停止视频录制。通过注册回调函数获取返回值。

需要在start()或pause()事件成功触发后,才能调用stop方法。

纯音频录制时,需要重新调用prepare()接口才能重新录制。纯视频录制,音视频录制时,需要重新调用prepare()和getInputSurface()接口才能重新录制。

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

**参数:**

| 参数名   | 类型                 | 必填 | 说明                         |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步停止视频录制的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                |
| -------- | --------------------------------------- |
| 5400102  | Operate not permit. Return by callback. |
| 5400103  | IO error. Return by callback.           |
| 5400105  | Service died. Return by callback.       |

**示例:**

```js
2205
avRecorder.stop((err) => {
2206 2207 2208 2209 2210
  if (err == null) {
    console.info('stop AVRecorder success');
  } else {
    console.error('stop AVRecorder failed and error is ' + err.message);
  }
2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244
});
```

### stop<sup>9+</sup>

stop(): Promise\<void>

异步方式停止视频录制。通过Promise获取返回值。

需要在start()或pause()事件成功触发后,才能调用stop方法。

纯音频录制时,需要重新调用prepare()接口才能重新录制。纯视频录制,音视频录制时,需要重新调用prepare()和getInputSurface()接口才能重新录制。

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

**返回值:**

| 类型           | 说明                                  |
| -------------- | ------------------------------------- |
| Promise\<void> | 异步停止视频录制方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                               |
| -------- | -------------------------------------- |
| 5400102  | Operate not permit. Return by promise. |
| 5400103  | IO error. Return by promise.           |
| 5400105  | Service died. Return by promise.       |

**示例:**

```js
2245
avRecorder.stop().then(() => {
2246
  console.info('stop AVRecorder success');
2247
}).catch((err) => {
2248
  console.error('stop AVRecorder failed and catch error is ' + err.message);
2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279
});
```

### reset<sup>9+</sup><a name=avrecorder_reset></a>

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

异步方式重置音视频录制。通过注册回调函数获取返回值。

纯音频录制时,需要重新调用prepare()接口才能重新录制。纯视频录制,音视频录制时,需要重新调用prepare()和getInputSurface()接口才能重新录制。

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

**参数:**

| 参数名   | 类型                 | 必填 | 说明                           |
| -------- | -------------------- | ---- | ------------------------------ |
| callback | AsyncCallback\<void> | 是   | 异步重置音视频录制的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                          |
| -------- | --------------------------------- |
| 5400103  | IO error. Return by callback.     |
| 5400105  | Service died. Return by callback. |

**示例:**

```js
2280
avRecorder.reset((err) => {
2281 2282 2283 2284 2285
  if (err == null) {
    console.info('reset AVRecorder success');
  } else {
    console.error('reset AVRecorder failed and error is ' + err.message);
  }
2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316
});
```

### reset<sup>9+</sup>

reset(): Promise\<void>

异步方式重置音视频录制。通过Promise获取返回值。

纯音频录制时,需要重新调用prepare()接口才能重新录制。纯视频录制,音视频录制时,需要重新调用prepare()和getInputSurface()接口才能重新录制。

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

**返回值:**

| 类型           | 说明                                    |
| -------------- | --------------------------------------- |
| Promise\<void> | 异步重置音视频录制方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                         |
| -------- | -------------------------------- |
| 5400103  | IO error. Return by promise.     |
| 5400105  | Service died. Return by promise. |

**示例:**

```js
2317
avRecorder.reset().then(() => {
2318
  console.info('reset AVRecorder success');
2319
}).catch((err) => {
2320
  console.error('reset AVRecorder failed and catch error is ' + err.message);
2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350
});
```

### release<sup>9+</sup><a name=avrecorder_release></a>

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

异步方式释放音视频录制资源。通过注册回调函数获取返回值。

释放音视频录制资源之后,该AVRecorder实例不能再进行任何操作。

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

**参数:**

| 参数名   | 类型                 | 必填 | 说明                               |
| -------- | -------------------- | ---- | ---------------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步释放音视频录制资源的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                          |
| -------- | --------------------------------- |
| 5400105  | Service died. Return by callback. |

**示例:**

```js
2351
avRecorder.release((err) => {
2352 2353 2354 2355 2356
  if (err == null) {
    console.info('release AVRecorder success');
  } else {
    console.error('release AVRecorder failed and error is ' + err.message);
  }
2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386
});
```

### release<sup>9+</sup>

release(): Promise\<void>

异步方式释放音视频录制资源。通过Promise获取返回值。

释放音视频录制资源之后,该AVRecorder实例不能再进行任何操作。

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

**返回值:**

| 类型           | 说明                                        |
| -------------- | ------------------------------------------- |
| Promise\<void> | 异步释放音视频录制资源方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                          |
| -------- | --------------------------------- |
| 5400105  | Service died. Return by callback. |

**示例:**

```js
2387
avRecorder.release().then(() => {
2388
  console.info('release AVRecorder success');
2389
}).catch((err) => {
2390
  console.error('release AVRecorder failed and catch error is ' + err.message);
2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411
});
```

### on('stateChange')<sup>9+</sup><a name=avrecorder_onstatechange></a>

on(type: 'stateChange', callback: (state: AVRecorderState, reason: StateChangeReason) => void): void

订阅录制状态机AVRecorderState切换的事件,当 AVRecorderState状态机发生变化时,会通过订阅的回调方法通知用户。用户只能订阅一个状态机切换事件的回调方法,当用户重复订阅时,以最后一次订阅的回调接口为准。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 状态机切换事件回调类型,支持的事件:'stateChange',用户操作和系统都会触发此事件。 |
| callback | function | 是   | 状态机切换事件回调方法:<br>state: [AVRecorderState](#avrecorderstate9),表示当前播放状态 ;<br>reason: [StateChangeReason](#statechangereason9),表示当前播放状态的切换原因。 |

**示例:**

```js
2412
avRecorder.on('stateChange', async (state, reason) => {
2413
  console.info('case state has changed, new state is :' + state + ',and new reason is : ' + reason);
2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433
});
```

### off('stateChange')<sup>9+</sup>

off(type: 'stateChange'): void

取消订阅播放状态机[AVRecorderState](#avrecorderstate9)切换的事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type   | string | 是   | 状态机切换事件回调类型,支持的事件:'stateChange',用户操作和系统都会触发此事件。 |

**示例:**

```js
2434
avRecorder.off('stateChange');
2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465
```

### on('error')<sup>9+</sup><a name=avrecorder_onerror></a>

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

订阅AVRecorder的错误事件,该事件仅用于错误提示,不需要用户停止播控动作。如果此时[AVRecorderState](#avrecorderstate9)也切至error状态,用户需要通过reset()或者release()退出录制操作。

用户只能订阅一个错误事件的回调方法,当用户重复订阅时,以最后一次订阅的回调接口为准。

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

**参数:**

| 参数名   | 类型          | 必填 | 说明                                                         |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type     | string        | 是   | 录制错误事件回调类型'error'。 <br>- 'error':录制过程中发生错误,触发该事件。 |
| callback | ErrorCallback | 是   | 录制错误事件回调方法。                                       |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                          |
| -------- | --------------------------------- |
| 5400103  | IO error. Return by callback.     |
| 5400105  | Service died. Return by callback. |

**示例:**

```js
2466
avRecorder.on('error', (err) => {
2467
  console.error('case avRecorder.on(error) called, errMessage is ' + err.message);
2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494
});
```

### off('error')<sup>9+</sup>

off(type: 'error'): void

取消订阅录制错误事件,取消后不再接收到AVRecorder的错误事件。

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

**参数:**

| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| type   | string | 是   | 录制错误事件回调类型'error'。 <br>- 'error':录制过程中发生错误,触发该事件。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                          |
| -------- | --------------------------------- |
| 5400103  | IO error. Return by callback.     |
| 5400105  | Service died. Return by callback. |

**示例:**
2495

2496
```js
2497
avRecorder.off('error');
2498
```
2499

2500
## AVRecorderState<sup>9+</sup>
Z
zengyawen 已提交
2501

2502
音视频录制的状态机。可通过state属性获取当前状态。
Z
zengyawen 已提交
2503

2504
**系统能力:** SystemCapability.Multimedia.Media.AVRecorder
2505

2506 2507 2508 2509 2510 2511 2512 2513 2514
| 名称     | 类型   | 说明                                                         |
| -------- | ------ | ------------------------------------------------------------ |
| idle     | string | 闲置状态。此时可以调用[prepare()](#avrecorder_prepare)方法设置录制参数,进入prepared状态。AVRecorder刚被创建,或者在任何非released状态下调用[reset()](#avrecorder_reset)方法,均进入idle状态。 |
| prepared | string | 参数设置完成。此时可以调用[start()](#avrecorder_start)方法开始录制,进入started状态。 |
| started  | string | 正在录制。此时可以调用[pause()](#avrecorder_pause)方法暂停录制,进入paused状态。也可以调用[stop()](#avrecorder_stop)方法结束录制,进入stopped状态。 |
| paused   | string | 录制暂停。此时可以调用[resume()](#avrecorder_resume)方法继续录制,进入started状态。也可以调用[stop()](#avrecorder_stop)方法结束录制,进入stopped状态。 |
| stopped  | string | 录制停止。此时可以调用[prepare()](#avrecorder_prepare)方法设置录制参数,重新进入prepared状态。 |
| released | string | 录制资源释放。此时不能再进行任何操作。在任何其他状态下,均可以通过调用[release()](#avrecorder_release)方法进入released状态。 |
| error    | string | 错误状态。当AVRecorder实例发生不可逆错误,会转换至当前状态。切换至error状态时会伴随[on('error')事件](#avrecorder_onerror),该事件会上报详细错误原因。在error状态时,用户需要调用[reset()](#avrecorder_reset)方法重置AVRecorder实例,或者调用[release()](#avrecorder_release)方法释放资源。 |
2515

2516
## AVRecorderConfig<sup>9+</sup>
2517

2518
表示音视频录制的参数设置。
2519

2520
**系统能力:** SystemCapability.Multimedia.Media.AVRecorder
2521

2522 2523 2524 2525 2526
| 名称            | 类型                                     | 必填 | 说明                                                         |
| --------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ |
| audioSourceType | [AudioSourceType](#audiosourcetype9)     | 否   | 选择录制的音频源类型。选择音频录制时必填。                   |
| videoSourceType | [VideoSourceType](#videosourcetype9)     | 否   | 选择录制的视频源类型。选择视频录制时必填。                   |
| profile         | [AVRecorderProfile](#avrecorderprofile9) | 是   | 录制的profile,必要参数。                                    |
2527
| url             | string                                   | 是   | 录制输出URL:fd://xx (fd number) ![img](figures/zh-cn_image_url.png),必要参数。 |
2528 2529
| rotation        | number                                   | 否   | 录制的视频旋转角度,仅支持0,90,180,270,默认值为0。       |
| location        | [Location](#location)                    | 否   | 录制的地理位置,默认不记录地理位置信息。                     |
2530

2531
通过audioSourceType和videoSourceType区分纯音频录制、纯视频录制或音视频录制。纯音频录制时,仅需要设置audioSourceType;纯视频录制时,仅需要设置videoSourceType;音视频录制时,audioSourceType和videoSourceType均需要设置。
2532

2533
## AVRecorderProfile<sup>9+</sup>
Z
zengyawen 已提交
2534

2535
音视频录制的配置文件。
2536

2537
**系统能力:** SystemCapability.Multimedia.Media.AVRecorder
2538

2539 2540 2541 2542 2543 2544 2545 2546
| 名称             | 类型                                         | 必填 | 说明                                                         |
| ---------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ |
| audioBitrate     | number                                       | 否   | 音频编码比特率,选择音频录制时必填。                         |
| audioChannels    | number                                       | 否   | 音频采集声道数,选择音频录制时必填。                         |
| audioCodec       | [CodecMimeType](#codecmimetype8)             | 否   | 音频编码格式,选择音频录制时必填。当前仅支持AUDIO_AAC。      |
| audioSampleRate  | number                                       | 否   | 音频采样率,选择音频录制时必填。                             |
| fileFormat       | [ContainerFormatType](#containerformattype8) | 是   | 文件的容器格式,必要参数。                                   |
| videoBitrate     | number                                       | 否   | 视频编码比特率,选择视频录制时必填。                         |
2547
| videoCodec       | [CodecMimeType](#codecmimetype8)             | 否   | 视频编码格式,选择视频录制时必填。需要查询设备支持的编码能力(包括编码格式,分辨率大小等)。 |
2548 2549 2550
| videoFrameWidth  | number                                       | 否   | 视频帧的宽,选择视频录制时必填。                             |
| videoFrameHeight | number                                       | 否   | 视频帧的高,选择视频录制时必填。                             |
| videoFrameRate   | number                                       | 否   | 视频帧率,选择视频录制时必填。                               |
2551

2552
## AudioSourceType<sup>9+</sup>
2553

2554
表示视频录制中音频源类型的枚举。
Z
zengyawen 已提交
2555

2556
**系统能力:** SystemCapability.Multimedia.Media.AVRecorder
W
wusongqing 已提交
2557

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

2563
## VideoSourceType<sup>9+</sup>
2564

2565
表示视频录制中视频源类型的枚举。
Z
zengyawen 已提交
2566

2567
**系统能力:** SystemCapability.Multimedia.Media.AVRecorder
2568

2569 2570 2571 2572
| 名称                          | 值   | 说明                            |
| ----------------------------- | ---- | ------------------------------- |
| VIDEO_SOURCE_TYPE_SURFACE_YUV | 0    | 输入surface中携带的是raw data。 |
| VIDEO_SOURCE_TYPE_SURFACE_ES  | 1    | 输入surface中携带的是ES data。  |
2573

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

2576
表示容器格式类型的枚举,缩写为CFT。
Z
zengyawen 已提交
2577

2578
**系统能力:** SystemCapability.Multimedia.Media.Core
2579

2580 2581 2582 2583
| 名称        | 值    | 说明                  |
| ----------- | ----- | --------------------- |
| CFT_MPEG_4  | 'mp4' | 视频的容器格式,MP4。 |
| CFT_MPEG_4A | 'm4a' | 音频的容器格式,M4A。 |
2584

2585
## Location
2586

2587
视频录制的地理位置。
Z
zengyawen 已提交
2588

2589
**系统能力:** SystemCapability.Multimedia.Media.Core
2590

2591 2592 2593 2594
| 名称      | 类型   | 必填 | 说明             |
| --------- | ------ | ---- | ---------------- |
| latitude  | number | 是   | 地理位置的纬度。 |
| longitude | number | 是   | 地理位置的经度。 |
2595

2596
## VideoRecorder<sup>9+</sup>
Z
zengyawen 已提交
2597

2598
> **说明:**
2599
> AVRecorder<sup>9+</sup>发布后停止维护,建议使用[AVRecorder](#avrecorder9)替代。
Z
zengyawen 已提交
2600

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

2603
### 属性
Z
zengyawen 已提交
2604

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

2607
**系统接口:** 该接口为系统接口
Z
zengyawen 已提交
2608

2609 2610 2611
| 名称               | 类型                                   | 可读 | 可写 | 说明             |
| ------------------ | -------------------------------------- | ---- | ---- | ---------------- |
| state<sup>9+</sup> | [VideoRecordState](#videorecordstate9) | 是   | 否   | 视频录制的状态。 |
Z
zengyawen 已提交
2612

2613
### prepare<sup>9+</sup><a name=videorecorder_prepare1></a>
Z
zengyawen 已提交
2614

2615
prepare(config: VideoRecorderConfig, callback: AsyncCallback\<void>): void;
Z
zengyawen 已提交
2616

2617
异步方式进行视频录制的参数设置。通过注册回调函数获取返回值。
B
bird_j 已提交
2618

2619
**需要权限:** ohos.permission.MICROPHONE
2620

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

2623
**系统接口:** 该接口为系统接口
2624

2625
**参数:**
2626

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

2632
**错误码:**
2633

2634
以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)
2635

2636 2637 2638 2639 2640 2641
| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 201      | Permission denied. Return by callback.     |
| 401      | Parameter error. Return by callback.       |
| 5400102  | Operation not allowed. Return by callback. |
| 5400105  | Service died. Return by callback.          |
Z
zengyawen 已提交
2642

W
wusongqing 已提交
2643
**示例:**
Z
zengyawen 已提交
2644

2645
```js
2646
// 配置参数以实际硬件设备支持的范围为准
2647
let videoProfile = {
2648 2649 2650 2651 2652 2653 2654 2655 2656 2657
  audioBitrate : 48000,
  audioChannels : 2,
  audioCodec : 'audio/mp4a-latm',
  audioSampleRate : 48000,
  fileFormat : 'mp4',
  videoBitrate : 2000000,
  videoCodec : 'video/avc',
  videoFrameWidth : 640,
  videoFrameHeight : 480,
  videoFrameRate : 30
2658
}
2659

2660
let videoConfig = {
2661 2662 2663 2664 2665 2666
  audioSourceType : 1,
  videoSourceType : 0,
  profile : videoProfile,
  url : 'fd://xx',   // 文件需先由调用者创建,并给予适当的权限
  orientationHint : 0,
  location : { latitude : 30, longitude : 130 },
2667
}
2668

2669 2670
// asyncallback
videoRecorder.prepare(videoConfig, (err) => {
2671 2672 2673 2674 2675
  if (err == null) {
    console.info('prepare success');
  } else {
    console.error('prepare failed and error is ' + err.message);
  }
2676
})
2677
```
Z
zengyawen 已提交
2678

2679
### prepare<sup>9+</sup><a name=videorecorder_prepare2></a>
Z
zengyawen 已提交
2680

2681
prepare(config: VideoRecorderConfig): Promise\<void>;
Z
zengyawen 已提交
2682

2683
异步方式进行视频录制的参数设置。通过Promise获取返回值。
Z
zengyawen 已提交
2684

2685
**需要权限:** ohos.permission.MICROPHONE
2686

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

2689
**系统接口:** 该接口为系统接口
2690

2691
**参数:**
B
bird_j 已提交
2692

2693 2694 2695 2696 2697 2698 2699 2700 2701
| 参数名 | 类型                                         | 必填 | 说明                     |
| ------ | -------------------------------------------- | ---- | ------------------------ |
| config | [VideoRecorderConfig](#videorecorderconfig9) | 是   | 配置视频录制的相关参数。 |

**返回值:**

| 类型           | 说明                                     |
| -------------- | ---------------------------------------- |
| Promise\<void> | 异步视频录制prepare方法的Promise返回值。 |
2702 2703 2704 2705 2706

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

2707 2708 2709 2710 2711 2712
| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 201      | Permission denied. Return by promise.     |
| 401      | Parameter error. Return by promise.       |
| 5400102  | Operation not allowed. Return by promise. |
| 5400105  | Service died. Return by promise.          |
Z
zengyawen 已提交
2713

W
wusongqing 已提交
2714
**示例:**
2715 2716

```js
2717
// 配置参数以实际硬件设备支持的范围为准
2718
let videoProfile = {
2719 2720 2721 2722 2723 2724 2725 2726 2727 2728
  audioBitrate : 48000,
  audioChannels : 2,
  audioCodec : 'audio/mp4a-latm',
  audioSampleRate : 48000,
  fileFormat : 'mp4',
  videoBitrate : 2000000,
  videoCodec : 'video/avc',
  videoFrameWidth : 640,
  videoFrameHeight : 480,
  videoFrameRate : 30
2729 2730 2731
}

let videoConfig = {
2732 2733 2734 2735 2736 2737
  audioSourceType : 1,
  videoSourceType : 0,
  profile : videoProfile,
  url : 'fd://xx',   // 文件需先由调用者创建,并给予适当的权限
  orientationHint : 0,
  location : { latitude : 30, longitude : 130 },
2738 2739 2740 2741
}

// promise
videoRecorder.prepare(videoConfig).then(() => {
2742
  console.info('prepare success');
2743
}).catch((err) => {
2744
  console.error('prepare failed and catch error is ' + err.message);
Z
zengyawen 已提交
2745 2746
});
```
Z
zengyawen 已提交
2747

2748
### getInputSurface<sup>9+</sup>
Z
zengyawen 已提交
2749

2750
getInputSurface(callback: AsyncCallback\<string>): void;
Z
zengyawen 已提交
2751

2752
异步方式获得录制需要的surface。此surface提供给调用者,调用者从此surface中获取surfaceBuffer,填入相应的数据。
2753

2754 2755 2756
应当注意,填入的视频数据需要携带时间戳(单位ns),buffersize。时间戳的起始时间请以系统启动时间为基准。

只能在[prepare()](#videorecorder_prepare1)接口调用后调用。
2757 2758 2759 2760

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

**系统接口:** 该接口为系统接口
Z
zengyawen 已提交
2761

2762
**参数:**
B
bird_j 已提交
2763

2764 2765 2766
| 参数名   | 类型                   | 必填 | 说明                        |
| -------- | ---------------------- | ---- | --------------------------- |
| callback | AsyncCallback\<string> | 是   | 异步获得surface的回调方法。 |
2767 2768 2769 2770 2771

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

2772 2773 2774 2775 2776
| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |
| 5400103  | I/O error. Return by callback.             |
| 5400105  | Service died. Return by callback.          |
Z
zengyawen 已提交
2777

W
wusongqing 已提交
2778
**示例:**
Z
zengyawen 已提交
2779

2780
```js
2781 2782 2783
// asyncallback
let surfaceID = null;                                               // 传递给外界的surfaceID
videoRecorder.getInputSurface((err, surfaceId) => {
2784 2785 2786 2787 2788 2789
  if (err == null) {
    console.info('getInputSurface success');
    surfaceID = surfaceId;
  } else {
    console.error('getInputSurface failed and error is ' + err.message);
  }
Z
zengyawen 已提交
2790 2791
});
```
Z
zengyawen 已提交
2792

2793
### getInputSurface<sup>9+</sup>
Z
zengyawen 已提交
2794

2795
getInputSurface(): Promise\<string>;
Z
zengyawen 已提交
2796

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

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

2801
只能在[prepare()](#videorecorder_prepare1)接口调用后调用。
Z
zengyawen 已提交
2802

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

2805
**系统接口:** 该接口为系统接口
Z
zengyawen 已提交
2806

2807
**返回值:**
B
bird_j 已提交
2808

2809 2810 2811
| 类型             | 说明                             |
| ---------------- | -------------------------------- |
| Promise\<string> | 异步获得surface的Promise返回值。 |
2812

2813
**错误码:**
2814

2815
以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)
2816

2817 2818 2819 2820 2821
| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |
| 5400103  | I/O error. Return by promise.             |
| 5400105  | Service died. Return by promise.          |
Z
zengyawen 已提交
2822

W
wusongqing 已提交
2823
**示例:**
Z
zengyawen 已提交
2824

2825
```js
2826 2827 2828
// promise
let surfaceID = null;                                               // 传递给外界的surfaceID
videoRecorder.getInputSurface().then((surfaceId) => {
2829 2830
  console.info('getInputSurface success');
  surfaceID = surfaceId;
2831
}).catch((err) => {
2832
  console.error('getInputSurface failed and catch error is ' + err.message);
2833
});
Z
zengyawen 已提交
2834
```
Z
zengyawen 已提交
2835

2836
### start<sup>9+</sup><a name=videorecorder_start1></a>
Z
zengyawen 已提交
2837

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

2840
异步方式开始视频录制。通过注册回调函数获取返回值。
2841

2842
[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface9)后调用,需要依赖数据源先给surface传递数据。
2843

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

2846
**系统接口:** 该接口为系统接口
B
bird_j 已提交
2847

2848
**参数:**
2849

2850 2851 2852
| 参数名   | 类型                 | 必填 | 说明                         |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步开始视频录制的回调方法。 |
2853

2854
**错误码:**
2855

2856 2857 2858 2859 2860 2861 2862
以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |
| 5400103  | I/O error. Return by callback.             |
| 5400105  | Service died. Return by callback.          |
Z
zengyawen 已提交
2863

W
wusongqing 已提交
2864
**示例:**
Z
zengyawen 已提交
2865

2866
```js
2867 2868
// asyncallback
videoRecorder.start((err) => {
2869 2870 2871 2872 2873
  if (err == null) {
    console.info('start videorecorder success');
  } else {
    console.error('start videorecorder failed and error is ' + err.message);
  }
2874
});
Z
zengyawen 已提交
2875
```
2876

2877
### start<sup>9+</sup><a name=videorecorder_start2></a>
2878

2879
start(): Promise\<void>;
B
bird_j 已提交
2880

2881
异步方式开始视频录制。通过Promise获取返回值。
2882

2883
[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface9)后调用,需要依赖数据源先给surface传递数据。
2884

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

2887
**系统接口:** 该接口为系统接口
2888

2889
**返回值:**
2890

2891 2892 2893
| 类型           | 说明                                  |
| -------------- | ------------------------------------- |
| Promise\<void> | 异步开始视频录制方法的Promise返回值。 |
2894

2895
**错误码:**
2896

2897
以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)
2898

2899 2900 2901 2902 2903
| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |
| 5400103  | I/O error. Return by promise.             |
| 5400105  | Service died. Return by promise.          |
2904

W
wusongqing 已提交
2905
**示例:**
2906 2907

```js
2908 2909
// promise
videoRecorder.start().then(() => {
2910
  console.info('start videorecorder success');
2911
}).catch((err) => {
2912
  console.error('start videorecorder failed and catch error is ' + err.message);
2913
});
Z
zengyawen 已提交
2914 2915
```

2916
### pause<sup>9+</sup><a name=videorecorder_pause1></a>
Z
zengyawen 已提交
2917

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

2920
异步方式暂停视频录制。通过注册回调函数获取返回值。
2921

2922 2923 2924 2925 2926
[start()](#videorecorder_start1)后调用。可以通过调用[resume()](#videorecorder_resume1)接口来恢复录制。

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

**系统接口:** 该接口为系统接口
Z
zengyawen 已提交
2927

W
wusongqing 已提交
2928
**参数:**
B
bird_j 已提交
2929

2930 2931 2932
| 参数名   | 类型                 | 必填 | 说明                         |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步暂停视频录制的回调方法。 |
2933

2934
**错误码:**
Z
zengyawen 已提交
2935

2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948
以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |
| 5400103  | I/O error. Return by callback.             |
| 5400105  | Service died. Return by callback.          |

**示例:**

```js
// asyncallback
videoRecorder.pause((err) => {
2949 2950 2951 2952 2953
  if (err == null) {
    console.info('pause videorecorder success');
  } else {
    console.error('pause videorecorder failed and error is ' + err.message);
  }
2954
});
Z
zengyawen 已提交
2955
```
2956

2957
### pause<sup>9+</sup><a name=videorecorder_pause2></a>
2958

2959
pause(): Promise\<void>;
Z
zengyawen 已提交
2960

2961
异步方式暂停视频录制。通过Promise获取返回值。
2962

2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983
[start()](#videorecorder_start1)后调用。可以通过调用[resume()](#videorecorder_resume1)接口来恢复录制。

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

**系统接口:** 该接口为系统接口

**返回值:**

| 类型           | 说明                                  |
| -------------- | ------------------------------------- |
| Promise\<void> | 异步暂停视频录制方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |
| 5400103  | I/O error. Return by promise.             |
| 5400105  | Service died. Return by promise.          |
2984 2985 2986 2987

**示例:**

```js
2988 2989
// promise
videoRecorder.pause().then(() => {
2990
  console.info('pause videorecorder success');
2991
}).catch((err) => {
2992
  console.error('pause videorecorder failed and catch error is ' + err.message);
2993
});
Z
zengyawen 已提交
2994 2995
```

2996
### resume<sup>9+</sup><a name=videorecorder_resume1></a>
Z
zengyawen 已提交
2997

2998
resume(callback: AsyncCallback\<void>): void;
Z
zengyawen 已提交
2999

3000
异步方式恢复视频录制。通过注册回调函数获取返回值。
3001

3002 3003 3004
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

**系统接口:** 该接口为系统接口
Z
zengyawen 已提交
3005

W
wusongqing 已提交
3006
**参数:**
B
bird_j 已提交
3007

3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020
| 参数名   | 类型                 | 必填 | 说明                         |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步恢复视频录制的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |
| 5400103  | I/O error. Return by callback.             |
| 5400105  | Service died. Return by callback.          |
Z
zengyawen 已提交
3021

W
wusongqing 已提交
3022
**示例:**
Z
zengyawen 已提交
3023

3024
```js
3025 3026
// asyncallback
videoRecorder.resume((err) => {
3027 3028 3029 3030 3031
  if (err == null) {
    console.info('resume videorecorder success');
  } else {
    console.error('resume videorecorder failed and error is ' + err.message);
  }
Z
zengyawen 已提交
3032 3033 3034
});
```

3035
### resume<sup>9+</sup><a name=videorecorder_resume2></a>
Z
zengyawen 已提交
3036

3037
resume(): Promise\<void>;
B
bird_j 已提交
3038

3039
异步方式恢复视频录制。通过Promise获取返回值。
Z
zengyawen 已提交
3040

3041 3042 3043
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

**系统接口:** 该接口为系统接口
Z
zengyawen 已提交
3044

3045 3046
**返回值:**

3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059
| 类型           | 说明                                  |
| -------------- | ------------------------------------- |
| Promise\<void> | 异步恢复视频录制方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |
| 5400103  | I/O error. Return by promise.             |
| 5400105  | Service died. Return by promise.          |
3060

W
wusongqing 已提交
3061
**示例:**
3062 3063

```js
3064 3065
// promise
videoRecorder.resume().then(() => {
3066
  console.info('resume videorecorder success');
3067
}).catch((err) => {
3068
  console.error('resume videorecorder failed and catch error is ' + err.message);
3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104
});
```

### stop<sup>9+</sup><a name=videorecorder_stop1></a>

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

异步方式停止视频录制。通过注册回调函数获取返回值。

需要重新调用[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface9)接口才能重新录制。

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

**系统接口:** 该接口为系统接口

**参数:**

| 参数名   | 类型                 | 必填 | 说明                         |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步停止视频录制的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                   |
| -------- | ------------------------------------------ |
| 5400102  | Operation not allowed. Return by callback. |
| 5400103  | I/O error. Return by callback.             |
| 5400105  | Service died. Return by callback.          |

**示例:**

```js
// asyncallback
videoRecorder.stop((err) => {
3105 3106 3107 3108 3109
  if (err == null) {
    console.info('stop videorecorder success');
  } else {
    console.error('stop videorecorder failed and error is ' + err.message);
  }
3110
});
3111
```
B
bird_j 已提交
3112

3113
### stop<sup>9+</sup><a name=videorecorder_stop2></a>
3114

3115
stop(): Promise\<void>;
3116

3117
异步方式停止视频录制。通过Promise获取返回值。
3118

3119
需要重新调用[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface9)接口才能重新录制。
3120

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

3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139
**系统接口:** 该接口为系统接口

**返回值:**

| 类型           | 说明                                  |
| -------------- | ------------------------------------- |
| Promise\<void> | 异步停止视频录制方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                                  |
| -------- | ----------------------------------------- |
| 5400102  | Operation not allowed. Return by promise. |
| 5400103  | I/O error. Return by promise.             |
| 5400105  | Service died. Return by promise.          |
3140

W
wusongqing 已提交
3141
**示例:**
3142 3143

```js
3144 3145
// promise
videoRecorder.stop().then(() => {
3146
  console.info('stop videorecorder success');
3147
}).catch((err) => {
3148
  console.error('stop videorecorder failed and catch error is ' + err.message);
3149
});
3150 3151
```

3152
### release<sup>9+</sup><a name=videorecorder_release1></a>
3153

3154
release(callback: AsyncCallback\<void>): void;
B
bird_j 已提交
3155

3156
异步方式释放视频录制资源。通过注册回调函数获取返回值。
3157

3158 3159 3160
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder

**系统接口:** 该接口为系统接口
Z
zengyawen 已提交
3161

W
wusongqing 已提交
3162
**参数:**
3163

3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174
| 参数名   | 类型                 | 必填 | 说明                             |
| -------- | -------------------- | ---- | -------------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步释放视频录制资源的回调方法。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                          |
| -------- | --------------------------------- |
| 5400105  | Service died. Return by callback. |
3175

W
wusongqing 已提交
3176
**示例:**
3177 3178

```js
3179 3180
// asyncallback
videoRecorder.release((err) => {
3181 3182 3183 3184 3185
  if (err == null) {
    console.info('release videorecorder success');
  } else {
    console.error('release videorecorder failed and error is ' + err.message);
  }
3186 3187 3188
});
```

3189
### release<sup>9+</sup><a name=videorecorder_release2></a>
Z
zengyawen 已提交
3190

3191
release(): Promise\<void>;
B
bird_j 已提交
3192

3193
异步方式释放视频录制资源。通过Promise获取返回值。
3194

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

3197
**系统接口:** 该接口为系统接口
3198

3199
**返回值:**
3200

3201 3202 3203
| 类型           | 说明                                      |
| -------------- | ----------------------------------------- |
| Promise\<void> | 异步释放视频录制资源方法的Promise返回值。 |
3204

3205
**错误码:**
3206

3207
以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)
3208

3209 3210 3211
| 错误码ID | 错误信息                          |
| -------- | --------------------------------- |
| 5400105  | Service died. Return by callback. |
3212

W
wusongqing 已提交
3213
**示例:**
3214 3215

```js
3216 3217
// promise
videoRecorder.release().then(() => {
3218
  console.info('release videorecorder success');
3219
}).catch((err) => {
3220
  console.error('release videorecorder failed and catch error is ' + err.message);
3221
});
3222 3223
```

3224
### reset<sup>9+</sup><a name=videorecorder_reset1></a>
3225

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

3228
异步方式重置视频录制。通过注册回调函数获取返回值。
3229

3230
需要重新调用[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface9)接口才能重新录制。
3231

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

3234
**系统接口:** 该接口为系统接口
3235

3236
**参数:**
3237

3238 3239 3240
| 参数名   | 类型                 | 必填 | 说明                         |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\<void> | 是   | 异步重置视频录制的回调方法。 |
3241

3242
**错误码:**
3243

3244
以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)
3245

3246 3247 3248 3249
| 错误码ID | 错误信息                          |
| -------- | --------------------------------- |
| 5400103  | I/O error. Return by callback.    |
| 5400105  | Service died. Return by callback. |
3250

W
wusongqing 已提交
3251
**示例:**
3252 3253

```js
3254 3255
// asyncallback
videoRecorder.reset((err) => {
3256 3257 3258 3259 3260
  if (err == null) {
    console.info('reset videorecorder success');
  } else {
    console.error('reset videorecorder failed and error is ' + err.message);
  }
3261 3262 3263
});
```

3264
### reset<sup>9+</sup><a name=videorecorder_reset2></a>
3265

3266
reset(): Promise\<void>;
3267

3268
异步方式重置视频录制。通过Promise获取返回值。
Z
zengyawen 已提交
3269

3270
需要重新调用[prepare()](#videorecorder_prepare1)[getInputSurface()](#getinputsurface9)接口才能重新录制。
B
bird_j 已提交
3271

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

3274
**系统接口:** 该接口为系统接口
3275

3276
**返回值:**
3277

3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289
| 类型           | 说明                                  |
| -------------- | ------------------------------------- |
| Promise\<void> | 异步重置视频录制方法的Promise返回值。 |

**错误码:**

以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)

| 错误码ID | 错误信息                         |
| -------- | -------------------------------- |
| 5400103  | I/O error. Return by promise.    |
| 5400105  | Service died. Return by promise. |
3290

W
wusongqing 已提交
3291
**示例:**
3292 3293

```js
3294 3295
// promise
videoRecorder.reset().then(() => {
3296
  console.info('reset videorecorder success');
3297
}).catch((err) => {
3298
  console.error('reset videorecorder failed and catch error is ' + err.message);
3299
});
3300 3301
```

3302
### on('error')<sup>9+</sup>
3303

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

3306
开始订阅视频录制错误事件,当上报error错误事件后,用户需处理error事件,退出录制操作。
B
bird_j 已提交
3307

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

W
wusongqing 已提交
3310
**参数:**
3311

3312 3313 3314 3315
| 参数名   | 类型          | 必填 | 说明                                                         |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type     | string        | 是   | 录制错误事件回调类型'error'。<br/>-&nbsp;'error':视频录制过程中发生错误,触发该事件。 |
| callback | ErrorCallback | 是   | 录制错误事件回调方法。                                       |
3316

3317
**错误码:**
3318

3319
以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)
3320

3321 3322 3323 3324
| 错误码ID | 错误信息                          |
| -------- | --------------------------------- |
| 5400103  | I/O error. Return by callback.    |
| 5400105  | Service died. Return by callback. |
3325

3326
**示例:**
3327

3328 3329 3330
```js
// 当获取videoRecordState接口出错时通过此订阅事件上报
videoRecorder.on('error', (error) => {                                  // 设置'error'事件回调
3331
  console.error(`audio error called, error: ${error}`); 
3332 3333
})
```
3334

3335
## VideoRecordState<sup>9+</sup>
Z
zengyawen 已提交
3336

3337
视频录制的状态机。可通过state属性获取当前状态。
B
bird_j 已提交
3338

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

3341
**系统接口:** 该接口为系统接口
3342

3343 3344 3345 3346 3347 3348 3349 3350
| 名称     | 类型   | 说明                   |
| -------- | ------ | ---------------------- |
| idle     | string | 视频录制空闲。         |
| prepared | string | 视频录制参数设置完成。 |
| playing  | string | 视频正在录制。         |
| paused   | string | 视频暂停录制。         |
| stopped  | string | 视频录制停止。         |
| error    | string | 错误状态。             |
3351

3352
## VideoRecorderConfig<sup>9+</sup>
3353

3354
表示视频录制的参数设置。
3355

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

3358
**系统接口:** 该接口为系统接口
Z
zengyawen 已提交
3359

3360 3361 3362 3363 3364
| 名称            | 类型                                           | 必填 | 说明                                                         |
| --------------- | ---------------------------------------------- | ---- | ------------------------------------------------------------ |
| audioSourceType | [AudioSourceType](#audiosourcetype9)           | 是   | 视频录制的音频源类型。                                       |
| videoSourceType | [VideoSourceType](#videosourcetype9)           | 是   | 视频录制的视频源类型。                                       |
| profile         | [VideoRecorderProfile](#videorecorderprofile9) | 是   | 视频录制的profile。                                          |
3365 3366 3367
| rotation        | number                                         | 否   | 录制的视频旋转角度,仅支持0,90,180,270,默认值为0。       |
| location        | [Location](#location)                          | 否   | 录制视频的地理位置,默认不记录地理位置信息。                 |
| url             | string                                         | 是   | 视频输出URL:fd://xx&nbsp;(fd&nbsp;number)<br/>![](figures/zh-cn_image_url.png) |
3368

3369
## VideoRecorderProfile<sup>9+</sup>
3370

3371
视频录制的配置文件。
3372

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

3375
**系统接口:** 该接口为系统接口
Z
zengyawen 已提交
3376

3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388
| 名称             | 类型                                         | 必填 | 说明             |
| ---------------- | -------------------------------------------- | ---- | ---------------- |
| audioBitrate     | number                                       | 是   | 音频编码比特率。 |
| audioChannels    | number                                       | 是   | 音频采集声道数。 |
| audioCodec       | [CodecMimeType](#codecmimetype8)             | 是   | 音频编码格式。   |
| audioSampleRate  | number                                       | 是   | 音频采样率。     |
| fileFormat       | [ContainerFormatType](#containerformattype8) | 是   | 文件的容器格式。 |
| videoBitrate     | number                                       | 是   | 视频编码比特率。 |
| videoCodec       | [CodecMimeType](#codecmimetype8)             | 是   | 视频编码格式。   |
| videoFrameWidth  | number                                       | 是   | 录制视频帧的宽。 |
| videoFrameHeight | number                                       | 是   | 录制视频帧的高。 |
| videoFrameRate   | number                                       | 是   | 录制视频帧率。   |
Z
zengyawen 已提交
3389

3390
## media.createAudioPlayer<sup>(deprecated)</sup><a name=createaudioplayer></a>
Z
zengyawen 已提交
3391

3392 3393 3394 3395 3396 3397 3398 3399
createAudioPlayer(): AudioPlayer

同步方式创建音频播放实例。

> **说明:**
> 从API version 6开始支持,从API version 9开始废弃,建议使用[createAVPlayer](#mediacreateavplayer9)替代。

**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
Z
zengyawen 已提交
3400 3401 3402

**返回值:**

3403 3404 3405
| 类型                        | 说明                                                         |
| --------------------------- | ------------------------------------------------------------ |
| [AudioPlayer](#audioplayerdeprecated) | 返回AudioPlayer类实例,失败时返回null。可用于音频播放、暂停、停止等操作。 |
Z
zengyawen 已提交
3406 3407 3408 3409

**示例:**

```js
3410
let audioPlayer = media.createAudioPlayer();
Z
zengyawen 已提交
3411 3412
```

3413
## media.createVideoPlayer<sup>(deprecated)</sup><a name=createvideoplayer></a>
Z
zengyawen 已提交
3414

3415
createVideoPlayer(callback: AsyncCallback\<VideoPlayer>): void
Z
zengyawen 已提交
3416

3417 3418 3419 3420
异步方式创建视频播放实例,通过注册回调函数获取返回值。

> **说明:**
> 从API version 8开始支持,从API version 9开始废弃,建议使用[createAVPlayer](#mediacreateavplayer9)替代。
Z
zengyawen 已提交
3421 3422 3423 3424 3425

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

**参数:**

3426 3427 3428
| 参数名   | 类型                                       | 必填 | 说明                                                         |
| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<[VideoPlayer](#videoplayerdeprecated)> | 是   | 回调函数。异步返回VideoPlayer实例,失败时返回null。可用于管理和播放视频媒体。 |
Z
zengyawen 已提交
3429 3430 3431 3432

**示例:**

```js
3433
let videoPlayer;
3434 3435

media.createVideoPlayer((error, video) => {
3436 3437 3438 3439 3440 3441
  if (video != null) {
    videoPlayer = video;
    console.info('video createVideoPlayer success');
  } else {
    console.error(`video createVideoPlayer fail, error:${error}`);
  }
Z
zengyawen 已提交
3442 3443 3444
});
```

3445
## media.createVideoPlayer<sup>(deprecated)</sup>
Z
zengyawen 已提交
3446

3447
createVideoPlayer(): Promise\<VideoPlayer>
Z
zengyawen 已提交
3448

3449 3450 3451 3452
异步方式创建视频播放实例,通过Promise获取返回值。

> **说明:**
> 从API version 8开始支持,从API version 9开始废弃,建议使用[createAVPlayer](#mediacreateavplayer9-1)替代。
Z
zengyawen 已提交
3453 3454 3455 3456 3457

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

**返回值:**

3458 3459 3460
| 类型                                 | 说明                                                         |
| ------------------------------------ | ------------------------------------------------------------ |
| Promise<[VideoPlayer](#videoplayerdeprecated)> | Promise对象。异步返回VideoPlayer实例,失败时返回null。可用于管理和播放视频媒体。 |
Z
zengyawen 已提交
3461 3462 3463 3464

**示例:**

```js
3465
let videoPlayer;
3466 3467

media.createVideoPlayer().then((video) => {
3468 3469 3470 3471 3472 3473
  if (video != null) {
    videoPlayer = video;
    console.info('video createVideoPlayer success');
  } else {
    console.error('video createVideoPlayer fail');
  }
Z
zengyawen 已提交
3474
}).catch((error) => {
3475
  console.error(`video catchCallback, error:${error}`);
Z
zengyawen 已提交
3476 3477 3478
});
```

3479
## media.createAudioRecorder<sup>(deprecated)</sup><a name=createaudiorecorder></a>
Z
zengyawen 已提交
3480

3481
createAudioRecorder(): AudioRecorder
Z
zengyawen 已提交
3482

3483 3484
创建音频录制的实例来控制音频的录制。
一台设备只允许创建一个录制实例。
Z
zengyawen 已提交
3485

3486 3487
> **说明:**
> 从API version 8开始支持,从API version 9开始废弃,建议使用[createAVRecorder](#mediacreateavrecorder9)替代。
Z
zengyawen 已提交
3488

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

3491 3492 3493 3494 3495
**返回值:**

| 类型                            | 说明                                                         |
| ------------------------------- | ------------------------------------------------------------ |
| [AudioRecorder](#audiorecorderdeprecated) | 返回AudioRecorder类实例,失败时返回null。可用于录制音频媒体。 |
Z
zengyawen 已提交
3496 3497 3498 3499

**示例:**

```js
3500
let audioRecorder = media.createAudioRecorder();
Z
zengyawen 已提交
3501 3502
```

3503
## MediaErrorCode<sup>(deprecated)</sup><a name=mediaerrorcode></a>
3504

3505
媒体服务错误类型枚举。
3506

3507 3508
> **说明:**
> 从API version 8开始支持,从API version 9开始废弃,建议使用[媒体错误码](../errorcodes/errorcode-media.md)替代。
B
bird_j 已提交
3509

3510
**系统能力:** SystemCapability.Multimedia.Media.Core
Z
zengyawen 已提交
3511

3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523
| 名称                       | 值   | 说明                                   |
| -------------------------- | ---- | -------------------------------------- |
| 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    | 表示在当前版本下,不支持此操作。       |
3524

3525
## AudioPlayer<sup>(deprecated)</sup>
3526

3527 3528
> **说明:**
> 从API version 6开始支持,从API version 9开始废弃,建议使用[AVPlayer](#avplayer9)替代。
3529

3530
音频播放管理类,用于管理和播放音频媒体。在调用AudioPlayer的方法前,需要先通过[createAudioPlayer()](#mediacreateaudioplayerdeprecated)构建一个AudioPlayer实例。
3531

3532
### 属性<a name=audioplayer_属性></a>
3533

3534
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
3535

3536 3537 3538 3539 3540 3541 3542 3543 3544
| 名称                            | 类型                                                   | 可读 | 可写 | 说明                                                         |
| ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ |
| src                             | string                                                 | 是   | 是   | 音频媒体URI,支持当前主流的音频格式(m4a、aac、mp3、ogg、wav)。<br>**支持路径示例**<br>1. fd类型播放:fd://xx<br>![](figures/zh-cn_image_url.png)<br>2. http网络播放: http://xx<br/>3. https网络播放: https://xx<br/>4. hls网络播放路径:http://xx或者https://xx<br/>**需要权限:** ohos.permission.READ_MEDIA 或 ohos.permission.INTERNET。 |
| fdSrc<sup>9+</sup>              | [AVFileDescriptor](#avfiledescriptor9)                 | 是   | 是   | 音频媒体文件描述,使用场景:应用中的音频资源被连续存储在同一个文件中。<br/>**使用示例**<br/>假设一个连续存储的音乐文件: <br/>音乐1(地址偏移:0,字节长度:100)<br/>音乐2(地址偏移:101,字节长度:50)<br/>音乐3(地址偏移:151,字节长度:150)<br/>1. 播放音乐1:AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }<br/>2. 播放音乐2:AVFileDescriptor { fd = 资源句柄; offset = 101; length = 50; }<br/>3. 播放音乐3:AVFileDescriptor { fd = 资源句柄; offset = 151; length = 150; }<br/>假设是一个独立的音乐文件: 请使用src=fd://xx <br/> |
| loop                            | boolean                                                | 是   | 是   | 音频循环播放属性,设置为'true'表示循环播放。                 |
| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](js-apis-audio.md#interruptmode9) | 是   | 是   | 音频焦点模型。                                               |
| currentTime                     | number                                                 | 是   | 否   | 音频的当前播放位置,单位为毫秒(ms)。                       |
| duration                        | number                                                 | 是   | 否   | 音频时长,单位为毫秒(ms)。                                 |
| state                           | [AudioState](#audiostate)                              | 是   | 否   | 可以查询音频播放的状态,该状态不可作为调用play/pause/stop等状态切换的触发条件。 |
Z
zengyawen 已提交
3545

3546
### play<a name=audioplayer_play></a>
B
bird_j 已提交
3547

3548
play(): void
3549

3550 3551 3552
开始播放音频资源,需在[dataLoad](#audioplayer_on)事件成功触发后,才能调用。

**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
3553

W
wusongqing 已提交
3554
**示例:**
3555 3556

```js
3557
audioPlayer.on('play', () => {    //设置'play'事件回调
3558
  console.log('audio play success');
3559
});
3560
audioPlayer.play();
3561 3562
```

3563
### pause<a name=audioplayer_pause></a>
B
bird_j 已提交
3564

3565
pause(): void
3566

3567
暂停播放音频资源。
3568

3569
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
3570

W
wusongqing 已提交
3571
**示例:**
3572 3573

```js
3574
audioPlayer.on('pause', () => {    //设置'pause'事件回调
3575
  console.log('audio pause success');
3576
});
3577
audioPlayer.pause();
3578 3579
```

3580
### stop<a name=audioplayer_stop></a>
3581

3582
stop(): void
3583

3584
停止播放音频资源。
3585

3586
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
3587

W
wusongqing 已提交
3588
**示例:**
3589 3590

```js
3591
audioPlayer.on('stop', () => {    //设置'stop'事件回调
3592
  console.log('audio stop success');
3593
});
3594
audioPlayer.stop();
3595 3596
```

3597
### reset<sup>7+</sup><a name=audioplayer_reset></a>
B
bird_j 已提交
3598

3599
reset(): void
3600

3601
重置播放音频资源。
3602

3603
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
3604

W
wusongqing 已提交
3605
**示例:**
3606 3607

```js
3608
audioPlayer.on('reset', () => {    //设置'reset'事件回调
3609
  console.log('audio reset success');
3610
});
3611
audioPlayer.reset();
3612 3613
```

3614
### seek<a name=audioplayer_seek></a>
3615

3616
seek(timeMs: number): void
3617

3618
跳转到指定播放位置。
3619

3620
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
3621 3622 3623

**参数:**

3624 3625 3626
| 参数名 | 类型   | 必填 | 说明                                                        |
| ------ | ------ | ---- | ----------------------------------------------------------- |
| timeMs | number | 是   | 指定的跳转时间节点,单位毫秒(ms),取值范围[0, duration]。 |
3627 3628 3629 3630

**示例:**

```js
3631
audioPlayer.on('timeUpdate', (seekDoneTime) => {    //设置'timeUpdate'事件回调
3632 3633 3634 3635 3636
  if (seekDoneTime == null) {
    console.info('audio seek fail');
    return;
  }
  console.log('audio seek success. seekDoneTime: ' + seekDoneTime);
3637
});
3638
audioPlayer.seek(30000);    //seek到30000ms的位置
3639 3640
```

3641
### setVolume<a name=audioplayer_setvolume></a>
3642

3643
setVolume(vol: number): void
3644

3645
设置音量。
B
bird_j 已提交
3646

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

W
wusongqing 已提交
3649
**参数:**
B
bird_j 已提交
3650

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

W
wusongqing 已提交
3655
**示例:**
3656 3657

```js
3658
audioPlayer.on('volumeChange', () => {    //设置'volumeChange'事件回调
3659
  console.log('audio volumeChange success');
3660
});
3661
audioPlayer.setVolume(1);    //设置音量到100%
3662 3663
```

3664
### release<a name=audioplayer_release></a>
3665

3666
release(): void
3667

3668
释放音频资源。
3669

3670
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
3671 3672 3673 3674

**示例:**

```js
3675 3676
audioPlayer.release();
audioPlayer = undefined;
3677 3678
```

3679
### getTrackDescription<sup>8+</sup><a name=audioplayer_gettrackdescription1></a>
3680

3681
getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void
3682

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

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

W
wusongqing 已提交
3687
**参数:**
B
bird_j 已提交
3688

3689 3690
| 参数名   | 类型                                                         | 必填 | 说明                                       |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
3691
| callback | AsyncCallback\<Array\<[MediaDescription](#mediadescription8)>> | 是   | 音频轨道信息MediaDescription数组回调方法。 |
3692

W
wusongqing 已提交
3693
**示例:**
3694 3695 3696

```js
function printfDescription(obj) {
3697 3698 3699 3700 3701
  for (let item in obj) {
    let property = obj[item];
    console.info('audio key is ' + item);
    console.info('audio value is ' + property);
  }
3702 3703
}

3704
audioPlayer.getTrackDescription((error, arrList) => {
3705 3706 3707
  if (arrList != null) {
    for (let i = 0; i < arrList.length; i++) {
      printfDescription(arrList[i]);
3708
    }
3709 3710 3711
  } else {
    console.log(`audio getTrackDescription fail, error:${error}`);
  }
3712 3713 3714
});
```

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

3717
getTrackDescription(): Promise\<Array\<MediaDescription>>
3718

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

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

W
wusongqing 已提交
3723
**返回值:**
3724

3725 3726
| 类型                                                   | 说明                                            |
| ------------------------------------------------------ | ----------------------------------------------- |
3727
| Promise<Array<[MediaDescription](#mediadescription8)>> | 音频轨道信息MediaDescription数组Promise返回值。 |
3728

W
wusongqing 已提交
3729
**示例:**
3730 3731 3732

```js
function printfDescription(obj) {
3733 3734 3735 3736 3737
  for (let item in obj) {
    let property = obj[item];
    console.info('audio key is ' + item);
    console.info('audio value is ' + property);
  }
3738
}
3739 3740
let arrayDescription = null
audioPlayer.getTrackDescription().then((arrList) => {
3741 3742 3743 3744 3745
  if (arrList != null) {
    arrayDescription = arrList;
  } else {
    console.log('audio getTrackDescription fail');
  }
3746
}).catch((error) => {
3747
  console.info(`audio catchCallback, error:${error}`);
3748
});
3749

3750
for (let i = 0; i < arrayDescription.length; i++) {
3751
  printfDescription(arrayDescription[i]);
3752 3753 3754
}
```

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

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

3759
开始订阅音频缓存更新事件。仅网络播放支持该订阅事件。
3760

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

W
wusongqing 已提交
3763
**参数:**
B
bird_j 已提交
3764

3765 3766 3767 3768
| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 音频缓存事件回调类型,支持的事件:'bufferingUpdate'。        |
| callback | function | 是   | 音频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时,value值有效,否则固定为0。 |
3769

W
wusongqing 已提交
3770
**示例:**
3771 3772

```js
3773
audioPlayer.on('bufferingUpdate', (infoType, value) => {
3774 3775
  console.log('audio bufferingInfo type: ' + infoType);
  console.log('audio bufferingInfo value: ' + value);
3776 3777 3778
});
```

3779
 ### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')<a name = audioplayer_on></a>
3780

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

3783
开始订阅音频播放事件。
B
bird_j 已提交
3784

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

W
wusongqing 已提交
3787
**参数:**
3788

3789 3790 3791 3792
| 参数名   | 类型       | 必填 | 说明                                                         |
| -------- | ---------- | ---- | ------------------------------------------------------------ |
| 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)调用,播放音量改变后触发该事件。 |
| callback | () => void | 是   | 播放事件回调方法。                                           |
Z
zengyawen 已提交
3793

W
wusongqing 已提交
3794
**示例:**
3795 3796

```js
3797
import fs from '@ohos.file.fs';
3798

3799 3800
let audioPlayer = media.createAudioPlayer();  //创建一个音频播放实例
audioPlayer.on('dataLoad', () => {            //设置'dataLoad'事件回调,src属性设置成功后,触发此回调
3801 3802
  console.info('audio set source success');
  audioPlayer.play();                       //开始播放,并触发'play'事件回调
3803 3804
});
audioPlayer.on('play', () => {                //设置'play'事件回调
3805 3806
  console.info('audio play success');
  audioPlayer.seek(30000);                  //调用seek方法,并触发'timeUpdate'事件回调
3807 3808
});
audioPlayer.on('pause', () => {               //设置'pause'事件回调
3809 3810
  console.info('audio pause success');
  audioPlayer.stop();                       //停止播放,并触发'stop'事件回调
3811 3812
});
audioPlayer.on('reset', () => {               //设置'reset'事件回调
3813 3814 3815
  console.info('audio reset success');
  audioPlayer.release();                    //释放播放实例资源
  audioPlayer = undefined;
3816 3817
});
audioPlayer.on('timeUpdate', (seekDoneTime) => {  //设置'timeUpdate'事件回调
3818 3819 3820 3821 3822 3823
  if (seekDoneTime == null) {
    console.info('audio seek fail');
    return;
  }
  console.info('audio seek success, and seek time is ' + seekDoneTime);
  audioPlayer.setVolume(0.5);                //设置音量为50%,并触发'volumeChange'事件回调
3824 3825
});
audioPlayer.on('volumeChange', () => {         //设置'volumeChange'事件回调
3826 3827
  console.info('audio volumeChange success');
  audioPlayer.pause();                       //暂停播放,并触发'pause'事件回调
3828 3829
});
audioPlayer.on('finish', () => {               //设置'finish'事件回调
3830 3831
  console.info('audio play finish');
  audioPlayer.stop();                        //停止播放,并触发'stop'事件回调
3832 3833
});
audioPlayer.on('error', (error) => {           //设置'error'事件回调
3834
  console.error(`audio error called, error: ${error}`);
3835 3836
});

3837
// 用户选择音频设置fd(本地播放)
3838 3839 3840
let fdPath = 'fd://';
// 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';
3841
fs.open(path).then((file) => {
3842 3843 3844
  fdPath = fdPath + '' + file.fd;
  console.info('open fd success fd is' + fdPath);
  audioPlayer.src = fdPath;  //设置src属性,并触发'dataLoad'事件回调
3845
}, (err) => {
3846
  console.info('open fd failed err is' + err);
3847
}).catch((err) => {
3848
  console.info('open fd failed err is' + err);
3849
});
3850 3851
```

3852
### on('timeUpdate')
3853

3854
on(type: 'timeUpdate', callback: Callback\<number>): void
3855

3856
开始订阅音频播放时间更新事件。处于播放状态时,每隔1s上报一次该事件。
3857

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

W
wusongqing 已提交
3860
**参数:**
B
bird_j 已提交
3861

3862 3863 3864 3865
| 参数名   | 类型              | 必填 | 说明                                                         |
| -------- | ----------------- | ---- | ------------------------------------------------------------ |
| type     | string            | 是   | 播放事件回调类型,支持的事件包括:'timeUpdate'。<br>- 'timeUpdate':音频播放时间戳更新,开始播放后自动触发该事件。 |
| callback | Callback\<number> | 是   | 播放事件回调方法。回调方法入参为更新后的时间戳。             |
3866

W
wusongqing 已提交
3867
**示例:**
3868 3869

```js
3870
audioPlayer.on('timeUpdate', (newTime) => {    //设置'timeUpdate'事件回调
3871 3872 3873 3874 3875
  if (newTime == null) {
    console.info('audio timeUpadate fail');
    return;
  }
  console.log('audio timeUpadate success. seekDoneTime: ' + newTime);
3876
});
3877
audioPlayer.play();    //开始播放后,自动触发时间戳更新事件
3878
```
3879

3880
### on('error')
3881

3882
on(type: 'error', callback: ErrorCallback): void
B
bird_j 已提交
3883

3884
开始订阅音频播放错误事件,当上报error错误事件后,用户需处理error事件,退出播放操作。
3885

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

W
wusongqing 已提交
3888
**参数:**
3889

3890 3891 3892 3893
| 参数名   | 类型          | 必填 | 说明                                                         |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type     | string        | 是   | 播放错误事件回调类型,支持的事件包括:'error'。<br>- 'error':音频播放中发生错误,触发该事件。 |
| callback | ErrorCallback | 是   | 播放错误事件回调方法。                                       |
3894

W
wusongqing 已提交
3895
**示例:**
3896 3897

```js
3898
audioPlayer.on('error', (error) => {      //设置'error'事件回调
3899
  console.error(`audio error called, error: ${error}`); 
3900
});
3901
audioPlayer.setVolume(3);  //设置volume为无效值,触发'error'事件
3902 3903
```

3904
## AudioState<sup>(deprecated)</sup>
3905

3906
音频播放的状态机。可通过state属性获取当前状态。
3907

3908 3909
> **说明:**
> 从API version 6开始支持,从API version 9开始废弃,建议使用[AVPlayerState](#avplayerstate9)替代。
B
bird_j 已提交
3910

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

3913 3914 3915 3916 3917 3918 3919
| 名称    | 类型   | 说明                                           |
| ------- | ------ | ---------------------------------------------- |
| idle    | string | 音频播放空闲,dataload/reset成功后处于此状态。 |
| playing | string | 音频正在播放,play成功后处于此状态。           |
| paused  | string | 音频暂停播放,pause成功后处于此状态。          |
| stopped | string | 音频播放停止,stop/播放结束后处于此状态。      |
| error   | string | 错误状态。                                     |
3920

3921
## VideoPlayer<sup>(deprecated)</sup><a name=videoplayer></a>
3922

3923 3924
> **说明:**
> 从API version 8开始支持,从API version 9开始废弃,建议使用[AVPlayer](#avplayer9)替代。
3925

3926
视频播放管理类,用于管理和播放视频媒体。在调用VideoPlayer的方法前,需要先通过[createVideoPlayer()](#createvideoplayer)构建一个VideoPlayer实例。
3927

3928
### 属性<a name=videoplayer_属性></a>
3929

3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

| 名称                            | 类型                                                   | 可读 | 可写 | 说明                                                         |
| ------------------------------- | ------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ |
| 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. https网络播放: https://xx<br/>4. hls网络播放路径:http://xx或者https://xx<br/> |
| fdSrc<sup>9+</sup>              | [AVFileDescriptor](#avfiledescriptor9)                 | 是   | 是   | 视频媒体文件描述,使用场景:应用中的视频资源被连续存储在同一个文件中。<br/>**使用示例**<br/>假设一个连续存储的音乐文件: <br/>视频1(地址偏移:0,字节长度:100)<br/>视频2(地址偏移:101,字节长度:50)<br/>视频3(地址偏移:151,字节长度:150)<br/>1. 播放视频1:AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }<br/>2. 播放视频2:AVFileDescriptor { fd = 资源句柄; offset = 101; length = 50; }<br/>3. 播放视频3:AVFileDescriptor { fd = 资源句柄; offset = 151; length = 150; }<br/>假设是一个独立的视频文件: 请使用src=fd://xx <br/> |
| loop<sup>8+</sup>               | boolean                                                | 是   | 是   | 视频循环播放属性,设置为'true'表示循环播放。                 |
| videoScaleType<sup>9+</sup>     | [VideoScaleType](#videoscaletype9)                     | 是   | 是   | 视频缩放模式。                                               |
| audioInterruptMode<sup>9+</sup> | [audio.InterruptMode](js-apis-audio.md#interruptmode9) | 是   | 是   | 音频焦点模型。                                               |
| currentTime<sup>8+</sup>        | number                                                 | 是   | 否   | 视频的当前播放位置,单位为毫秒(ms)。                       |
| duration<sup>8+</sup>           | number                                                 | 是   | 否   | 视频时长,单位为毫秒(ms),返回-1表示直播模式。             |
| state<sup>8+</sup>              | [VideoPlayState](#videoplayerstate)                    | 是   | 否   | 视频播放的状态。                                             |
| width<sup>8+</sup>              | number                                                 | 是   | 否   | 视频宽,单位为像素(px)。                                   |
| height<sup>8+</sup>             | number                                                 | 是   | 否   | 视频高,单位为像素(px)。                                   |

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

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

通过回调方式设置SurfaceId。

*注意:SetDisplaySurface需要在设置url和Prepare之间,无音频的视频流必须设置Surface否则Prepare失败。
B
bird_j 已提交
3952

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

W
wusongqing 已提交
3955
**参数:**
3956

3957 3958 3959 3960
| 参数名    | 类型                 | 必填 | 说明                      |
| --------- | -------------------- | ---- | ------------------------- |
| surfaceId | string               | 是   | SurfaceId                 |
| callback  | AsyncCallback\<void> | 是   | 设置SurfaceId的回调方法。 |
3961

W
wusongqing 已提交
3962
**示例:**
3963 3964

```js
3965 3966
let surfaceId = null;
videoPlayer.setDisplaySurface(surfaceId, (err) => {
3967 3968 3969 3970 3971
  if (err == null) {
    console.info('setDisplaySurface success!');
  } else {
    console.error('setDisplaySurface fail!');
  }
3972 3973 3974
});
```

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

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

3979 3980 3981
通过Promise方式设置SurfaceId。

*注意:SetDisplaySurface需要在设置url和Prepare之间,无音频的视频流必须设置Surface否则Prepare失败。
3982 3983 3984 3985 3986

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

**参数:**

3987 3988 3989 3990 3991 3992 3993 3994 3995
| 参数名    | 类型   | 必填 | 说明      |
| --------- | ------ | ---- | --------- |
| surfaceId | string | 是   | SurfaceId |

**返回值:**

| 类型           | 说明                           |
| -------------- | ------------------------------ |
| Promise\<void> | 设置SurfaceId的Promise返回值。 |
3996 3997 3998 3999

**示例:**

```js
4000 4001
let surfaceId = null;
videoPlayer.setDisplaySurface(surfaceId).then(() => {
4002
  console.info('setDisplaySurface success');
4003
}).catch((error) => {
4004
  console.error(`video catchCallback, error:${error}`);
4005 4006 4007
});
```

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

4010
prepare(callback: AsyncCallback\<void>): void
Z
zengyawen 已提交
4011

4012
通过回调方式准备播放视频。
4013

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

4016
**参数:**
4017

4018 4019 4020
| 参数名   | 类型                 | 必填 | 说明                     |
| -------- | -------------------- | ---- | ------------------------ |
| callback | AsyncCallback\<void> | 是   | 准备播放视频的回调方法。 |
Z
zengyawen 已提交
4021

4022
**示例:**
Z
zengyawen 已提交
4023

4024 4025
```js
videoPlayer.prepare((err) => {
4026 4027 4028 4029 4030
  if (err == null) {
    console.info('prepare success!');
  } else {
    console.error('prepare fail!');
  }
4031 4032
});
```
Z
zengyawen 已提交
4033

4034
### prepare<sup>8+</sup>
Z
zengyawen 已提交
4035

4036
prepare(): Promise\<void>
4037

4038
通过Promise方式准备播放视频。
4039

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

4042
**返回值:**
B
bird_j 已提交
4043

4044 4045 4046
| 类型           | 说明                          |
| -------------- | ----------------------------- |
| Promise\<void> | 准备播放视频的Promise返回值。 |
Z
zengyawen 已提交
4047

W
wusongqing 已提交
4048
**示例:**
Z
zengyawen 已提交
4049

4050
```js
4051
videoPlayer.prepare().then(() => {
4052
  console.info('prepare success');
4053
}).catch((error) => {
4054
  console.error(`video catchCallback, error:${error}`);
4055
});
Z
zengyawen 已提交
4056 4057
```

4058
### play<sup>8+</sup>
Z
zengyawen 已提交
4059

4060
play(callback: AsyncCallback\<void>): void;
Z
zengyawen 已提交
4061

4062
通过回调方式开始播放视频。
B
bird_j 已提交
4063

4064
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4065

4066 4067 4068 4069 4070
**参数:**

| 参数名   | 类型                 | 必填 | 说明                     |
| -------- | -------------------- | ---- | ------------------------ |
| callback | AsyncCallback\<void> | 是   | 开始播放视频的回调方法。 |
Z
zengyawen 已提交
4071

W
wusongqing 已提交
4072
**示例:**
Z
zengyawen 已提交
4073

4074
```js
4075
videoPlayer.play((err) => {
4076 4077 4078 4079 4080
  if (err == null) {
    console.info('play success!');
  } else {
    console.error('play fail!');
  }
4081
});
Z
zengyawen 已提交
4082
```
4083

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

4086
play(): Promise\<void>;
4087

4088
通过Promise方式开始播放视频。
4089

4090 4091 4092 4093 4094 4095 4096
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

**返回值:**

| 类型           | 说明                          |
| -------------- | ----------------------------- |
| Promise\<void> | 开始播放视频的Promise返回值。 |
Z
zengyawen 已提交
4097

W
wusongqing 已提交
4098
**示例:**
4099 4100

```js
4101
videoPlayer.play().then(() => {
4102
  console.info('play success');
4103
}).catch((error) => {
4104
  console.error(`video catchCallback, error:${error}`);
4105
});
4106 4107
```

4108
### pause<sup>8+</sup>
B
bird_j 已提交
4109

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

4112
通过回调方式暂停播放视频。
4113

4114 4115 4116 4117 4118 4119 4120
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

**参数:**

| 参数名   | 类型                 | 必填 | 说明                     |
| -------- | -------------------- | ---- | ------------------------ |
| callback | AsyncCallback\<void> | 是   | 暂停播放视频的回调方法。 |
Z
zengyawen 已提交
4121

W
wusongqing 已提交
4122
**示例:**
4123 4124

```js
4125
videoPlayer.pause((err) => {
4126 4127 4128 4129 4130
  if (err == null) {
    console.info('pause success!');
  } else {
    console.info('pause fail!');
  }
4131
});
Z
zengyawen 已提交
4132 4133
```

4134
### pause<sup>8+</sup>
Z
zengyawen 已提交
4135

4136
pause(): Promise\<void>
4137

4138
通过Promise方式暂停播放视频。
4139

4140 4141 4142 4143 4144 4145 4146
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

**返回值:**

| 类型           | 说明                          |
| -------------- | ----------------------------- |
| Promise\<void> | 暂停播放视频的Promise返回值。 |
Z
zengyawen 已提交
4147

W
wusongqing 已提交
4148
**示例:**
Z
zengyawen 已提交
4149

4150
```js
4151
videoPlayer.pause().then(() => {
4152
  console.info('pause success');
4153
}).catch((error) => {
4154
  console.error(`video catchCallback, error:${error}`);
4155
});
Z
zengyawen 已提交
4156 4157
```

4158
### stop<sup>8+</sup>
B
bird_j 已提交
4159

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

4162
通过回调方式停止播放视频。
4163

4164 4165 4166 4167 4168 4169 4170
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer

**参数:**

| 参数名   | 类型                 | 必填 | 说明                     |
| -------- | -------------------- | ---- | ------------------------ |
| callback | AsyncCallback\<void> | 是   | 停止播放视频的回调方法。 |
Z
zengyawen 已提交
4171

W
wusongqing 已提交
4172
**示例:**
Z
zengyawen 已提交
4173

4174
```js
4175
videoPlayer.stop((err) => {
4176 4177 4178 4179 4180
  if (err == null) {
    console.info('stop success!');
  } else {
    console.error('stop fail!');
  }
B
bird_j 已提交
4181
});
Z
zengyawen 已提交
4182 4183
```

4184
### stop<sup>8+</sup>
Z
zengyawen 已提交
4185

4186
stop(): Promise\<void>
Z
zengyawen 已提交
4187

4188
通过Promise方式停止播放视频。
B
bird_j 已提交
4189

4190
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4191

4192 4193 4194 4195 4196
**返回值:**

| 类型           | 说明                          |
| -------------- | ----------------------------- |
| Promise\<void> | 停止播放视频的Promise返回值。 |
Z
zengyawen 已提交
4197

W
wusongqing 已提交
4198
**示例:**
Z
zengyawen 已提交
4199

B
bird_j 已提交
4200
```js
4201
videoPlayer.stop().then(() => {
4202
  console.info('stop success');
4203
}).catch((error) => {
4204
  console.error(`video catchCallback, error:${error}`);
B
bird_j 已提交
4205
});
Z
zengyawen 已提交
4206 4207
```

4208
### reset<sup>8+</sup>
Z
zengyawen 已提交
4209

4210
reset(callback: AsyncCallback\<void>): void
Z
zengyawen 已提交
4211

4212
通过回调方式重置播放视频。
Z
zengyawen 已提交
4213

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

4216
**参数:**
B
bird_j 已提交
4217

4218 4219 4220
| 参数名   | 类型                 | 必填 | 说明                     |
| -------- | -------------------- | ---- | ------------------------ |
| callback | AsyncCallback\<void> | 是   | 切换播放视频的回调方法。 |
Z
zengyawen 已提交
4221

W
wusongqing 已提交
4222
**示例:**
Z
zengyawen 已提交
4223

4224
```js
4225
videoPlayer.reset((err) => {
4226 4227 4228 4229 4230
  if (err == null) {
    console.info('reset success!');
  } else {
    console.error('reset fail!');
  }
Z
zengyawen 已提交
4231 4232 4233
});
```

4234
### reset<sup>8+</sup>
Z
zengyawen 已提交
4235

4236
reset(): Promise\<void>
Z
zengyawen 已提交
4237

4238
通过Promise方式重置播放视频。
B
bird_j 已提交
4239

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

4242
**返回值:**
Z
zengyawen 已提交
4243

4244 4245 4246
| 类型           | 说明                          |
| -------------- | ----------------------------- |
| Promise\<void> | 切换播放视频的Promise返回值。 |
Z
zengyawen 已提交
4247

W
wusongqing 已提交
4248
**示例:**
4249 4250

```js
4251
videoPlayer.reset().then(() => {
4252
  console.info('reset success');
4253
}).catch((error) => {
4254
  console.error(`video catchCallback, error:${error}`);
4255 4256
});
```
Z
zengyawen 已提交
4257

4258
### seek<sup>8+</sup>
Z
zengyawen 已提交
4259

4260
seek(timeMs: number, callback: AsyncCallback\<number>): void
Z
zengyawen 已提交
4261

4262
通过回调方式跳转到指定播放位置,默认跳转到指定时间点的上一个关键帧。
Z
zengyawen 已提交
4263

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

4266
**参数:**
A
add dep  
abc12133 已提交
4267

4268 4269 4270 4271
| 参数名   | 类型                   | 必填 | 说明                                                         |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| timeMs   | number                 | 是   | 指定的跳转时间节点,单位毫秒(ms),取值范围为[0, duration]。 |
| callback | AsyncCallback\<number> | 是   | 跳转到指定播放位置的回调方法。                               |
Z
zengyawen 已提交
4272

4273
**示例:**
Z
zengyawen 已提交
4274

4275 4276 4277
```js
let seekTime = 5000;
videoPlayer.seek(seekTime, (err, result) => {
4278 4279 4280 4281 4282
  if (err == null) {
    console.info('seek success!');
  } else {
    console.error('seek fail!');
  }
4283 4284
});
```
4285

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

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

4290
通过回调方式跳转到指定播放位置。
4291

4292
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4293

4294
**参数:**
4295

4296 4297 4298 4299 4300
| 参数名   | 类型                   | 必填 | 说明                                                         |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| timeMs   | number                 | 是   | 指定的跳转时间节点,单位毫秒(ms),取值范围为[0, duration]。 |
| mode     | [SeekMode](#seekmode8) | 是   | 跳转模式。                                                   |
| callback | AsyncCallback\<number> | 是   | 跳转到指定播放位置的回调方法。                               |
Z
zengyawen 已提交
4301

4302
**示例:**
4303

4304 4305 4306 4307
```js
import media from '@ohos.multimedia.media'
let seekTime = 5000;
videoPlayer.seek(seekTime, media.SeekMode.SEEK_NEXT_SYNC, (err, result) => {
4308 4309 4310 4311 4312
  if (err == null) {
    console.info('seek success!');
  } else {
    console.error('seek fail!');
  }
4313 4314
});
```
4315

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

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

4320
通过Promise方式跳转到指定播放位置,如果没有设置mode则跳转到指定时间点的上一个关键帧。
4321

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

4324
**参数:**
Z
zengyawen 已提交
4325

4326 4327 4328
| 参数名 | 类型                   | 必填 | 说明                                                         |
| ------ | ---------------------- | ---- | ------------------------------------------------------------ |
| timeMs | number                 | 是   | 指定的跳转时间节点,单位毫秒(ms),取值范围为[0, duration]。 |
4329
| mode   | [SeekMode](#seekmode8) | 否   | 基于视频I帧的跳转模式,默认为SEEK_PREV_SYNC模式。            |
4330

4331
**返回值:**
4332

4333 4334 4335
| 类型             | 说明                                        |
| ---------------- | ------------------------------------------- |
| Promise\<number> | 跳转到指定播放位置的Promise返回值,单位ms。 |
4336

4337
**示例:**
4338

4339 4340 4341 4342
```js
import media from '@ohos.multimedia.media'
let seekTime = 5000;
videoPlayer.seek(seekTime).then((seekDoneTime) => { // seekDoneTime表示seek完成后的时间点
4343
  console.info('seek success');
4344
}).catch((error) => {
4345
  console.error(`video catchCallback, error:${error}`);
4346
});
4347

4348
videoPlayer.seek(seekTime, media.SeekMode.SEEK_NEXT_SYNC).then((seekDoneTime) => {
4349
  console.info('seek success');
4350
}).catch((error) => {
4351
  console.error(`video catchCallback, error:${error}`);
4352 4353
});
```
4354

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

4357
setVolume(vol: number, callback: AsyncCallback\<void>): void
B
bird_j 已提交
4358

4359
通过回调方式设置音量。
4360

4361
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4362

4363
**参数:**
4364

4365 4366 4367 4368
| 参数名   | 类型                 | 必填 | 说明                                                         |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| vol      | number               | 是   | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |
| callback | AsyncCallback\<void> | 是   | 设置音量的回调方法。                                         |
4369

W
wusongqing 已提交
4370
**示例:**
4371 4372

```js
4373 4374
let vol = 0.5;
videoPlayer.setVolume(vol, (err, result) => {
4375 4376 4377 4378 4379
  if (err == null) {
    console.info('setVolume success!');
  } else {
    console.error('setVolume fail!');
  }
4380
});
4381 4382
```

4383
### setVolume<sup>8+</sup>
Z
zengyawen 已提交
4384

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

4387
通过Promise方式设置音量。
4388

4389
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4390

W
wusongqing 已提交
4391
**参数:**
4392

4393 4394 4395
| 参数名 | 类型   | 必填 | 说明                                                         |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| vol    | number | 是   | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |
4396

W
wusongqing 已提交
4397
**返回值:**
4398

4399 4400 4401
| 类型           | 说明                      |
| -------------- | ------------------------- |
| Promise\<void> | 设置音量的Promise返回值。 |
4402

W
wusongqing 已提交
4403
**示例:**
4404 4405

```js
4406 4407
let vol = 0.5;
videoPlayer.setVolume(vol).then(() => {
4408
  console.info('setVolume success');
4409
}).catch((error) => {
4410
  console.error(`video catchCallback, error:${error}`);
4411 4412
});
```
4413

4414
### release<sup>8+</sup>
B
bird_j 已提交
4415

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

4418
通过回调方式释放视频资源。
4419

4420
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4421

4422
**参数:**
4423

4424 4425 4426
| 参数名   | 类型                 | 必填 | 说明                     |
| -------- | -------------------- | ---- | ------------------------ |
| callback | AsyncCallback\<void> | 是   | 释放视频资源的回调方法。 |
4427

W
wusongqing 已提交
4428
**示例:**
4429 4430

```js
4431
videoPlayer.release((err) => {
4432 4433 4434 4435 4436
  if (err == null) {
    console.info('release success!');
  } else {
    console.error('release fail!');
  }
4437 4438 4439
});
```

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

4442
release(): Promise\<void>
4443

4444
通过Promise方式释放视频资源。
4445

4446
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4447

4448
**返回值:**
B
bird_j 已提交
4449

4450 4451 4452
| 类型           | 说明                          |
| -------------- | ----------------------------- |
| Promise\<void> | 释放视频资源的Promise返回值。 |
Z
zengyawen 已提交
4453

4454
**示例:**
4455

4456
```js
4457
videoPlayer.release().then(() => {
4458
  console.info('release success');
4459
}).catch((error) => {
4460
  console.error(`video catchCallback, error:${error}`);
4461 4462
});
```
4463

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

4466
getTrackDescription(callback: AsyncCallback\<Array\<MediaDescription>>): void
4467

4468
通过回调方式获取视频轨道信息。
4469

4470
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4471 4472 4473

**参数:**

4474 4475 4476
| 参数名   | 类型                                                         | 必填 | 说明                                       |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
| callback | AsyncCallback\<Array\<[MediaDescription](#mediadescription8)>> | 是   | 视频轨道信息MediaDescription数组回调方法。 |
4477

W
wusongqing 已提交
4478
**示例:**
4479 4480

```js
4481
function printfDescription(obj) {
4482 4483 4484 4485 4486
  for (let item in obj) {
    let property = obj[item];
    console.info('video key is ' + item);
    console.info('video value is ' + property);
  }
4487 4488 4489
}

videoPlayer.getTrackDescription((error, arrList) => {
4490 4491 4492
  if ((arrList) != null) {
    for (let i = 0; i < arrList.length; i++) {
      printfDescription(arrList[i]);
4493
    }
4494 4495 4496
  } else {
    console.log(`video getTrackDescription fail, error:${error}`);
  }
4497 4498 4499
});
```

4500
### getTrackDescription<sup>8+</sup>
B
bird_j 已提交
4501

4502
getTrackDescription(): Promise\<Array\<MediaDescription>>
4503

4504
通过Promise方式获取视频轨道信息。
4505

4506
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4507

4508
**返回值:**
4509

4510 4511 4512
| 类型                                                   | 说明                                            |
| ------------------------------------------------------ | ----------------------------------------------- |
| Promise<Array<[MediaDescription](#mediadescription8)>> | 视频轨道信息MediaDescription数组Promise返回值。 |
4513

4514
**示例:**
4515

4516 4517
```js
function printfDescription(obj) {
4518 4519 4520 4521 4522
  for (let item in obj) {
    let property = obj[item];
    console.info('video key is ' + item);
    console.info('video value is ' + property);
  }
4523
}
4524

4525 4526
let arrayDescription;
videoPlayer.getTrackDescription().then((arrList) => {
4527 4528 4529 4530 4531
  if (arrList != null) {
    arrayDescription = arrList;
  } else {
    console.log('video getTrackDescription fail');
  }
4532
}).catch((error) => {
4533
  console.info(`video catchCallback, error:${error}`);
4534 4535
});
for (let i = 0; i < arrayDescription.length; i++) {
4536
  printfDescription(arrayDescription[i]);
4537 4538
}
```
4539

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

4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553
setSpeed(speed:number, callback: AsyncCallback\<number>): void

通过回调方式设置播放速度。

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

**参数:**

| 参数名   | 类型                   | 必填 | 说明                                                       |
| -------- | ---------------------- | ---- | ---------------------------------------------------------- |
| speed    | number                 | 是   | 指定播放视频速度,具体见[PlaybackSpeed](#playbackspeed8)。 |
| callback | AsyncCallback\<number> | 是   | 设置播放速度的回调方法。                                   |
4554

W
wusongqing 已提交
4555
**示例:**
4556 4557

```js
4558 4559 4560 4561
import media from '@ohos.multimedia.media'
let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X;

videoPlayer.setSpeed(speed, (err, result) => {
4562 4563 4564 4565 4566
  if (err == null) {
    console.info('setSpeed success!');
  } else {
    console.error('setSpeed fail!');
  }
4567 4568 4569
});
```

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

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

4574
通过Promise方式设置播放速度。
4575

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

4578
**参数:**
4579

4580 4581 4582
| 参数名 | 类型   | 必填 | 说明                                                       |
| ------ | ------ | ---- | ---------------------------------------------------------- |
| speed  | number | 是   | 指定播放视频速度,具体见[PlaybackSpeed](#playbackspeed8)。 |
B
bird_j 已提交
4583

4584
**返回值:**
4585

4586 4587 4588
| 类型             | 说明                                                         |
| ---------------- | ------------------------------------------------------------ |
| Promise\<number> | 播放速度Promise返回值,具体见[PlaybackSpeed](#playbackspeed8)。 |
4589

W
wusongqing 已提交
4590
**示例:**
4591 4592

```js
4593 4594 4595 4596
import media from '@ohos.multimedia.media'
let speed = media.PlaybackSpeed.SPEED_FORWARD_2_00_X;

videoPlayer.setSpeed(speed).then(() => {
4597
  console.info('setSpeed success');
4598
}).catch((error) => {
4599
  console.error(`video catchCallback, error:${error}`);
4600 4601 4602
});
```

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

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

4607 4608 4609 4610 4611 4612 4613 4614 4615 4616
开始监听视频播放完成事件。

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

**参数:**

| 参数名   | 类型     | 必填 | 说明                                                        |
| -------- | -------- | ---- | ----------------------------------------------------------- |
| type     | string   | 是   | 视频播放完成事件回调类型,支持的事件:'playbackCompleted'。 |
| callback | function | 是   | 视频播放完成事件回调方法。                                  |
4617

4618
**示例:**
4619

4620 4621
```js
videoPlayer.on('playbackCompleted', () => {
4622
  console.info('playbackCompleted success!');
4623 4624
});
```
4625

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

4628
on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void
B
bird_j 已提交
4629

4630
开始监听视频缓存更新事件。仅网络播放支持该订阅事件。
4631

4632
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4633

4634
**参数:**
4635

4636 4637 4638 4639
| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 视频缓存事件回调类型,支持的事件:'bufferingUpdate'。        |
| callback | function | 是   | 视频缓存事件回调方法。<br>[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时,value值有效,否则固定为0。 |
4640

W
wusongqing 已提交
4641
**示例:**
4642 4643

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

4650
### on('startRenderFrame')<sup>8+</sup>
B
bird_j 已提交
4651

4652
on(type: 'startRenderFrame', callback: Callback\<void>): void
Z
zengyawen 已提交
4653

4654
开始监听视频播放首帧送显上报事件。
4655

4656
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4657

W
wusongqing 已提交
4658
**参数:**
4659

4660 4661 4662 4663
| 参数名   | 类型            | 必填 | 说明                                                         |
| -------- | --------------- | ---- | ------------------------------------------------------------ |
| type     | string          | 是   | 视频播放首帧送显上报事件回调类型,支持的事件:'startRenderFrame'。 |
| callback | Callback\<void> | 是   | 视频播放首帧送显上报事件回调方法。                           |
4664

W
wusongqing 已提交
4665
**示例:**
4666 4667

```js
4668
videoPlayer.on('startRenderFrame', () => {
4669
  console.info('startRenderFrame success!');
4670 4671 4672
});
```

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

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

4677
开始监听视频播放宽高变化事件。
4678

4679
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4680

4681
**参数:**
4682

4683 4684 4685 4686
| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type     | string   | 是   | 视频播放宽高变化事件回调类型,支持的事件:'videoSizeChanged'。 |
| callback | function | 是   | 视频播放宽高变化事件回调方法,width表示宽,height表示高。    |
4687

W
wusongqing 已提交
4688
**示例:**
4689 4690

```js
4691
videoPlayer.on('videoSizeChanged', (width, height) => {
4692 4693
  console.log('video width is: ' + width);
  console.log('video height is: ' + height);
4694 4695 4696
});
```

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

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

4701
开始监听视频播放错误事件,当上报error错误事件后,用户需处理error事件,退出播放操作。
B
bird_j 已提交
4702

4703
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4704

4705
**参数:**
4706

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

4712
**示例:**
Z
zengyawen 已提交
4713

4714
```js
4715
videoPlayer.on('error', (error) => {      // 设置'error'事件回调
4716
  console.error(`video error called, error: ${error}`);
4717
});
4718
videoPlayer.url = 'fd://error';  //设置错误的播放地址,触发'error'事件
4719
```
4720

4721
## VideoPlayState<sup>(deprecated)</sup><a name=videoplayerstate></a>
4722

4723
视频播放的状态机,可通过state属性获取当前状态。
B
bird_j 已提交
4724

4725 4726
> **说明:**
> 从API version 8开始支持,从API version 9开始废弃,建议使用[AVPlayerState](#avplayerstate9)替代。
4727

4728
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
4729

4730 4731 4732 4733 4734 4735 4736 4737
| 名称     | 类型   | 说明           |
| -------- | ------ | -------------- |
| idle     | string | 视频播放空闲。 |
| prepared | string | 视频播放准备。 |
| playing  | string | 视频正在播放。 |
| paused   | string | 视频暂停播放。 |
| stopped  | string | 视频播放停止。 |
| error    | string | 错误状态。     |
4738

4739
## AudioRecorder<sup>(deprecated)</sup>
4740

4741 4742
> **说明:**
> 从API version 6开始支持,从API version 9开始废弃,建议使用[AVRecorder](#avrecorder9)替代。
4743

4744
音频录制管理类,用于录制音频媒体。在调用AudioRecorder的方法前,需要先通过[createAudioRecorder()](#mediacreateaudiorecorder) 构建一个AudioRecorder实例。
4745

4746
### prepare<a name=audiorecorder_prepare></a>
4747

4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760
prepare(config: AudioRecorderConfig): void

录音准备。

**需要权限:** ohos.permission.MICROPHONE

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

**参数:**

| 参数名 | 类型                                        | 必填 | 说明                                                         |
| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ |
| config | [AudioRecorderConfig](#audiorecorderconfigdeprecated) | 是   | 配置录音的相关参数,包括音频输出URI、编码格式、采样率、声道数、输出格式等。 |
B
bird_j 已提交
4761

4762
**示例:**
Z
zengyawen 已提交
4763

4764
```js
4765
let audioRecorderConfig = {
4766 4767 4768 4769 4770 4771 4772
  audioEncoder : media.AudioEncoder.AAC_LC,
  audioEncodeBitRate : 22050,
  audioSampleRate : 22050,
  numberOfChannels : 2,
  format : media.AudioOutputFormat.AAC_ADTS,
  uri : 'fd://1',       // 文件需先由调用者创建,并给予适当的权限
  location : { latitude : 30, longitude : 130},
4773 4774
}
audioRecorder.on('prepare', () => {    //设置'prepare'事件回调
4775
  console.log('prepare success');
4776
});
4777
audioRecorder.prepare(audioRecorderConfig);
4778
```
4779

4780

4781
### start<a name=audiorecorder_start></a>
4782

4783
start(): void
4784

4785
开始录制,需在[prepare](#audiorecorder_on)事件成功触发后,才能调用start方法。
4786

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

4789
**示例:**
4790

4791 4792
```js
audioRecorder.on('start', () => {    //设置'start'事件回调
4793
  console.log('audio recorder start success');
4794 4795 4796
});
audioRecorder.start();
```
4797

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

4800
pause():void
B
bird_j 已提交
4801

4802 4803 4804
暂停录制,需要在[start](#audiorecorder_on)事件成功触发后,才能调用pause方法。

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

4806
**示例:**
4807

4808
```js
4809
audioRecorder.on('pause', () => {    //设置'pause'事件回调
4810
  console.log('audio recorder pause success');
4811
});
4812
audioRecorder.pause();
4813
```
4814

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

4817
resume():void
4818

4819
恢复录制,需要在[pause](#audiorecorder_on)事件成功触发后,才能调用resume方法。
4820

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

4823
**示例:**
4824

4825 4826
```js
audioRecorder.on('resume', () => {    //设置'resume'事件回调
4827
  console.log('audio recorder resume success');
4828 4829 4830
});
audioRecorder.resume();
```
4831

4832
### stop<a name=audiorecorder_stop></a>
4833

4834
stop(): void
4835

4836
停止录音。
Z
zengyawen 已提交
4837

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

4840
**示例:**
4841

4842
```js
4843
audioRecorder.on('stop', () => {    //设置'stop'事件回调
4844
  console.log('audio recorder stop success');
4845
});
4846
audioRecorder.stop();
4847
```
B
bird_j 已提交
4848

4849
### release<a name=audiorecorder_release></a>
4850

4851
release(): void
4852

4853
释放录音资源。
4854

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

4857
**示例:**
4858

4859 4860
```js
audioRecorder.on('release', () => {    //设置'release'事件回调
4861
  console.log('audio recorder release success');
4862 4863 4864 4865
});
audioRecorder.release();
audioRecorder = undefined;
```
4866

4867
### reset<a name=audiorecorder_reset></a>
4868

4869
reset(): void
4870

4871
重置录音。
4872

4873
进行重置录音之前,需要先调用[stop()](#audiorecorder_stop)停止录音。重置录音之后,需要调用[prepare()](#audiorecorder_prepare)设置录音参数项,才能再次进行录音。
Z
zengyawen 已提交
4874

4875
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
B
bird_j 已提交
4876

4877
**示例:**
4878

4879
```js
4880
audioRecorder.on('reset', () => {    //设置'reset'事件回调
4881
  console.log('audio recorder reset success');
4882
});
4883
audioRecorder.reset();
4884
```
4885

4886
### on('prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset')<a name=audiorecorder_on></a>
4887

4888
on(type: 'prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset', callback: () => void): void
4889

4890
开始订阅音频录制事件。
4891

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

4894
**参数:**
4895

4896 4897 4898 4899
| 参数名   | 类型     | 必填 | 说明                                                         |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| 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 | 是   | 录制事件回调方法。                                           |
4900

W
wusongqing 已提交
4901
**示例:**
4902 4903

```js
4904 4905
let audioRecorder = media.createAudioRecorder();                                  // 创建一个音频录制实例
let audioRecorderConfig = {
4906 4907 4908 4909 4910 4911 4912
  audioEncoder : media.AudioEncoder.AAC_LC,
  audioEncodeBitRate : 22050,
  audioSampleRate : 22050,
  numberOfChannels : 2,
  format : media.AudioOutputFormat.AAC_ADTS,
  uri : 'fd://xx',                                                            // 文件需先由调用者创建,并给予适当的权限
  location : { latitude : 30, longitude : 130},
4913 4914
}
audioRecorder.on('error', (error) => {                                             // 设置'error'事件回调
4915
  console.info(`audio error called, error: ${error}`);
4916 4917
});
audioRecorder.on('prepare', () => {                                              // 设置'prepare'事件回调
4918 4919
  console.log('prepare success');
  audioRecorder.start();                                                       // 开始录制,并触发'start'事件回调
4920 4921
});
audioRecorder.on('start', () => {                                                 // 设置'start'事件回调
4922
  console.log('audio recorder start success');
4923 4924
});
audioRecorder.on('pause', () => {                                                 // 设置'pause'事件回调
4925
  console.log('audio recorder pause success');
4926 4927
});
audioRecorder.on('resume', () => {                                                 // 设置'resume'事件回调
4928
  console.log('audio recorder resume success');
4929 4930
});
audioRecorder.on('stop', () => {                                                 // 设置'stop'事件回调
4931
  console.log('audio recorder stop success');
4932 4933
});
audioRecorder.on('release', () => {                                                 // 设置'release'事件回调
4934
  console.log('audio recorder release success');
4935 4936
});
audioRecorder.on('reset', () => {                                                 // 设置'reset'事件回调
4937
  console.log('audio recorder reset success');
4938
});
4939
audioRecorder.prepare(audioRecorderConfig)                                       // 设置录制参数 ,并触发'prepare'事件回调
4940 4941
```

4942
### on('error')
4943 4944 4945

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

4946
开始订阅音频录制错误事件,当上报error错误事件后,用户需处理error事件,退出录制操作。
4947

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

W
wusongqing 已提交
4950
**参数:**
B
bird_j 已提交
4951

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

W
wusongqing 已提交
4957
**示例:**
4958 4959

```js
4960
let audioRecorderConfig = {
4961 4962 4963 4964 4965 4966 4967
  audioEncoder : media.AudioEncoder.AAC_LC,
  audioEncodeBitRate : 22050,
  audioSampleRate : 22050,
  numberOfChannels : 2,
  format : media.AudioOutputFormat.AAC_ADTS,
  uri : 'fd://xx',                                                     // 文件需先由调用者创建,并给予适当的权限
  location : { latitude : 30, longitude : 130},
4968 4969
}
audioRecorder.on('error', (error) => {                                  // 设置'error'事件回调
4970
  console.error(`audio error called, error: ${error}`);
4971 4972
});
audioRecorder.prepare(audioRecorderConfig);                            // prepare不设置参数,触发'error'事件
4973 4974
```

4975
## AudioRecorderConfig<sup>(deprecated)</sup>
4976

4977
> **说明:**
4978
> 从API version 6开始支持,从API version 9开始废弃,建议使用[AVRecorderConfig](#avrecorderconfig9)替代。
Z
zengyawen 已提交
4979

4980
表示音频的录音配置。
4981

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

4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994
| 名称                                | 类型                                         | 必填 | 说明                                                         |
| ----------------------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ |
| audioEncoder                        | [AudioEncoder](#audioencoderdeprecated)                | 否   | 音频编码格式,默认设置为AAC_LC。<br/>**说明:** 从API version 8开始废弃,建议使用audioEncoderMime替代。 |
| audioEncodeBitRate                  | number                                       | 否   | 音频编码比特率,默认值为48000。                              |
| audioSampleRate                     | number                                       | 否   | 音频采集采样率,默认值为48000。                              |
| numberOfChannels                    | number                                       | 否   | 音频采集声道数,默认值为2。                                  |
| format                              | [AudioOutputFormat](#audiooutputformatdeprecated)      | 否   | 音频输出封装格式,默认设置为MPEG_4。<br/>**说明:** 从API version 8开始废弃,建议使用fileFormat替代。 |
| location                            | [Location](#location)                        | 否   | 音频采集的地理位置。                                         |
| uri                                 | string                                       | 是   | 音频输出URI:fd://xx&nbsp;(fd&nbsp;number)<br/>![](figures/zh-cn_image_url.png) <br/>文件需要由调用者创建,并赋予适当的权限。 |
| audioEncoderMime<sup>8+</sup>       | [CodecMimeType](#codecmimetype8)             | 否   | 音频编码格式。                                               |
| fileFormat<sup>8+</sup>             | [ContainerFormatType](#containerformattype8) | 否   | 音频编码格式。                                               |
4995

4996
## AudioEncoder<sup>(deprecated)</sup>
4997

4998
> **说明:**
4999
> 从API version 6开始支持,从API version 8开始废弃,建议使用[CodecMimeType](#codecmimetype8)替代。
Z
zengyawen 已提交
5000

5001
表示音频编码格式的枚举。
5002

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

5005 5006 5007 5008 5009 5010 5011
| 名称    | 值   | 说明                                                         |
| ------- | ---- | ------------------------------------------------------------ |
| 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/>仅做接口定义,暂不支持使用。 |
| AAC_LC  | 3    | AAC-LC(Advanced&nbsp;Audio&nbsp;Coding&nbsp;Low&nbsp;Complexity)编码格式。 |
| HE_AAC  | 4    | HE_AAC(High-Efficiency Advanced&nbsp;Audio&nbsp;Coding)编码格式。<br/>仅做接口定义,暂不支持使用。 |
5012

5013
## AudioOutputFormat<sup>(deprecated)</sup>
5014

5015
> **说明:**
5016
> 从API version 6开始支持,从API version 8 开始废弃,建议使用[ContainerFormatType](#containerformattype8)替代。
Z
zengyawen 已提交
5017

5018
表示音频封装格式的枚举。
5019

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

5022 5023 5024 5025 5026 5027 5028
| 名称     | 值   | 说明                                                         |
| -------- | ---- | ------------------------------------------------------------ |
| DEFAULT  | 0    | 默认封装格式。<br/>仅做接口定义,暂不支持使用。              |
| MPEG_4   | 2    | 封装为MPEG-4格式。                                           |
| AMR_NB   | 3    | 封装为AMR_NB格式。<br/>仅做接口定义,暂不支持使用。          |
| AMR_WB   | 4    | 封装为AMR_WB格式。<br/>仅做接口定义,暂不支持使用。          |
| AAC_ADTS | 6    | 封装为ADTS(Audio&nbsp;Data&nbsp;Transport&nbsp;Stream)格式,是AAC音频的传输流格式。 |