1# @ohos.multimedia.media (媒体服务)(系统接口) 2 3媒体子系统为开发者提供一套简单且易于理解的接口，使得开发者能够方便接入系统并使用系统的媒体资源。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.multimedia.media (媒体服务)](js-apis-media.md)。 9 10## 导入模块 11 12```ts 13import { media } from '@kit.MediaKit'; 14``` 15 16## media.createVideoRecorder<sup>9+</sup> 17 18createVideoRecorder(callback: AsyncCallback\<VideoRecorder>): void 19 20异步方式创建视频录制实例。通过注册回调函数获取返回值。 21一台设备只允许创建一个录制实例。 22 23**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 24 25**系统接口：** 该接口为系统接口 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 31| callback | AsyncCallback<[VideoRecorder](#videorecorder9)> | 是 | 回调函数。异步返回VideoRecorder实例，失败时返回null。可用于录制视频媒体。 | 32 33**错误码：** 34 35以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 36 37| 错误码ID | 错误信息 | 38| -------- | ------------------------------ | 39| 5400101 | No memory. Return by callback. | 40 41**示例：** 42 43```ts 44import { BusinessError } from '@kit.BasicServicesKit'; 45 46let videoRecorder: media.VideoRecorder; 47media.createVideoRecorder((error: BusinessError, video: media.VideoRecorder) => { 48 if (video != null) { 49 videoRecorder = video; 50 console.info('video createVideoRecorder success'); 51 } else { 52 console.error(`video createVideoRecorder fail, error message:${error.message}`); 53 } 54}); 55``` 56 57## media.createVideoRecorder<sup>9+</sup> 58 59createVideoRecorder(): Promise\<VideoRecorder> 60 61异步方式创建视频录制实例。通过Promise获取返回值。 62一台设备只允许创建一个录制实例。 63 64**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 65 66**系统接口：** 该接口为系统接口 67 68**返回值：** 69 70| 类型 | 说明 | 71| ----------------------------------------- | ------------------------------------------------------------ | 72| Promise<[VideoRecorder](#videorecorder9)> | Promise对象。异步返回VideoRecorder实例，失败时返回null。可用于录制视频媒体。 | 73 74**错误码：** 75 76以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 77 78| 错误码ID | 错误信息 | 79| -------- | ----------------------------- | 80| 5400101 | No memory. Return by promise. | 81 82**示例：** 83 84```ts 85import { BusinessError } from '@kit.BasicServicesKit'; 86 87let videoRecorder: media.VideoRecorder; 88media.createVideoRecorder().then((video: media.VideoRecorder) => { 89 if (video != null) { 90 videoRecorder = video; 91 console.info('video createVideoRecorder success'); 92 } else { 93 console.error('video createVideoRecorder fail'); 94 } 95}).catch((error: BusinessError) => { 96 console.error(`video catchCallback, error message:${error.message}`); 97}); 98``` 99 100## media.reportAVScreenCaptureUserChoice<sup>12+</sup> 101 102reportAVScreenCaptureUserChoice(sessionId: number, choice: string): Promise\<void> 103 104上报录屏隐私弹窗的选择结果到ScreenCapture的服务端，用于判断是否开始录屏。如果用户选择“取消”则不进行录屏，如果用户选择“确定”则开始录屏。 105 106此接口提供给创建弹窗的系统应用调用。 107 108**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture 109 110**系统接口：** 该接口为系统接口 111 112**参数：** 113 114| 参数名 | 类型 | 必填 | 说明 | 115| --------- | ------ | ---- | ------------------------------------------------------------ | 116| sessionId | number | 是 | AVScreenCapture服务会话Id，会由AVScreenCapture拉起隐私弹窗时传给应用。 | 117| choice | string | 是 | 用户的选择内容，“取消”为“false”，“确定”为“true“。 | 118 119**错误码：** 120 121| 错误码ID | 错误信息 | 122| -------- | ------------------------------------------- | 123| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 124| 5400101 | No memory. Return by promise. | 125 126**示例：** 127 128```ts 129import { BusinessError } from '@kit.BasicServicesKit'; 130 131let sessionId: number = 0; // 替换成拉起此进程的sessionId 132let choice: string = 'false'; // 替换成用户的选择内容 133 134try { 135 await media.reportAVScreenCaptureUserChoice(sessionId, choice); 136} catch (error: BusinessError) { 137 console.error(`reportAVScreenCaptureUserChoice error, error message: ${error.message}`); 138} 139``` 140 141## PixelMapParams<sup>11+</sup> 142 143获取视频缩略图时，输出缩略图的格式参数。 144 145**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 146 147| 名称 | 类型 | 可读 | 可写 | 说明 | 148| -------- | ------ | ------| ------ | ---------------------- | 149| colorFormat | [PixelFormat](#pixelformat11) | 是 | 是 | 输出的缩略图颜色格式<br>**系统接口：** 该接口为系统接口 | 150 151## PixelFormat<sup>11+</sup> 152 153获取视频缩略图时，输出的缩略图采用的颜色格式枚举。 154 155**系统能力：** SystemCapability.Multimedia.Media.AVImageGenerator 156 157**系统接口：** 该接口为系统接口 158 159| 名称 | 值 | 说明 | 160| ------------------------ | --------------- | ------------------------------------------------------------ | 161| RGB_565 | 2 | 表示RGB_565颜色格式。 | 162| RGBA_8888 | 3 | 表示RGBA_8888颜色格式。 | 163| RGB_888 | 5 | 表示RGB_888颜色格式。 | 164 165## AvPlayer<sup>9+</sup> 166> **说明：** 167> 播放管理类，用于管理和播放媒体资源。在调用AVPlayer的方法前，需要先通过[createAVPlayer()](js-apis-media.md#mediacreateavplayer9)构建一个[AVPlayer](js-apis-media.md#avplayer9)实例。 168 169### setPlaybackRange<sup>12+</sup> 170 171setPlaybackRange(startTimeMs: number, endTimeMs: number, mode?: SeekMode) : Promise\<void> 172 173设置播放区间，并通过指定的[SeekMode](js-apis-media.md#seekmode8)跳转到区间开始位置。设置之后，只播放音视频文件设定区间内的内容。该方法异步方式返回执行结果，通过Promise获取返回值。可在**initialized**/**prepared**/**paused**/**stopped**/**completed**状态下使用。 174 175**系统能力：** SystemCapability.Multimedia.Media.AvPlayer 176 177**系统接口：** 该接口为系统接口 178 179**参数：** 180 181| 参数名 | 类型 | 必填 | 说明 | 182| -------- | ---------------------- | ---- | --------------------------- | 183| startTimeMs | number | 是 | 区间开始位置，单位ms，取值[0, duration)。可以设置-1值，系统将会从0位置开始播放。| 184| endTimeMs | number | 是 | 区间结束位置，单位ms，取值(startTimeMs, duration]。可以设置-1值，系统将会播放到资源末尾。| 185| mode | [SeekMode](js-apis-media.md#seekmode8) | 否 | 支持SeekMode.SEEK_PREV_SYNC和SeekMode.SEEK_CLOSEST, <br/>默认值: SeekMode.SEEK_PREV_SYNC。| 186 187**错误码：** 188 189以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 190 191| 错误码ID | 错误信息 | 192| -------- | ------------------------------------------ | 193| 202 | Called from Non-System applications. Return by promise. | 194| 401 | The parameter check failed. Return by promise. | 195| 5400102 | Operation not allowed. Return by promise. | 196 197**示例：** 198 199```ts 200import { media } from '@kit.MediaKit'; 201import { BusinessError } from '@kit.BasicServicesKit'; 202 203avPlayer.setPlaybackRange(0, 6000, media.SeekMode.SEEK_CLOSEST).then(() => { 204 console.info('Succeeded setPlaybackRange'); 205}).catch((err: BusinessError) => { 206 console.error('Failed to setPlaybackRange' + err.message); 207}); 208``` 209 210## AVMetadataExtractor<sup>11+</sup> 211> **说明：** 212> 元数据获取类，用于从媒体资源中获取元数据。在调用AVMetadataExtractor的方法前，需要先通过[createAVMetadataExtractor()](js-apis-media.md#mediacreateavmetadataextractor11)构建一个AVMetadataExtractor实例。 213 214### getTimeByFrameIndex<sup>12+</sup> 215 216getTimeByFrameIndex(index: number): Promise\<number> 217 218获取目标视频帧号对应的视频时间戳。仅支持MP4视频文件。 219 220**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 221 222**系统接口：** 该接口为系统接口 223 224**参数：** 225 226| 参数名 | 类型 | 必填 | 说明 | 227| ------ | ------ | ---- | ---------- | 228| index | number | 是 | 视频帧号。 | 229 230**返回值：** 231 232| 类型 | 说明 | 233| ---------------- | ----------------------------------- | 234| Promise\<number> | 时间戳的Promise返回值。单位是微秒。 | 235 236**错误码：** 237 238以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 239 240| 错误码ID | 错误信息 | 241| -------- | ---------------------------------------------- | 242| 401 | The parameter check failed. Return by promise. | 243| 5400102 | Operation not allowed. Returned by promise. | 244| 5400106 | Unsupported format. Returned by promise. | 245 246**示例：** 247 248```ts 249import { media } from '@kit.MediaKit'; 250import { BusinessError } from '@kit.BasicServicesKit'; 251 252avMetadataExtractor.getTimeByFrameIndex(0).then((timeUs: number) => { 253 console.info(`Succeeded getTimeByFrameIndex timeUs: ${timeUs}`); 254}).catch((err: BusinessError) => { 255 console.error(`Failed to getTimeByFrameIndex ${err.message}`); 256}) 257``` 258 259### getFrameIndexByTime<sup>12+</sup> 260 261getFrameIndexByTime(timeUs: number): Promise\<number> 262 263获取目标视频时间戳对应的视频帧号。仅支持MP4视频文件。 264 265**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor 266 267**系统接口：** 该接口为系统接口 268 269**参数：** 270 271| 参数名 | 类型 | 必填 | 说明 | 272| ------ | ------ | ---- | ------------------------ | 273| timeUs | number | 是 | 视频时间戳，单位：微秒。 | 274 275**返回值：** 276 277| 类型 | 说明 | 278| ---------------- | ------------------------- | 279| Promise\<number> | 视频帧号的Promise返回值。 | 280 281**错误码：** 282 283以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 284 285| 错误码ID | 错误信息 | 286| -------- | ---------------------------------------------- | 287| 401 | The parameter check failed. Return by promise. | 288| 5400102 | Operation not allowed. Returned by promise. | 289| 5400106 | Unsupported format. Returned by promise. | 290 291**示例：** 292 293```ts 294import { media } from '@kit.MediaKit'; 295import { BusinessError } from '@kit.BasicServicesKit'; 296 297avMetadataExtractor.getFrameIndexByTime(0).then((index: number) => { 298 console.info(`Succeeded getFrameIndexByTime index: ${index}`); 299}).catch((err: BusinessError) => { 300 console.error(`Failed to getFrameIndexByTime ${err.message}`); 301}) 302``` 303 304## AVRecorder<sup>9+</sup> 305 306音视频录制管理类，用于音视频媒体录制。在调用AVRecorder的方法前，需要先通过[createAVRecorder()](js-apis-media.md#mediacreateavrecorder9)构建一个AVRecorder实例。 307 308> **说明：** 309> 310> 使用相机进行视频录制时，需要与相机模块配合，相机模块接口的使用详情见[相机管理](../apis-camera-kit/js-apis-camera.md)。 311 312### isWatermarkSupported<sup>12+</sup> 313 314isWatermarkSupported(): Promise\<boolean> 315 316检查当前设备录制是否支持硬件数字水印能力。通过Promise获取返回值。 317 318可在[prepare()](js-apis-media.md#prepare9-3)、[start()](js-apis-media.md#start9)、[paused()](js-apis-media.md#pause9)事件成功触发后调用。 319 320**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 321 322**系统接口：** 该接口为系统接口 323 324**返回值：** 325 326| 类型 | 说明 | 327| ---------------- | -------------------------------- | 328| Promise\<boolean> | 获取是否支持水印的Promise返回值。 | 329 330**示例：** 331 332```ts 333import { BusinessError } from '@kit.BasicServicesKit'; 334 335avRecorder.isWatermarkSupported().then((isWatermarkSupported: boolean) => { 336 console.info(`Succeeded in get, isWatermarkSupported: ${isWatermarkSupported}`); 337}).catch((error: BusinessError) => { 338 console.error(`Failed to get and catch error is ${error.message}`); 339}); 340``` 341 342### setWatermark<sup>12+</sup> 343 344setWatermark(watermark: image.PixelMap, config: WatermarkConfig): Promise\<void> 345 346给AVRecorder设置水印图像。通过Promise获取返回值。 347 348当且仅当[prepare()](js-apis-media.md#prepare9-3)事件成功触发后，且在[start()](js-apis-media.md#start9)之前，才能调用setWatermark方法。 349 350**系统能力：** SystemCapability.Multimedia.Media.AVRecorder 351 352**系统接口：** 该接口为系统接口 353 354**参数：** 355 356| 参数名 | 类型 | 必填 | 说明 | 357| -------- | -------------------- | ---- | --------------------------- | 358| watermark | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | 是 | 图像PixelMap数据。<br>当前支持规格:<br>-当前仅支持pixelformat为RGBA8888。<br>-原图像为8K时->水印图像限制范围3072x288,原图像为4K时->水印图像限制范围1536x144。 | 359| config | [WatermarkConfig](#watermarkconfig12) | 是 | 水印的相关配置参数。 | 360 361**返回值：** 362 363| 类型 | 说明 | 364| ---------------- | -------------------------------- | 365| Promise\<void> | 异步返回函数执行结果。 | 366 367**错误码：** 368 369以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 370 371| 错误码ID | 错误信息 | 372| -------- | -------------------------------------- | 373| 401 | The parameter check failed. Return by promise. | 374| 801 | Capability not supported. Return by promise. | 375 376**示例：** 377 378```ts 379import { BusinessError } from '@kit.BasicServicesKit'; 380import { image } from '@kit.ImageKit'; 381 382let watermark: image.PixelMap|undefined = undefined; // need data 383let watermarkConfig: media.WatermarkConfig = { top: 100, left: 100 } 384 385avRecorder.setWatermark(watermark, watermarkConfig).then(() => { 386 console.info('Succeeded in setWatermark'); 387}).catch((error: BusinessError) => { 388 console.error(`Failed to setWatermark and catch error is ${error.message}`); 389}); 390``` 391 392## VideoRecorder<sup>9+</sup> 393 394> **说明：** 395> AVRecorder<sup>9+</sup>发布后，VideoRecorder停止维护，建议使用[AVRecorder](js-apis-media.md#avrecorder9)替代。 396 397视频录制管理类，用于录制视频媒体。在调用VideoRecorder的方法前，需要先通过[createVideoRecorder()](#mediacreatevideorecorder9)构建一个[VideoRecorder](#videorecorder9)实例。 398 399### 属性 400 401**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 402 403**系统接口：** 该接口为系统接口 404 405| 名称 | 类型 | 可读 | 可写 | 说明 | 406| ------------------ | -------------------------------------- | ---- | ---- | ---------------- | 407| state<sup>9+</sup> | [VideoRecordState](#videorecordstate9) | 是 | 否 | 视频录制的状态。 | 408 409### prepare<sup>9+</sup> 410 411prepare(config: VideoRecorderConfig, callback: AsyncCallback\<void>): void 412 413异步方式进行视频录制的参数设置。通过注册回调函数获取返回值。 414 415**需要权限：** ohos.permission.MICROPHONE 416 417**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 418 419**系统接口：** 该接口为系统接口 420 421**参数：** 422 423| 参数名 | 类型 | 必填 | 说明 | 424| -------- | -------------------------------------------- | ---- | ----------------------------------- | 425| config | [VideoRecorderConfig](#videorecorderconfig9) | 是 | 配置视频录制的相关参数。 | 426| callback | AsyncCallback\<void> | 是 | 异步视频录制prepare方法的回调方法。 | 427 428**错误码：** 429 430以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 431 432| 错误码ID | 错误信息 | 433| -------- | ------------------------------------------ | 434| 201 | Permission denied. Return by callback. | 435| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 436| 5400102 | Operation not allowed. Return by callback. | 437| 5400105 | Service died. Return by callback. | 438 439**示例：** 440 441```ts 442import { BusinessError } from '@kit.BasicServicesKit'; 443 444// 配置参数以实际硬件设备支持的范围为准 445let videoProfile: media.VideoRecorderProfile = { 446 audioBitrate : 48000, 447 audioChannels : 2, 448 audioCodec : media.CodecMimeType.AUDIO_AAC, 449 audioSampleRate : 48000, 450 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 451 videoBitrate : 2000000, 452 videoCodec : media.CodecMimeType.VIDEO_AVC, 453 videoFrameWidth : 640, 454 videoFrameHeight : 480, 455 videoFrameRate : 30 456} 457 458let videoConfig: media.VideoRecorderConfig = { 459 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 460 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 461 profile : videoProfile, 462 url : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限 463 rotation : 0, 464 location : { latitude : 30, longitude : 130 } 465} 466 467// asyncallback 468videoRecorder.prepare(videoConfig, (err: BusinessError) => { 469 if (err == null) { 470 console.info('prepare success'); 471 } else { 472 console.error('prepare failed and error is ' + err.message); 473 } 474}) 475``` 476 477### prepare<sup>9+</sup> 478 479prepare(config: VideoRecorderConfig): Promise\<void> 480 481异步方式进行视频录制的参数设置。通过Promise获取返回值。 482 483**需要权限：** ohos.permission.MICROPHONE 484 485**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 486 487**系统接口：** 该接口为系统接口 488 489**参数：** 490 491| 参数名 | 类型 | 必填 | 说明 | 492| ------ | -------------------------------------------- | ---- | ------------------------ | 493| config | [VideoRecorderConfig](#videorecorderconfig9) | 是 | 配置视频录制的相关参数。 | 494 495**返回值：** 496 497| 类型 | 说明 | 498| -------------- | ---------------------------------------- | 499| Promise\<void> | 异步视频录制prepare方法的Promise返回值。 | 500 501**错误码：** 502 503以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 504 505| 错误码ID | 错误信息 | 506| -------- | ----------------------------------------- | 507| 201 | Permission denied. Return by promise. | 508| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 509| 5400102 | Operation not allowed. Return by promise. | 510| 5400105 | Service died. Return by promise. | 511 512**示例：** 513 514```ts 515import { BusinessError } from '@kit.BasicServicesKit'; 516 517// 配置参数以实际硬件设备支持的范围为准 518let videoProfile: media.VideoRecorderProfile = { 519 audioBitrate : 48000, 520 audioChannels : 2, 521 audioCodec : media.CodecMimeType.AUDIO_AAC, 522 audioSampleRate : 48000, 523 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 524 videoBitrate : 2000000, 525 videoCodec : media.CodecMimeType.VIDEO_AVC, 526 videoFrameWidth : 640, 527 videoFrameHeight : 480, 528 videoFrameRate : 30 529} 530 531let videoConfig: media.VideoRecorderConfig = { 532 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 533 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 534 profile : videoProfile, 535 url : 'fd://xx', // 文件需先由调用者创建，并给予适当的权限 536 rotation : 0, 537 location : { latitude : 30, longitude : 130 } 538} 539 540// promise 541videoRecorder.prepare(videoConfig).then(() => { 542 console.info('prepare success'); 543}).catch((err: BusinessError) => { 544 console.error('prepare failed and catch error is ' + err.message); 545}); 546``` 547 548### getInputSurface<sup>9+</sup> 549 550getInputSurface(callback: AsyncCallback\<string>): void 551 552异步方式获得录制需要的surface。通过注册回调函数获取返回值。此surface提供给调用者，调用者从此surface中获取surfaceBuffer，填入相应的数据。 553 554应当注意，填入的视频数据需要携带时间戳（单位ns），buffersize。时间戳的起始时间请以系统启动时间为基准。 555 556只能在[prepare()](#prepare9)接口调用后调用。 557 558**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 559 560**系统接口：** 该接口为系统接口 561 562**参数：** 563 564| 参数名 | 类型 | 必填 | 说明 | 565| -------- | ---------------------- | ---- | --------------------------- | 566| callback | AsyncCallback\<string> | 是 | 异步获得surface的回调方法。 | 567 568**错误码：** 569 570以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 571 572| 错误码ID | 错误信息 | 573| -------- | ------------------------------------------ | 574| 5400102 | Operation not allowed. Return by callback. | 575| 5400103 | I/O error. Return by callback. | 576| 5400105 | Service died. Return by callback. | 577 578**示例：** 579 580```ts 581import { BusinessError } from '@kit.BasicServicesKit'; 582 583// asyncallback 584let surfaceID: string; // 传递给外界的surfaceID 585videoRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 586 if (err == null) { 587 console.info('getInputSurface success'); 588 surfaceID = surfaceId; 589 } else { 590 console.error('getInputSurface failed and error is ' + err.message); 591 } 592}); 593``` 594 595### getInputSurface<sup>9+</sup> 596 597getInputSurface(): Promise\<string>; 598 599 异步方式获得录制需要的surface。通过Promise获取返回值。此surface提供给调用者，调用者从此surface中获取surfaceBuffer，填入相应的数据。 600 601应当注意，填入的视频数据需要携带时间戳（单位ns），buffersize。时间戳的起始时间请以系统启动时间为基准。 602 603只能在[prepare()](#prepare9-1)接口调用后调用。 604 605**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 606 607**系统接口：** 该接口为系统接口 608 609**返回值：** 610 611| 类型 | 说明 | 612| ---------------- | -------------------------------- | 613| Promise\<string> | 异步获得surface的Promise返回值。 | 614 615**错误码：** 616 617以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 618 619| 错误码ID | 错误信息 | 620| -------- | ----------------------------------------- | 621| 5400102 | Operation not allowed. Return by promise. | 622| 5400103 | I/O error. Return by promise. | 623| 5400105 | Service died. Return by promise. | 624 625**示例：** 626 627```ts 628import { BusinessError } from '@kit.BasicServicesKit'; 629 630// promise 631let surfaceID: string; // 传递给外界的surfaceID 632videoRecorder.getInputSurface().then((surfaceId: string) => { 633 console.info('getInputSurface success'); 634 surfaceID = surfaceId; 635}).catch((err: BusinessError) => { 636 console.error('getInputSurface failed and catch error is ' + err.message); 637}); 638``` 639 640### start<sup>9+</sup> 641 642start(callback: AsyncCallback\<void>): void 643 644异步方式开始视频录制。通过注册回调函数获取返回值。 645 646在[prepare()](#prepare9)和[getInputSurface()](#getinputsurface9)后调用，需要依赖数据源先给surface传递数据。 647 648**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 649 650**系统接口：** 该接口为系统接口 651 652**参数：** 653 654| 参数名 | 类型 | 必填 | 说明 | 655| -------- | -------------------- | ---- | ---------------------------- | 656| callback | AsyncCallback\<void> | 是 | 异步开始视频录制的回调方法。 | 657 658**错误码：** 659 660以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 661 662| 错误码ID | 错误信息 | 663| -------- | ------------------------------------------ | 664| 5400102 | Operation not allowed. Return by callback. | 665| 5400103 | I/O error. Return by callback. | 666| 5400105 | Service died. Return by callback. | 667 668**示例：** 669 670```ts 671import { BusinessError } from '@kit.BasicServicesKit'; 672 673// asyncallback 674videoRecorder.start((err: BusinessError) => { 675 if (err == null) { 676 console.info('start videorecorder success'); 677 } else { 678 console.error('start videorecorder failed and error is ' + err.message); 679 } 680}); 681``` 682 683### start<sup>9+</sup> 684 685start(): Promise\<void> 686 687异步方式开始视频录制。通过Promise获取返回值。 688 689在[prepare()](#prepare9-1)和[getInputSurface()](#getinputsurface9-1)后调用，需要依赖数据源先给surface传递数据。 690 691**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 692 693**系统接口：** 该接口为系统接口 694 695**返回值：** 696 697| 类型 | 说明 | 698| -------------- | ------------------------------------- | 699| Promise\<void> | 异步开始视频录制方法的Promise返回值。 | 700 701**错误码：** 702 703以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 704 705| 错误码ID | 错误信息 | 706| -------- | ----------------------------------------- | 707| 5400102 | Operation not allowed. Return by promise. | 708| 5400103 | I/O error. Return by promise. | 709| 5400105 | Service died. Return by promise. | 710 711**示例：** 712 713```ts 714import { BusinessError } from '@kit.BasicServicesKit'; 715 716// promise 717videoRecorder.start().then(() => { 718 console.info('start videorecorder success'); 719}).catch((err: BusinessError) => { 720 console.error('start videorecorder failed and catch error is ' + err.message); 721}); 722``` 723 724### pause<sup>9+</sup> 725 726pause(callback: AsyncCallback\<void>): void 727 728异步方式暂停视频录制。通过注册回调函数获取返回值。 729 730在[start()](#start9)后调用。可以通过调用[resume()](#resume9)接口来恢复录制。 731 732**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 733 734**系统接口：** 该接口为系统接口 735 736**参数：** 737 738| 参数名 | 类型 | 必填 | 说明 | 739| -------- | -------------------- | ---- | ---------------------------- | 740| callback | AsyncCallback\<void> | 是 | 异步暂停视频录制的回调方法。 | 741 742**错误码：** 743 744以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 745 746| 错误码ID | 错误信息 | 747| -------- | ------------------------------------------ | 748| 5400102 | Operation not allowed. Return by callback. | 749| 5400103 | I/O error. Return by callback. | 750| 5400105 | Service died. Return by callback. | 751 752**示例：** 753 754```ts 755import { BusinessError } from '@kit.BasicServicesKit'; 756 757// asyncallback 758videoRecorder.pause((err: BusinessError) => { 759 if (err == null) { 760 console.info('pause videorecorder success'); 761 } else { 762 console.error('pause videorecorder failed and error is ' + err.message); 763 } 764}); 765``` 766 767### pause<sup>9+</sup> 768 769pause(): Promise\<void> 770 771异步方式暂停视频录制。通过Promise获取返回值。 772 773在[start()](#start9-1)后调用。可以通过调用[resume()](#resume9-1)接口来恢复录制。 774 775**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 776 777**系统接口：** 该接口为系统接口 778 779**返回值：** 780 781| 类型 | 说明 | 782| -------------- | ------------------------------------- | 783| Promise\<void> | 异步暂停视频录制方法的Promise返回值。 | 784 785**错误码：** 786 787以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 788 789| 错误码ID | 错误信息 | 790| -------- | ----------------------------------------- | 791| 5400102 | Operation not allowed. Return by promise. | 792| 5400103 | I/O error. Return by promise. | 793| 5400105 | Service died. Return by promise. | 794 795**示例：** 796 797```ts 798import { BusinessError } from '@kit.BasicServicesKit'; 799 800// promise 801videoRecorder.pause().then(() => { 802 console.info('pause videorecorder success'); 803}).catch((err: BusinessError) => { 804 console.error('pause videorecorder failed and catch error is ' + err.message); 805}); 806``` 807 808### resume<sup>9+</sup> 809 810resume(callback: AsyncCallback\<void>): void 811 812异步方式恢复视频录制。通过注册回调函数获取返回值。 813 814**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 815 816**系统接口：** 该接口为系统接口 817 818**参数：** 819 820| 参数名 | 类型 | 必填 | 说明 | 821| -------- | -------------------- | ---- | ---------------------------- | 822| callback | AsyncCallback\<void> | 是 | 异步恢复视频录制的回调方法。 | 823 824**错误码：** 825 826以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 827 828| 错误码ID | 错误信息 | 829| -------- | ------------------------------------------ | 830| 5400102 | Operation not allowed. Return by callback. | 831| 5400103 | I/O error. Return by callback. | 832| 5400105 | Service died. Return by callback. | 833 834**示例：** 835 836```ts 837import { BusinessError } from '@kit.BasicServicesKit'; 838 839// asyncallback 840videoRecorder.resume((err: BusinessError) => { 841 if (err == null) { 842 console.info('resume videorecorder success'); 843 } else { 844 console.error('resume videorecorder failed and error is ' + err.message); 845 } 846}); 847``` 848 849### resume<sup>9+</sup> 850 851resume(): Promise\<void> 852 853异步方式恢复视频录制。通过Promise获取返回值。 854 855**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 856 857**系统接口：** 该接口为系统接口 858 859**返回值：** 860 861| 类型 | 说明 | 862| -------------- | ------------------------------------- | 863| Promise\<void> | 异步恢复视频录制方法的Promise返回值。 | 864 865**错误码：** 866 867以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 868 869| 错误码ID | 错误信息 | 870| -------- | ----------------------------------------- | 871| 5400102 | Operation not allowed. Return by promise. | 872| 5400103 | I/O error. Return by promise. | 873| 5400105 | Service died. Return by promise. | 874 875**示例：** 876 877```ts 878import { BusinessError } from '@kit.BasicServicesKit'; 879 880// promise 881videoRecorder.resume().then(() => { 882 console.info('resume videorecorder success'); 883}).catch((err: BusinessError) => { 884 console.error('resume videorecorder failed and catch error is ' + err.message); 885}); 886``` 887 888### stop<sup>9+</sup> 889 890stop(callback: AsyncCallback\<void>): void 891 892异步方式停止视频录制。通过注册回调函数获取返回值。 893 894需要重新调用[prepare()](#prepare9)和[getInputSurface()](#getinputsurface9)接口才能重新录制。 895 896**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 897 898**系统接口：** 该接口为系统接口 899 900**参数：** 901 902| 参数名 | 类型 | 必填 | 说明 | 903| -------- | -------------------- | ---- | ---------------------------- | 904| callback | AsyncCallback\<void> | 是 | 异步停止视频录制的回调方法。 | 905 906**错误码：** 907 908以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 909 910| 错误码ID | 错误信息 | 911| -------- | ------------------------------------------ | 912| 5400102 | Operation not allowed. Return by callback. | 913| 5400103 | I/O error. Return by callback. | 914| 5400105 | Service died. Return by callback. | 915 916**示例：** 917 918```ts 919import { BusinessError } from '@kit.BasicServicesKit'; 920 921// asyncallback 922videoRecorder.stop((err: BusinessError) => { 923 if (err == null) { 924 console.info('stop videorecorder success'); 925 } else { 926 console.error('stop videorecorder failed and error is ' + err.message); 927 } 928}); 929``` 930 931### stop<sup>9+</sup> 932 933stop(): Promise\<void> 934 935异步方式停止视频录制。通过Promise获取返回值。 936 937需要重新调用[prepare()](#prepare9-1)和[getInputSurface()](#getinputsurface9-1)接口才能重新录制。 938 939**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 940 941**系统接口：** 该接口为系统接口 942 943**返回值：** 944 945| 类型 | 说明 | 946| -------------- | ------------------------------------- | 947| Promise\<void> | 异步停止视频录制方法的Promise返回值。 | 948 949**错误码：** 950 951以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 952 953| 错误码ID | 错误信息 | 954| -------- | ----------------------------------------- | 955| 5400102 | Operation not allowed. Return by promise. | 956| 5400103 | I/O error. Return by promise. | 957| 5400105 | Service died. Return by promise. | 958 959**示例：** 960 961```ts 962import { BusinessError } from '@kit.BasicServicesKit'; 963 964// promise 965videoRecorder.stop().then(() => { 966 console.info('stop videorecorder success'); 967}).catch((err: BusinessError) => { 968 console.error('stop videorecorder failed and catch error is ' + err.message); 969}); 970``` 971 972### release<sup>9+</sup> 973 974release(callback: AsyncCallback\<void>): void 975 976异步方式释放视频录制资源。通过注册回调函数获取返回值。 977 978**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 979 980**系统接口：** 该接口为系统接口 981 982**参数：** 983 984| 参数名 | 类型 | 必填 | 说明 | 985| -------- | -------------------- | ---- | -------------------------------- | 986| callback | AsyncCallback\<void> | 是 | 异步释放视频录制资源的回调方法。 | 987 988**错误码：** 989 990以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 991 992| 错误码ID | 错误信息 | 993| -------- | --------------------------------- | 994| 5400105 | Service died. Return by callback. | 995 996**示例：** 997 998```ts 999import { BusinessError } from '@kit.BasicServicesKit'; 1000 1001// asyncallback 1002videoRecorder.release((err: BusinessError) => { 1003 if (err == null) { 1004 console.info('release videorecorder success'); 1005 } else { 1006 console.error('release videorecorder failed and error is ' + err.message); 1007 } 1008}); 1009``` 1010 1011### release<sup>9+</sup> 1012 1013release(): Promise\<void> 1014 1015异步方式释放视频录制资源。通过Promise获取返回值。 1016 1017**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 1018 1019**系统接口：** 该接口为系统接口 1020 1021**返回值：** 1022 1023| 类型 | 说明 | 1024| -------------- | ----------------------------------------- | 1025| Promise\<void> | 异步释放视频录制资源方法的Promise返回值。 | 1026 1027**错误码：** 1028 1029以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1030 1031| 错误码ID | 错误信息 | 1032| -------- | --------------------------------- | 1033| 5400105 | Service died. Return by callback. | 1034 1035**示例：** 1036 1037```ts 1038import { BusinessError } from '@kit.BasicServicesKit'; 1039 1040// promise 1041videoRecorder.release().then(() => { 1042 console.info('release videorecorder success'); 1043}).catch((err: BusinessError) => { 1044 console.error('release videorecorder failed and catch error is ' + err.message); 1045}); 1046``` 1047 1048### reset<sup>9+</sup> 1049 1050reset(callback: AsyncCallback\<void>): void 1051 1052异步方式重置视频录制。通过注册回调函数获取返回值。 1053 1054需要重新调用[prepare()](#prepare9)和[getInputSurface()](#getinputsurface9)接口才能重新录制。 1055 1056**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 1057 1058**系统接口：** 该接口为系统接口 1059 1060**参数：** 1061 1062| 参数名 | 类型 | 必填 | 说明 | 1063| -------- | -------------------- | ---- | ---------------------------- | 1064| callback | AsyncCallback\<void> | 是 | 异步重置视频录制的回调方法。 | 1065 1066**错误码：** 1067 1068以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1069 1070| 错误码ID | 错误信息 | 1071| -------- | --------------------------------- | 1072| 5400103 | I/O error. Return by callback. | 1073| 5400105 | Service died. Return by callback. | 1074 1075**示例：** 1076 1077```ts 1078import { BusinessError } from '@kit.BasicServicesKit'; 1079 1080// asyncallback 1081videoRecorder.reset((err: BusinessError) => { 1082 if (err == null) { 1083 console.info('reset videorecorder success'); 1084 } else { 1085 console.error('reset videorecorder failed and error is ' + err.message); 1086 } 1087}); 1088``` 1089 1090### reset<sup>9+</sup> 1091 1092reset(): Promise\<void> 1093 1094异步方式重置视频录制。通过Promise获取返回值。 1095 1096需要重新调用[prepare()](#prepare9-1)和[getInputSurface()](#getinputsurface9-1)接口才能重新录制。 1097 1098**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 1099 1100**系统接口：** 该接口为系统接口 1101 1102**返回值：** 1103 1104| 类型 | 说明 | 1105| -------------- | ------------------------------------- | 1106| Promise\<void> | 异步重置视频录制方法的Promise返回值。 | 1107 1108**错误码：** 1109 1110以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1111 1112| 错误码ID | 错误信息 | 1113| -------- | -------------------------------- | 1114| 5400103 | I/O error. Return by promise. | 1115| 5400105 | Service died. Return by promise. | 1116 1117**示例：** 1118 1119```ts 1120import { BusinessError } from '@kit.BasicServicesKit'; 1121 1122// promise 1123videoRecorder.reset().then(() => { 1124 console.info('reset videorecorder success'); 1125}).catch((err: BusinessError) => { 1126 console.error('reset videorecorder failed and catch error is ' + err.message); 1127}); 1128``` 1129 1130### on('error')<sup>9+</sup> 1131 1132on(type: 'error', callback: ErrorCallback): void 1133 1134开始订阅视频录制错误事件，当上报error错误事件后，用户需处理error事件，退出录制操作。 1135 1136**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 1137 1138**系统接口：** 该接口为系统接口 1139 1140**参数：** 1141 1142| 参数名 | 类型 | 必填 | 说明 | 1143| -------- | ------------- | ---- | ------------------------------------------------------------ | 1144| type | string | 是 | 录制错误事件回调类型'error'。<br/>- 'error'：视频录制过程中发生错误，触发该事件。 | 1145| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是 | 录制错误事件回调方法。 | 1146 1147**错误码：** 1148 1149以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) 1150 1151| 错误码ID | 错误信息 | 1152| -------- | --------------------------------- | 1153| 5400103 | I/O error. Return by callback. | 1154| 5400105 | Service died. Return by callback. | 1155 1156**示例：** 1157 1158```ts 1159import { BusinessError } from '@kit.BasicServicesKit'; 1160 1161// 当获取videoRecordState接口出错时通过此订阅事件上报 1162videoRecorder.on('error', (error: BusinessError) => { // 设置'error'事件回调 1163 console.error(`audio error called, error: ${error}`); 1164}) 1165``` 1166 1167## VideoRecordState<sup>9+</sup> 1168 1169视频录制的状态机。可通过state属性获取当前状态。 1170 1171**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 1172 1173**系统接口：** 该接口为系统接口 1174 1175| 名称 | 类型 | 说明 | 1176| -------- | ------ | ---------------------- | 1177| idle | string | 视频录制空闲。 | 1178| prepared | string | 视频录制参数设置完成。 | 1179| playing | string | 视频正在录制。 | 1180| paused | string | 视频暂停录制。 | 1181| stopped | string | 视频录制停止。 | 1182| error | string | 错误状态。 | 1183 1184## VideoRecorderConfig<sup>9+</sup> 1185 1186表示视频录制的参数设置。 1187 1188通过audioSourceType和videoSourceType区分纯视频录制和音视频录制（纯音频录制请使用[AVRecorder](js-apis-media.md#avrecorder9)或[AudioRecorder](js-apis-media.md#audiorecorderdeprecated)）。纯视频录制时，仅需要设置videoSourceType；音视频录制时，audioSourceType和videoSourceType均需要设置。 1189 1190**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 1191 1192**系统接口：** 该接口为系统接口 1193 1194| 名称 | 类型 | 必填 | 说明 | 1195| --------------- | ---------------------------------------------- | ---- | ------------------------------------------------------------ | 1196| audioSourceType | [AudioSourceType](js-apis-media.md#audiosourcetype9) | 否 | 视频录制的音频源类型，选择音频录制时必填。 | 1197| videoSourceType | [VideoSourceType](js-apis-media.md#videosourcetype9) | 是 | 视频录制的视频源类型。 | 1198| profile | [VideoRecorderProfile](#videorecorderprofile9) | 是 | 视频录制的profile。 | 1199| rotation | number | 否 | 录制的视频旋转角度，仅支持0，90，180，270，默认值为0。 | 1200| location | [Location](js-apis-media.md#location) | 否 | 录制视频的地理位置，默认不记录地理位置信息。 | 1201| url | string | 是 | 视频输出URL：fd://xx (fd number)<br/> | 1202 1203## VideoRecorderProfile<sup>9+</sup> 1204 1205视频录制的配置文件。 1206 1207**系统能力：** SystemCapability.Multimedia.Media.VideoRecorder 1208 1209**系统接口：** 该接口为系统接口 1210 1211| 名称 | 类型 | 必填 | 说明 | 1212| ---------------- | -------------------------------------------- | ---- | ---------------- | 1213| audioBitrate | number | 否 | 音频编码比特率，选择音频录制时必填。 | 1214| audioChannels | number | 否 | 音频采集声道数，选择音频录制时必填。 | 1215| audioCodec | [CodecMimeType](js-apis-media.md#codecmimetype8) | 否 | 音频编码格式，选择音频录制时必填。 | 1216| audioSampleRate | number | 否 | 音频采样率，选择音频录制时必填。 | 1217| fileFormat | [ContainerFormatType](js-apis-media.md#containerformattype8) | 是 | 文件的容器格式。 | 1218| videoBitrate | number | 是 | 视频编码比特率。 | 1219| videoCodec | [CodecMimeType](js-apis-media.md#codecmimetype8) | 是 | 视频编码格式。 | 1220| videoFrameWidth | number | 是 | 录制视频帧的宽。 | 1221| videoFrameHeight | number | 是 | 录制视频帧的高。 | 1222| videoFrameRate | number | 是 | 录制视频帧率。 | 1223 1224## WatermarkConfig<sup>12+</sup> 1225 1226设置给AVRecorder的水印相关配置，该位置以画面的左上角为开始点。 1227 1228**系统能力：** SystemCapability.Multimedia.Media.Core 1229 1230**系统接口：** 该接口为系统接口 1231 1232| 名称 | 类型 | 必填 | 说明 | 1233| --------- | ------ | ---- | ---------------- | 1234| top | number | 是 | 显示位置，距离图像顶部的像素偏移量。 | 1235| left | number | 是 | 显示位置，距离图像左部的像素偏移量。 |
