1# @ohos.multimedia.media (Media) (System API) 2 3The multimedia subsystem provides a set of simple and easy-to-use APIs for you to access the system and use media resources. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> - This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.multimedia.media (Media)](js-apis-media.md). 9 10## Modules to Import 11 12```ts 13import { media } from '@kit.MediaKit'; 14``` 15 16## media.createVideoRecorder<sup>9+</sup> 17 18createVideoRecorder(callback: AsyncCallback\<VideoRecorder>): void 19 20Creates a **VideoRecorder** instance. This API uses an asynchronous callback to return the result. 21 22Only one **VideoRecorder** instance can be created per device. 23 24**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 25 26**System API**: This is a system API. 27 28**Parameters** 29 30| Name | Type | Mandatory| Description | 31| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 32| callback | AsyncCallback<[VideoRecorder](#videorecorder9)> | Yes | Callback used to return the result. If the operation is successful, a **VideoRecorder** instance is returned; otherwise, **null** is returned. The instance can be used to record video.| 33 34**Error codes** 35 36For details about the error codes, see [Media Error Codes](errorcode-media.md). 37 38| ID| Error Message | 39| -------- | ------------------------------ | 40| 5400101 | No memory. Return by callback. | 41 42**Example** 43 44```ts 45import { BusinessError } from '@kit.BasicServicesKit'; 46 47let videoRecorder: media.VideoRecorder; 48media.createVideoRecorder((error: BusinessError, video: media.VideoRecorder) => { 49 if (video != null) { 50 videoRecorder = video; 51 console.info('video createVideoRecorder success'); 52 } else { 53 console.error(`video createVideoRecorder fail, error message:${error.message}`); 54 } 55}); 56``` 57 58## media.createVideoRecorder<sup>9+</sup> 59 60createVideoRecorder(): Promise\<VideoRecorder> 61 62Creates a **VideoRecorder** instance. This API uses a promise to return the result. 63 64Only one **VideoRecorder** instance can be created per device. 65 66**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 67 68**System API**: This is a system API. 69 70**Return value** 71 72| Type | Description | 73| ----------------------------------------- | ------------------------------------------------------------ | 74| Promise<[VideoRecorder](#videorecorder9)> | Promise used to return the result. If the operation is successful, a **VideoRecorder** instance is returned; otherwise, **null** is returned. The instance can be used to record video.| 75 76**Error codes** 77 78For details about the error codes, see [Media Error Codes](errorcode-media.md). 79 80| ID| Error Message | 81| -------- | ----------------------------- | 82| 5400101 | No memory. Return by promise. | 83 84**Example** 85 86```ts 87import { BusinessError } from '@kit.BasicServicesKit'; 88 89let videoRecorder: media.VideoRecorder; 90media.createVideoRecorder().then((video: media.VideoRecorder) => { 91 if (video != null) { 92 videoRecorder = video; 93 console.info('video createVideoRecorder success'); 94 } else { 95 console.error('video createVideoRecorder fail'); 96 } 97}).catch((error: BusinessError) => { 98 console.error(`video catchCallback, error message:${error.message}`); 99}); 100``` 101 102## media.reportAVScreenCaptureUserChoice<sup>12+</sup> 103 104reportAVScreenCaptureUserChoice(sessionId: number, choice: string): Promise\<void> 105 106Reports the user selection result in the screen capture privacy dialog box to the AVScreenCapture server to determine whether to start screen capture. Screen capture starts only when the user touches a button to continue the operation. 107 108This API is called by the system application that creates the dialog box. 109 110**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 111 112**System API**: This is a system API. 113 114**Parameters** 115 116| Name | Type | Mandatory| Description | 117| --------- | ------ | ---- | ------------------------------------------------------------ | 118| sessionId | number | Yes | Session ID of the AVScreenCapture service, which is sent to the application when the AVScreenCapture server starts the privacy dialog box.| 119| choice | string | Yes | User choice, including whether screen capture is agreed, selected display ID, and window ID. For details, see JsonData in the example below.| 120 121**Error codes** 122 123| ID| Error Message | 124| -------- | ------------------------------------------- | 125| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 126| 5400101 | No memory. Return by promise. | 127 128**Example** 129 130```ts 131import { BusinessError } from '@kit.BasicServicesKit'; 132import { media } from '@kit.MediaKit'; 133 134class JsonData { 135 public choice: string = 'true' 136 public displayId: number | null = -1 137 public missionId: number | null = -1 138} 139let sessionId: number = 0; // Use the ID of the session that starts the process. 140 141try { 142 const jsonData: JsonData = { 143 choice: 'true', // Replace it with the user choice. 144 displayId: -1, // Replace it with the ID of the display selected by the user. 145 missionId: -1, // Replace it with the ID of the window selected by the user. 146 } 147 await media.reportAVScreenCaptureUserChoice(sessionId, JSON.stringify(jsonData)); 148} catch (error: BusinessError) { 149 console.error(`reportAVScreenCaptureUserChoice error, error message: ${error.message}`); 150} 151``` 152 153## media.getScreenCaptureMonitor<sup>18+</sup> 154 155getScreenCaptureMonitor(): Promise\<ScreenCaptureMonitor> 156 157Obtains a **ScreenCaptureMonitor** instance. This API uses a promise to return the result. 158 159**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 160 161**System API**: This is a system API. 162 163**Return value** 164 165| Type | Description | 166| ----------------------------------------- | ------------------------------------------------------------ | 167| Promise<[ScreenCaptureMonitor](#screencapturemonitor18)> | Promise used to return the result. The instance can be used to query and monitor the status of the system screen recorder.<br>If the operation is successful, a **ScreenCaptureMonitor** instance is returned; otherwise, **null** is returned.| 168 169**Error codes** 170 171For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](errorcode-media.md). 172 173| ID| Error Message | 174| -------- | ----------------------------- | 175| 202 | Not System App. | 176| 5400101 | No memory. Return by promise. | 177 178**Example** 179 180```ts 181let screenCaptureMonitor: media.ScreenCaptureMonitor; 182try { 183 screenCaptureMonitor = await media.getScreenCaptureMonitor(); 184} catch (err) { 185 console.error(`getScreenCaptureMonitor failed, error message:${err.message}`); 186} 187``` 188 189## PixelMapParams<sup>11+</sup> 190 191Defines the format parameters of the video thumbnail to be obtained. 192 193**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 194 195| Name | Type | Readable | Writable | Description | 196| -------- | ------ | ------| ------ | ---------------------- | 197| colorFormat | [PixelFormat](#pixelformat11) | Yes | Yes | Color format of the thumbnail.<br>**System API**: This is a system API. | 198 199## PixelFormat<sup>11+</sup> 200 201Enumerates the color formats supported by the video thumbnail. 202 203**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 204 205**System API**: This is a system API. 206 207| Name | Value | Description | 208| ------------------------ | --------------- | ------------------------------------------------------------ | 209| RGB_565 | 2 | RGB_565. | 210| RGBA_8888 | 3 | RGBA_8888.| 211| RGB_888 | 5 | RGB_888. | 212 213## AVMetadataExtractor<sup>11+</sup> 214 215Provides APIs to obtain metadata from media assets. Before calling any API of **AVMetadataExtractor**, you must use [createAVMetadataExtractor()](js-apis-media.md#mediacreateavmetadataextractor11) to create an **AVMetadataExtractor** instance. 216 217### getTimeByFrameIndex<sup>12+</sup> 218 219getTimeByFrameIndex(index: number): Promise\<number> 220 221Obtains the video timestamp corresponding to a video frame number. Only MP4 video files are supported. 222 223**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 224 225**System API**: This is a system API. 226 227**Parameters** 228 229| Name| Type | Mandatory| Description | 230| ------ | ------ | ---- | ---------- | 231| index | number | Yes | Video frame number.| 232 233**Return value** 234 235| Type | Description | 236| ---------------- | ----------------------------------- | 237| Promise\<number> | Promise used to return the timestamp, in microseconds.| 238 239**Error codes** 240 241For details about the error codes, see [Media Error Codes](errorcode-media.md). 242 243| ID| Error Message | 244| -------- | ---------------------------------------------- | 245| 401 | The parameter check failed. Return by promise. | 246| 5400102 | Operation not allowed. Returned by promise. | 247| 5400106 | Unsupported format. Returned by promise. | 248 249**Example** 250 251```ts 252import { media } from '@kit.MediaKit'; 253import { BusinessError } from '@kit.BasicServicesKit'; 254 255avMetadataExtractor.getTimeByFrameIndex(0).then((timeUs: number) => { 256 console.info(`Succeeded getTimeByFrameIndex timeUs: ${timeUs}`); 257}).catch((err: BusinessError) => { 258 console.error(`Failed to getTimeByFrameIndex ${err.message}`); 259}) 260``` 261 262### getFrameIndexByTime<sup>12+</sup> 263 264getFrameIndexByTime(timeUs: number): Promise\<number> 265 266Obtains the video frame number corresponding to a video timestamp. Only MP4 video files are supported. 267 268**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 269 270**System API**: This is a system API. 271 272**Parameters** 273 274| Name| Type | Mandatory| Description | 275| ------ | ------ | ---- | ------------------------ | 276| timeUs | number | Yes | Video timestamp, in microseconds.| 277 278**Return value** 279 280| Type | Description | 281| ---------------- | ------------------------- | 282| Promise\<number> | Promise used to return the video frame number.| 283 284**Error codes** 285 286For details about the error codes, see [Media Error Codes](errorcode-media.md). 287 288| ID| Error Message | 289| -------- | ---------------------------------------------- | 290| 401 | The parameter check failed. Return by promise. | 291| 5400102 | Operation not allowed. Returned by promise. | 292| 5400106 | Unsupported format. Returned by promise. | 293 294**Example** 295 296```ts 297import { media } from '@kit.MediaKit'; 298import { BusinessError } from '@kit.BasicServicesKit'; 299 300avMetadataExtractor.getFrameIndexByTime(0).then((index: number) => { 301 console.info(`Succeeded getFrameIndexByTime index: ${index}`); 302}).catch((err: BusinessError) => { 303 console.error(`Failed to getFrameIndexByTime ${err.message}`); 304}) 305``` 306 307## AVRecorder<sup>9+</sup> 308 309A recording management class that provides APIs to record media assets. Before calling any API in **AVRecorder**, you must use [createAVRecorder()](js-apis-media.md#mediacreateavrecorder9) to create an **AVRecorder** instance. 310 311> **NOTE** 312> 313> To use the camera to record videos, the camera module is required. For details about how to use the APIs provided by the camera module, see [Camera Management](../apis-camera-kit/js-apis-camera.md). 314 315### isWatermarkSupported<sup>13+</sup> 316 317isWatermarkSupported(): Promise\<boolean> 318 319Checks whether the device supports the hardware digital watermark. This API uses a promise to return the result. 320 321This API can be called after the [prepare()](js-apis-media.md#prepare9-3), [start()](js-apis-media.md#start9), or [paused()](js-apis-media.md#pause9) event is triggered. 322 323**System capability**: SystemCapability.Multimedia.Media.AVRecorder 324 325**System API**: This is a system API. 326 327**Return value** 328 329| Type | Description | 330| ---------------- | -------------------------------- | 331| Promise\<boolean> | Promise used to return the check result.| 332 333**Example** 334 335```ts 336import { BusinessError } from '@kit.BasicServicesKit'; 337 338avRecorder.isWatermarkSupported().then((isWatermarkSupported: boolean) => { 339 console.info(`Succeeded in get, isWatermarkSupported: ${isWatermarkSupported}`); 340}).catch((error: BusinessError) => { 341 console.error(`Failed to get and catch error is ${error.message}`); 342}); 343``` 344 345### setWatermark<sup>13+</sup> 346 347setWatermark(watermark: image.PixelMap, config: WatermarkConfig): Promise\<void> 348 349Sets a watermark for the AVRecorder. This API uses a promise to return the result. 350 351This API can be called only after the [prepare()](js-apis-media.md#prepare9-3) event is triggered and before the [start()](js-apis-media.md#start9) event is triggered. 352 353**System capability**: SystemCapability.Multimedia.Media.AVRecorder 354 355**System API**: This is a system API. 356 357**Parameters** 358 359| Name | Type | Mandatory| Description | 360| -------- | -------------------- | ---- | --------------------------- | 361| watermark | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | PixelMap data.<br>Currently, the following specifications are supported:<br>- Only RGBA8888 is supported.<br>- If the original image is 8K, the watermark resolution should be limited to a size of 3072 x 288; if the original image is 4K, the watermark resolution should be limited to a size of 1536 x 144.| 362| config | [WatermarkConfig](#watermarkconfig13) | Yes | Watermark configuration.| 363 364**Return value** 365 366| Type | Description | 367| ---------------- | -------------------------------- | 368| Promise\<void> | Promise that returns no value.| 369 370**Error codes** 371 372For details about the error codes, see [Media Error Codes](errorcode-media.md). 373 374| ID| Error Message | 375| -------- | -------------------------------------- | 376| 401 | The parameter check failed. Return by promise. | 377| 801 | Capability not supported. Return by promise. | 378 379**Example** 380 381```ts 382import { BusinessError } from '@kit.BasicServicesKit'; 383import { image } from '@kit.ImageKit'; 384 385let watermark: image.PixelMap|undefined = undefined; // need data. 386let watermarkConfig: media.WatermarkConfig = { top: 100, left: 100 } 387 388avRecorder.setWatermark(watermark, watermarkConfig).then(() => { 389 console.info('Succeeded in setWatermark'); 390}).catch((error: BusinessError) => { 391 console.error(`Failed to setWatermark and catch error is ${error.message}`); 392}); 393``` 394 395## VideoRecorder<sup>9+</sup> 396 397> **NOTE** 398> This class is deprecated after AVRecorder<sup>9+</sup> is released. You are advised to use [AVRecorder](js-apis-media.md#avrecorder9) instead. 399 400Implements video recording. Before calling any API in the **VideoRecorder** class, you must use [createVideoRecorder()](#mediacreatevideorecorder9) to create a [VideoRecorder](#videorecorder9) instance. 401 402### Properties 403 404**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 405 406**System API**: This is a system API. 407 408| Name | Type | Readable| Writable| Description | 409| ------------------ | -------------------------------------- | ---- | ---- | ---------------- | 410| state<sup>9+</sup> | [VideoRecordState](#videorecordstate9) | Yes | No | Video recording state.| 411 412### prepare<sup>9+</sup> 413 414prepare(config: VideoRecorderConfig, callback: AsyncCallback\<void>): void 415 416Sets video recording parameters. This API uses an asynchronous callback to return the result. 417 418**Required permissions:** ohos.permission.MICROPHONE 419 420**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 421 422**System API**: This is a system API. 423 424**Parameters** 425 426| Name | Type | Mandatory| Description | 427| -------- | -------------------------------------------- | ---- | ----------------------------------- | 428| config | [VideoRecorderConfig](#videorecorderconfig9) | Yes | Video recording parameters to set. | 429| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 430 431**Error codes** 432 433For details about the error codes, see [Media Error Codes](errorcode-media.md). 434 435| ID| Error Message | 436| -------- | ------------------------------------------ | 437| 201 | Permission denied. Return by callback. | 438| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 439| 5400102 | Operation not allowed. Return by callback. | 440| 5400105 | Service died. Return by callback. | 441 442**Example** 443 444```ts 445import { BusinessError } from '@kit.BasicServicesKit'; 446 447// Configure the parameters based on those supported by the hardware device. 448let videoProfile: media.VideoRecorderProfile = { 449 audioBitrate : 48000, 450 audioChannels : 2, 451 audioCodec : media.CodecMimeType.AUDIO_AAC, 452 audioSampleRate : 48000, 453 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 454 videoBitrate : 2000000, 455 videoCodec : media.CodecMimeType.VIDEO_AVC, 456 videoFrameWidth : 640, 457 videoFrameHeight : 480, 458 videoFrameRate : 30 459} 460 461let videoConfig: media.VideoRecorderConfig = { 462 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 463 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 464 profile : videoProfile, 465 url : 'fd://xx', // The file must be created by the caller and granted with proper permissions. 466 rotation : 0, 467 location : { latitude : 30, longitude : 130 } 468} 469 470// asyncallback. 471videoRecorder.prepare(videoConfig, (err: BusinessError) => { 472 if (err == null) { 473 console.info('prepare success'); 474 } else { 475 console.error('prepare failed and error is ' + err.message); 476 } 477}) 478``` 479 480### prepare<sup>9+</sup> 481 482prepare(config: VideoRecorderConfig): Promise\<void> 483 484Sets video recording parameters. This API uses a promise to return the result. 485 486**Required permissions:** ohos.permission.MICROPHONE 487 488**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 489 490**System API**: This is a system API. 491 492**Parameters** 493 494| Name| Type | Mandatory| Description | 495| ------ | -------------------------------------------- | ---- | ------------------------ | 496| config | [VideoRecorderConfig](#videorecorderconfig9) | Yes | Video recording parameters to set.| 497 498**Return value** 499 500| Type | Description | 501| -------------- | ---------------------------------------- | 502| Promise\<void> | Promise used to return the result.| 503 504**Error codes** 505 506For details about the error codes, see [Media Error Codes](errorcode-media.md). 507 508| ID| Error Message | 509| -------- | ----------------------------------------- | 510| 201 | Permission denied. Return by promise. | 511| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 512| 5400102 | Operation not allowed. Return by promise. | 513| 5400105 | Service died. Return by promise. | 514 515**Example** 516 517```ts 518import { BusinessError } from '@kit.BasicServicesKit'; 519 520// Configure the parameters based on those supported by the hardware device. 521let videoProfile: media.VideoRecorderProfile = { 522 audioBitrate : 48000, 523 audioChannels : 2, 524 audioCodec : media.CodecMimeType.AUDIO_AAC, 525 audioSampleRate : 48000, 526 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 527 videoBitrate : 2000000, 528 videoCodec : media.CodecMimeType.VIDEO_AVC, 529 videoFrameWidth : 640, 530 videoFrameHeight : 480, 531 videoFrameRate : 30 532} 533 534let videoConfig: media.VideoRecorderConfig = { 535 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 536 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 537 profile : videoProfile, 538 url : 'fd://xx', // The file must be created by the caller and granted with proper permissions. 539 rotation : 0, 540 location : { latitude : 30, longitude : 130 } 541} 542 543// promise. 544videoRecorder.prepare(videoConfig).then(() => { 545 console.info('prepare success'); 546}).catch((err: BusinessError) => { 547 console.error('prepare failed and catch error is ' + err.message); 548}); 549``` 550 551### getInputSurface<sup>9+</sup> 552 553getInputSurface(callback: AsyncCallback\<string>): void 554 555Obtains the surface required for recording. This API uses an asynchronous callback to return the result. The caller obtains the **surfaceBuffer** from this surface and fills in the corresponding data. 556 557Note that the video data must carry the timestamp (in ns) and buffer size, and the start time of the timestamp must be based on the system startup time. 558 559This API can be called only after [prepare()](#prepare9) is called. 560 561**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 562 563**System API**: This is a system API. 564 565**Parameters** 566 567| Name | Type | Mandatory| Description | 568| -------- | ---------------------- | ---- | --------------------------- | 569| callback | AsyncCallback\<string> | Yes | Callback used to return the result.| 570 571**Error codes** 572 573For details about the error codes, see [Media Error Codes](errorcode-media.md). 574 575| ID| Error Message | 576| -------- | ------------------------------------------ | 577| 5400102 | Operation not allowed. Return by callback. | 578| 5400103 | I/O error. Return by callback. | 579| 5400105 | Service died. Return by callback. | 580 581**Example** 582 583```ts 584import { BusinessError } from '@kit.BasicServicesKit'; 585 586// asyncallback. 587let surfaceID: string; // Surface ID passed to the external system. 588videoRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 589 if (err == null) { 590 console.info('getInputSurface success'); 591 surfaceID = surfaceId; 592 } else { 593 console.error('getInputSurface failed and error is ' + err.message); 594 } 595}); 596``` 597 598### getInputSurface<sup>9+</sup> 599 600getInputSurface(): Promise\<string>; 601 602 Obtains the surface required for recording. This API uses a promise to return the result. The caller obtains the **surfaceBuffer** from this surface and fills in the corresponding data. 603 604Note that the video data must carry the timestamp (in ns) and buffer size, and the start time of the timestamp must be based on the system startup time. 605 606This API can be called only after [prepare()](#prepare9-1) is called. 607 608**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 609 610**System API**: This is a system API. 611 612**Return value** 613 614| Type | Description | 615| ---------------- | -------------------------------- | 616| Promise\<string> | Promise used to return the result.| 617 618**Error codes** 619 620For details about the error codes, see [Media Error Codes](errorcode-media.md). 621 622| ID| Error Message | 623| -------- | ----------------------------------------- | 624| 5400102 | Operation not allowed. Return by promise. | 625| 5400103 | I/O error. Return by promise. | 626| 5400105 | Service died. Return by promise. | 627 628**Example** 629 630```ts 631import { BusinessError } from '@kit.BasicServicesKit'; 632 633// promise. 634let surfaceID: string; // Surface ID passed to the external system. 635videoRecorder.getInputSurface().then((surfaceId: string) => { 636 console.info('getInputSurface success'); 637 surfaceID = surfaceId; 638}).catch((err: BusinessError) => { 639 console.error('getInputSurface failed and catch error is ' + err.message); 640}); 641``` 642 643### start<sup>9+</sup> 644 645start(callback: AsyncCallback\<void>): void 646 647Starts recording. This API uses an asynchronous callback to return the result. 648 649This API can be called only after [prepare()](#prepare9) and [getInputSurface()](#getinputsurface9) are called, because the data source must pass data to the surface first. 650 651**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 652 653**System API**: This is a system API. 654 655**Parameters** 656 657| Name | Type | Mandatory| Description | 658| -------- | -------------------- | ---- | ---------------------------- | 659| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 660 661**Error codes** 662 663For details about the error codes, see [Media Error Codes](errorcode-media.md). 664 665| ID| Error Message | 666| -------- | ------------------------------------------ | 667| 5400102 | Operation not allowed. Return by callback. | 668| 5400103 | I/O error. Return by callback. | 669| 5400105 | Service died. Return by callback. | 670 671**Example** 672 673```ts 674import { BusinessError } from '@kit.BasicServicesKit'; 675 676// asyncallback. 677videoRecorder.start((err: BusinessError) => { 678 if (err == null) { 679 console.info('start videorecorder success'); 680 } else { 681 console.error('start videorecorder failed and error is ' + err.message); 682 } 683}); 684``` 685 686### start<sup>9+</sup> 687 688start(): Promise\<void> 689 690Starts recording. This API uses a promise to return the result. 691 692This API can be called only after [prepare()](#prepare9-1) and [getInputSurface()](#getinputsurface9-1) are called, because the data source must pass data to the surface first. 693 694**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 695 696**System API**: This is a system API. 697 698**Return value** 699 700| Type | Description | 701| -------------- | ------------------------------------- | 702| Promise\<void> | Promise used to return the result.| 703 704**Error codes** 705 706For details about the error codes, see [Media Error Codes](errorcode-media.md). 707 708| ID| Error Message | 709| -------- | ----------------------------------------- | 710| 5400102 | Operation not allowed. Return by promise. | 711| 5400103 | I/O error. Return by promise. | 712| 5400105 | Service died. Return by promise. | 713 714**Example** 715 716```ts 717import { BusinessError } from '@kit.BasicServicesKit'; 718 719// promise. 720videoRecorder.start().then(() => { 721 console.info('start videorecorder success'); 722}).catch((err: BusinessError) => { 723 console.error('start videorecorder failed and catch error is ' + err.message); 724}); 725``` 726 727### pause<sup>9+</sup> 728 729pause(callback: AsyncCallback\<void>): void 730 731Pauses recording. This API uses an asynchronous callback to return the result. 732 733This API can be called only after [start()](#start9) is called. You can resume recording by calling [resume()](#resume9). 734 735**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 736 737**System API**: This is a system API. 738 739**Parameters** 740 741| Name | Type | Mandatory| Description | 742| -------- | -------------------- | ---- | ---------------------------- | 743| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 744 745**Error codes** 746 747For details about the error codes, see [Media Error Codes](errorcode-media.md). 748 749| ID| Error Message | 750| -------- | ------------------------------------------ | 751| 5400102 | Operation not allowed. Return by callback. | 752| 5400103 | I/O error. Return by callback. | 753| 5400105 | Service died. Return by callback. | 754 755**Example** 756 757```ts 758import { BusinessError } from '@kit.BasicServicesKit'; 759 760// asyncallback. 761videoRecorder.pause((err: BusinessError) => { 762 if (err == null) { 763 console.info('pause videorecorder success'); 764 } else { 765 console.error('pause videorecorder failed and error is ' + err.message); 766 } 767}); 768``` 769 770### pause<sup>9+</sup> 771 772pause(): Promise\<void> 773 774Pauses recording. This API uses a promise to return the result. 775 776This API can be called only after [start()](#start9-1) is called. You can resume recording by calling [resume()](#resume9-1). 777 778**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 779 780**System API**: This is a system API. 781 782**Return value** 783 784| Type | Description | 785| -------------- | ------------------------------------- | 786| Promise\<void> | Promise used to return the result.| 787 788**Error codes** 789 790For details about the error codes, see [Media Error Codes](errorcode-media.md). 791 792| ID| Error Message | 793| -------- | ----------------------------------------- | 794| 5400102 | Operation not allowed. Return by promise. | 795| 5400103 | I/O error. Return by promise. | 796| 5400105 | Service died. Return by promise. | 797 798**Example** 799 800```ts 801import { BusinessError } from '@kit.BasicServicesKit'; 802 803// promise. 804videoRecorder.pause().then(() => { 805 console.info('pause videorecorder success'); 806}).catch((err: BusinessError) => { 807 console.error('pause videorecorder failed and catch error is ' + err.message); 808}); 809``` 810 811### resume<sup>9+</sup> 812 813resume(callback: AsyncCallback\<void>): void 814 815Resumes recording. This API uses an asynchronous callback to return the result. 816 817**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 818 819**System API**: This is a system API. 820 821**Parameters** 822 823| Name | Type | Mandatory| Description | 824| -------- | -------------------- | ---- | ---------------------------- | 825| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 826 827**Error codes** 828 829For details about the error codes, see [Media Error Codes](errorcode-media.md). 830 831| ID| Error Message | 832| -------- | ------------------------------------------ | 833| 5400102 | Operation not allowed. Return by callback. | 834| 5400103 | I/O error. Return by callback. | 835| 5400105 | Service died. Return by callback. | 836 837**Example** 838 839```ts 840import { BusinessError } from '@kit.BasicServicesKit'; 841 842// asyncallback. 843videoRecorder.resume((err: BusinessError) => { 844 if (err == null) { 845 console.info('resume videorecorder success'); 846 } else { 847 console.error('resume videorecorder failed and error is ' + err.message); 848 } 849}); 850``` 851 852### resume<sup>9+</sup> 853 854resume(): Promise\<void> 855 856Resumes recording. This API uses a promise to return the result. 857 858**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 859 860**System API**: This is a system API. 861 862**Return value** 863 864| Type | Description | 865| -------------- | ------------------------------------- | 866| Promise\<void> | Promise used to return the result.| 867 868**Error codes** 869 870For details about the error codes, see [Media Error Codes](errorcode-media.md). 871 872| ID| Error Message | 873| -------- | ----------------------------------------- | 874| 5400102 | Operation not allowed. Return by promise. | 875| 5400103 | I/O error. Return by promise. | 876| 5400105 | Service died. Return by promise. | 877 878**Example** 879 880```ts 881import { BusinessError } from '@kit.BasicServicesKit'; 882 883// promise. 884videoRecorder.resume().then(() => { 885 console.info('resume videorecorder success'); 886}).catch((err: BusinessError) => { 887 console.error('resume videorecorder failed and catch error is ' + err.message); 888}); 889``` 890 891### stop<sup>9+</sup> 892 893stop(callback: AsyncCallback\<void>): void 894 895Stops recording. This API uses an asynchronous callback to return the result. 896 897To start another recording, you must call [prepare()](#prepare9) and [getInputSurface()](#getinputsurface9) again. 898 899**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 900 901**System API**: This is a system API. 902 903**Parameters** 904 905| Name | Type | Mandatory| Description | 906| -------- | -------------------- | ---- | ---------------------------- | 907| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 908 909**Error codes** 910 911For details about the error codes, see [Media Error Codes](errorcode-media.md). 912 913| ID| Error Message | 914| -------- | ------------------------------------------ | 915| 5400102 | Operation not allowed. Return by callback. | 916| 5400103 | I/O error. Return by callback. | 917| 5400105 | Service died. Return by callback. | 918 919**Example** 920 921```ts 922import { BusinessError } from '@kit.BasicServicesKit'; 923 924// asyncallback. 925videoRecorder.stop((err: BusinessError) => { 926 if (err == null) { 927 console.info('stop videorecorder success'); 928 } else { 929 console.error('stop videorecorder failed and error is ' + err.message); 930 } 931}); 932``` 933 934### stop<sup>9+</sup> 935 936stop(): Promise\<void> 937 938Stops recording. This API uses a promise to return the result. 939 940To start another recording, you must call [prepare()](#prepare9-1) and [getInputSurface()](#getinputsurface9-1) again. 941 942**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 943 944**System API**: This is a system API. 945 946**Return value** 947 948| Type | Description | 949| -------------- | ------------------------------------- | 950| Promise\<void> | Promise used to return the result.| 951 952**Error codes** 953 954For details about the error codes, see [Media Error Codes](errorcode-media.md). 955 956| ID| Error Message | 957| -------- | ----------------------------------------- | 958| 5400102 | Operation not allowed. Return by promise. | 959| 5400103 | I/O error. Return by promise. | 960| 5400105 | Service died. Return by promise. | 961 962**Example** 963 964```ts 965import { BusinessError } from '@kit.BasicServicesKit'; 966 967// promise. 968videoRecorder.stop().then(() => { 969 console.info('stop videorecorder success'); 970}).catch((err: BusinessError) => { 971 console.error('stop videorecorder failed and catch error is ' + err.message); 972}); 973``` 974 975### release<sup>9+</sup> 976 977release(callback: AsyncCallback\<void>): void 978 979Releases the video recording resources. This API uses an asynchronous callback to return the result. 980 981**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 982 983**System API**: This is a system API. 984 985**Parameters** 986 987| Name | Type | Mandatory| Description | 988| -------- | -------------------- | ---- | -------------------------------- | 989| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 990 991**Error codes** 992 993For details about the error codes, see [Media Error Codes](errorcode-media.md). 994 995| ID| Error Message | 996| -------- | --------------------------------- | 997| 5400105 | Service died. Return by callback. | 998 999**Example** 1000 1001```ts 1002import { BusinessError } from '@kit.BasicServicesKit'; 1003 1004// asyncallback. 1005videoRecorder.release((err: BusinessError) => { 1006 if (err == null) { 1007 console.info('release videorecorder success'); 1008 } else { 1009 console.error('release videorecorder failed and error is ' + err.message); 1010 } 1011}); 1012``` 1013 1014### release<sup>9+</sup> 1015 1016release(): Promise\<void> 1017 1018Releases the video recording resources. This API uses a promise to return the result. 1019 1020**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1021 1022**System API**: This is a system API. 1023 1024**Return value** 1025 1026| Type | Description | 1027| -------------- | ----------------------------------------- | 1028| Promise\<void> | Promise used to return the result.| 1029 1030**Error codes** 1031 1032For details about the error codes, see [Media Error Codes](errorcode-media.md). 1033 1034| ID| Error Message | 1035| -------- | --------------------------------- | 1036| 5400105 | Service died. Return by callback. | 1037 1038**Example** 1039 1040```ts 1041import { BusinessError } from '@kit.BasicServicesKit'; 1042 1043// promise. 1044videoRecorder.release().then(() => { 1045 console.info('release videorecorder success'); 1046}).catch((err: BusinessError) => { 1047 console.error('release videorecorder failed and catch error is ' + err.message); 1048}); 1049``` 1050 1051### reset<sup>9+</sup> 1052 1053reset(callback: AsyncCallback\<void>): void 1054 1055Resets video recording. This API uses an asynchronous callback to return the result. 1056 1057To start another recording, you must call [prepare()](#prepare9) and [getInputSurface()](#getinputsurface9) again. 1058 1059**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1060 1061**System API**: This is a system API. 1062 1063**Parameters** 1064 1065| Name | Type | Mandatory| Description | 1066| -------- | -------------------- | ---- | ---------------------------- | 1067| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 1068 1069**Error codes** 1070 1071For details about the error codes, see [Media Error Codes](errorcode-media.md). 1072 1073| ID| Error Message | 1074| -------- | --------------------------------- | 1075| 5400103 | I/O error. Return by callback. | 1076| 5400105 | Service died. Return by callback. | 1077 1078**Example** 1079 1080```ts 1081import { BusinessError } from '@kit.BasicServicesKit'; 1082 1083// asyncallback. 1084videoRecorder.reset((err: BusinessError) => { 1085 if (err == null) { 1086 console.info('reset videorecorder success'); 1087 } else { 1088 console.error('reset videorecorder failed and error is ' + err.message); 1089 } 1090}); 1091``` 1092 1093### reset<sup>9+</sup> 1094 1095reset(): Promise\<void> 1096 1097Resets video recording. This API uses a promise to return the result. 1098 1099To start another recording, you must call [prepare()](#prepare9-1) and [getInputSurface()](#getinputsurface9-1) again. 1100 1101**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1102 1103**System API**: This is a system API. 1104 1105**Return value** 1106 1107| Type | Description | 1108| -------------- | ------------------------------------- | 1109| Promise\<void> | Promise used to return the result.| 1110 1111**Error codes** 1112 1113For details about the error codes, see [Media Error Codes](errorcode-media.md). 1114 1115| ID| Error Message | 1116| -------- | -------------------------------- | 1117| 5400103 | I/O error. Return by promise. | 1118| 5400105 | Service died. Return by promise. | 1119 1120**Example** 1121 1122```ts 1123import { BusinessError } from '@kit.BasicServicesKit'; 1124 1125// promise. 1126videoRecorder.reset().then(() => { 1127 console.info('reset videorecorder success'); 1128}).catch((err: BusinessError) => { 1129 console.error('reset videorecorder failed and catch error is ' + err.message); 1130}); 1131``` 1132 1133### on('error')<sup>9+</sup> 1134 1135on(type: 'error', callback: ErrorCallback): void 1136 1137Subscribes to video recording error events. After an error event is reported, you must handle the event and exit the recording. 1138 1139**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1140 1141**System API**: This is a system API. 1142 1143**Parameters** 1144 1145| Name | Type | Mandatory| Description | 1146| -------- | ------------- | ---- | ------------------------------------------------------------ | 1147| type | string | Yes | Event type, which is **'error'** in this case.<br>This event is triggered when an error occurs during video recording.| 1148| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | Yes | Callback invoked when the event is triggered. | 1149 1150**Error codes** 1151 1152For details about the error codes, see [Media Error Codes](errorcode-media.md). 1153 1154| ID| Error Message | 1155| -------- | --------------------------------- | 1156| 5400103 | I/O error. Return by callback. | 1157| 5400105 | Service died. Return by callback. | 1158 1159**Example** 1160 1161```ts 1162import { BusinessError } from '@kit.BasicServicesKit'; 1163 1164// This event is reported when an error occurs during the retrieval of videoRecordState. 1165videoRecorder.on('error', (error: BusinessError) => { // Set the 'error' event callback. 1166 console.error(`audio error called, error: ${error}`); 1167}) 1168``` 1169 1170## VideoRecordState<sup>9+</sup> 1171 1172Enumerates the video recording states. You can obtain the state through the **state** attribute. 1173 1174**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1175 1176**System API**: This is a system API. 1177 1178| Name | Type | Description | 1179| -------- | ------ | ---------------------- | 1180| idle | string | The video recorder is idle. | 1181| prepared | string | The video recording parameters are set.| 1182| playing | string | Video recording is in progress. | 1183| paused | string | Video recording is paused. | 1184| stopped | string | Video recording is stopped. | 1185| error | string | Video recording is in the error state. | 1186 1187## VideoRecorderConfig<sup>9+</sup> 1188 1189Describes the video recording parameters. 1190 1191The **audioSourceType** and **videoSourceType** parameters are used to distinguish video-only recording from audio and video recording. (For audio-only recording, use [AVRecorder](js-apis-media.md#avrecorder9) or [AudioRecorder](js-apis-media.md#audiorecorderdeprecated).) For video-only recording, set only **videoSourceType**. For audio and video recording, set both **audioSourceType** and **videoSourceType**. 1192 1193**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1194 1195**System API**: This is a system API. 1196 1197| Name | Type | Mandatory| Description | 1198| --------------- | ---------------------------------------------- | ---- | ------------------------------------------------------------ | 1199| audioSourceType | [AudioSourceType](js-apis-media.md#audiosourcetype9) | No | Type of the audio source for video recording. This parameter is mandatory for audio recording. | 1200| videoSourceType | [VideoSourceType](js-apis-media.md#videosourcetype9) | Yes | Type of the video source for video recording. | 1201| profile | [VideoRecorderProfile](#videorecorderprofile9) | Yes | Video recording profile. | 1202| rotation | number | No | Rotation angle of the recorded video. The value can only be 0 (default), 90, 180, or 270. | 1203| location | [Location](js-apis-media.md#location) | No | Geographical location of the recorded video. By default, the geographical location information is not recorded. | 1204| url | string | Yes | Video output URL. Supported: fd://xx (fd number)<br> | 1205 1206## VideoRecorderProfile<sup>9+</sup> 1207 1208Describes the video recording profile. 1209 1210**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1211 1212**System API**: This is a system API. 1213 1214| Name | Type | Mandatory| Description | 1215| ---------------- | -------------------------------------------- | ---- | ---------------- | 1216| audioBitrate | number | No | Audio encoding bit rate. This parameter is mandatory for audio recording.| 1217| audioChannels | number | No | Number of audio channels. This parameter is mandatory for audio recording.| 1218| audioCodec | [CodecMimeType](js-apis-media.md#codecmimetype8) | No | Audio encoding format. This parameter is mandatory for audio recording. | 1219| audioSampleRate | number | No | Audio sampling rate. This parameter is mandatory for audio recording. | 1220| fileFormat | [ContainerFormatType](js-apis-media.md#containerformattype8) | Yes | Container format of a file.| 1221| videoBitrate | number | Yes | Video encoding bit rate.| 1222| videoCodec | [CodecMimeType](js-apis-media.md#codecmimetype8) | Yes | Video encoding format. | 1223| videoFrameWidth | number | Yes | Width of the recorded video frame.| 1224| videoFrameHeight | number | Yes | Height of the recorded video frame.| 1225| videoFrameRate | number | Yes | Video frame rate. | 1226 1227## WatermarkConfig<sup>13+</sup> 1228 1229Describes the watermark configuration set for the AVRecorder. The start point is the upper left corner of the image. 1230 1231**System capability**: SystemCapability.Multimedia.Media.Core 1232 1233**System API**: This is a system API. 1234 1235| Name | Type | Mandatory| Description | 1236| --------- | ------ | ---- | ---------------- | 1237| top | number | Yes | Pixel offset from the top edge of the image.| 1238| left | number | Yes | Pixel offset from the left edge of the image.| 1239 1240## ScreenCaptureMonitor<sup>18+</sup> 1241 1242A class that provides APIs to query and monitor the system screen recorder status. Before calling any API, you must use [getScreenCaptureMonitor()](#mediagetscreencapturemonitor18) to obtain a [ScreenCaptureMonitor](#screencapturemonitor18) instance. 1243 1244### Properties 1245 1246**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 1247 1248**System API**: This is a system API. 1249 1250| Name | Type | Readable| Writable| Description | 1251| ------------------ | -------------------------------------- | ---- | ---- | ---------------- | 1252| isSystemScreenRecorderWorking<sup>18+</sup> | bool | Yes | No | Whether the system screen recorder is working.| 1253 1254### on('systemScreenRecorder')<sup>18+</sup> 1255 1256on(type: 'systemScreenRecorder', callback: Callback\<ScreenCaptureEvent>): void 1257 1258Subscribes to state change events of the system screen recorder. From the ScreenCaptureEvent event reported, you can determine whether the system screen recorder is working. 1259 1260**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 1261 1262**System API**: This is a system API. 1263 1264**Parameters** 1265 1266| Name | Type | Mandatory| Description | 1267| -------- | ------------- | ---- | ------------------------------------------------------------ | 1268| type | string | Yes | Event type, which is **'systemScreenRecorder'** in this case.<br>This event is triggered when the state of the system screen recorder changes.| 1269| callback | function | Yes | Callback invoked when the event is triggered, where [ScreenCaptureEvent](#screencaptureevent18) indicates the new state. | 1270 1271**Error codes** 1272 1273For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1274 1275| ID| Error Message | 1276| -------- | --------------------------------- | 1277| 202 | Not System App. | 1278 1279**Example** 1280 1281```ts 1282 1283// This event is reported when the state of the system screen recorder changes. 1284screenCaptureMonitor.on('systemScreenRecorder', (event: media.ScreenCaptureEvent) => { 1285 // Set the 'systemScreenRecorder' event callback. 1286 console.info(`system ScreenRecorder event: ${event}`); 1287}) 1288``` 1289 1290### off('systemScreenRecorder')<sup>18+</sup> 1291 1292off(type: 'systemScreenRecorder', callback?: Callback\<ScreenCaptureEvent>): void 1293 1294Unsubscribes from state change events of the system screen recorder. 1295 1296**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 1297 1298**System API**: This is a system API. 1299 1300**Parameters** 1301 1302| Name | Type | Mandatory| Description | 1303| -------- | ------------- | ---- | ------------------------------------------------------------ | 1304| type | string | Yes | Event type, which is **'systemScreenRecorder'** in this case.<br>This event is triggered when the state of the system screen recorder changes.| 1305| callback | function | No | Callback invoked when the event is triggered, where [ScreenCaptureEvent](#screencaptureevent18) indicates the new state. If this parameter is not specified, the last subscription event is canceled.| 1306 1307**Error codes** 1308 1309For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1310 1311| ID| Error Message | 1312| -------- | --------------------------------- | 1313| 202 | Not System App. | 1314 1315**Example** 1316 1317```ts 1318screenCaptureMonitor.off('systemScreenRecorder'); 1319``` 1320 1321## ScreenCaptureEvent<sup>18+</sup> 1322 1323Enumerates the states available for the system screen recorder. 1324 1325**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 1326 1327**System API**: This is a system API. 1328 1329| Name | Value | Description | 1330| ------------------------ | --------------- | ------------------------------------------------------------ | 1331| SCREENCAPTURE_STARTED | 0 | The system screen recorder starts screen capture. | 1332| SCREENCAPTURE_STOPPED | 1 | The system screen recorder stops screen capture.| 1333
