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