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## PixelMapParams<sup>11+</sup> 154 155Defines the format parameters of the video thumbnail to be obtained. 156 157**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 158 159| Name | Type | Readable | Writable | Description | 160| -------- | ------ | ------| ------ | ---------------------- | 161| colorFormat | [PixelFormat](#pixelformat11) | Yes | Yes | Color format of the thumbnail.<br>**System API**: This is a system API. | 162 163## PixelFormat<sup>11+</sup> 164 165Enumerates the color formats supported by the video thumbnail. 166 167**System capability**: SystemCapability.Multimedia.Media.AVImageGenerator 168 169**System API**: This is a system API. 170 171| Name | Value | Description | 172| ------------------------ | --------------- | ------------------------------------------------------------ | 173| RGB_565 | 2 | RGB_565. | 174| RGBA_8888 | 3 | RGBA_8888.| 175| RGB_888 | 5 | RGB_888. | 176 177## AvPlayer<sup>9+</sup> 178 179A playback management class that provides APIs to manage and play media assets. Before calling any API in **AVPlayer**, you must use [createAVPlayer()](js-apis-media.md#mediacreateavplayer9) to create an [AVPlayer](js-apis-media.md#avplayer9) instance. 180 181### setPlaybackRange<sup>12+</sup> 182 183setPlaybackRange(startTimeMs: number, endTimeMs: number, mode?: SeekMode) : Promise\<void> 184 185Sets the playback range and seeks to the start position of the range based on the specified [SeekMode](js-apis-media.md#seekmode8). After the setting, only the content in the specified range of the audio or video file is played. This API uses a promise to return the result. It can be used when the AVPlayer is in the initialized, prepared, paused, stopped, or completed state. 186 187**System capability**: SystemCapability.Multimedia.Media.AvPlayer 188 189**System API**: This is a system API. 190 191**Parameters** 192 193| Name | Type | Mandatory| Description | 194| -------- | ---------------------- | ---- | --------------------------- | 195| startTimeMs | number | Yes | Start position of the range, in ms. The value range is [0, duration). If **-1** is passed in, the system starts playing from position 0.| 196| endTimeMs | number | Yes | End position of the range, in ms. The value range is (startTimeMs, duration]. If **-1** is passed in, the system plays the content until it reaches the final part of the asset.| 197| mode | [SeekMode](js-apis-media.md#seekmode8) | No | Seek mode, which can be **SeekMode.SEEK_PREV_SYNC** or **SeekMode.SEEK_CLOSEST**.<br>The default value is **SeekMode.SEEK_PREV_SYNC**.| 198 199**Error codes** 200 201For details about the error codes, see [Media Error Codes](errorcode-media.md). 202 203| ID| Error Message | 204| -------- | ------------------------------------------ | 205| 202 | Called from Non-System applications. Return by promise. | 206| 401 | The parameter check failed. Return by promise. | 207| 5400102 | Operation not allowed. Return by promise. | 208 209**Example** 210 211```ts 212import { media } from '@kit.MediaKit'; 213import { BusinessError } from '@kit.BasicServicesKit'; 214 215avPlayer.setPlaybackRange(0, 6000, media.SeekMode.SEEK_CLOSEST).then(() => { 216 console.info('Succeeded setPlaybackRange'); 217}).catch((err: BusinessError) => { 218 console.error('Failed to setPlaybackRange' + err.message); 219}); 220``` 221 222## AVMetadataExtractor<sup>11+</sup> 223 224Provides 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. 225 226### getTimeByFrameIndex<sup>12+</sup> 227 228getTimeByFrameIndex(index: number): Promise\<number> 229 230Obtains the video timestamp corresponding to a video frame number. Only MP4 video files are supported. 231 232**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 233 234**System API**: This is a system API. 235 236**Parameters** 237 238| Name| Type | Mandatory| Description | 239| ------ | ------ | ---- | ---------- | 240| index | number | Yes | Video frame number.| 241 242**Return value** 243 244| Type | Description | 245| ---------------- | ----------------------------------- | 246| Promise\<number> | Promise used to return the timestamp, in microseconds.| 247 248**Error codes** 249 250For details about the error codes, see [Media Error Codes](errorcode-media.md). 251 252| ID| Error Message | 253| -------- | ---------------------------------------------- | 254| 401 | The parameter check failed. Return by promise. | 255| 5400102 | Operation not allowed. Returned by promise. | 256| 5400106 | Unsupported format. Returned by promise. | 257 258**Example** 259 260```ts 261import { media } from '@kit.MediaKit'; 262import { BusinessError } from '@kit.BasicServicesKit'; 263 264avMetadataExtractor.getTimeByFrameIndex(0).then((timeUs: number) => { 265 console.info(`Succeeded getTimeByFrameIndex timeUs: ${timeUs}`); 266}).catch((err: BusinessError) => { 267 console.error(`Failed to getTimeByFrameIndex ${err.message}`); 268}) 269``` 270 271### getFrameIndexByTime<sup>12+</sup> 272 273getFrameIndexByTime(timeUs: number): Promise\<number> 274 275Obtains the video frame number corresponding to a video timestamp. Only MP4 video files are supported. 276 277**System capability**: SystemCapability.Multimedia.Media.AVMetadataExtractor 278 279**System API**: This is a system API. 280 281**Parameters** 282 283| Name| Type | Mandatory| Description | 284| ------ | ------ | ---- | ------------------------ | 285| timeUs | number | Yes | Video timestamp, in microseconds.| 286 287**Return value** 288 289| Type | Description | 290| ---------------- | ------------------------- | 291| Promise\<number> | Promise used to return the video frame number.| 292 293**Error codes** 294 295For details about the error codes, see [Media Error Codes](errorcode-media.md). 296 297| ID| Error Message | 298| -------- | ---------------------------------------------- | 299| 401 | The parameter check failed. Return by promise. | 300| 5400102 | Operation not allowed. Returned by promise. | 301| 5400106 | Unsupported format. Returned by promise. | 302 303**Example** 304 305```ts 306import { media } from '@kit.MediaKit'; 307import { BusinessError } from '@kit.BasicServicesKit'; 308 309avMetadataExtractor.getFrameIndexByTime(0).then((index: number) => { 310 console.info(`Succeeded getFrameIndexByTime index: ${index}`); 311}).catch((err: BusinessError) => { 312 console.error(`Failed to getFrameIndexByTime ${err.message}`); 313}) 314``` 315 316## AVRecorder<sup>9+</sup> 317 318A 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. 319 320> **NOTE** 321> 322> 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). 323 324### isWatermarkSupported<sup>12+</sup> 325 326isWatermarkSupported(): Promise\<boolean> 327 328Checks whether the device supports the hardware digital watermark. This API uses a promise to return the result. 329 330This 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. 331 332**System capability**: SystemCapability.Multimedia.Media.AVRecorder 333 334**System API**: This is a system API. 335 336**Return value** 337 338| Type | Description | 339| ---------------- | -------------------------------- | 340| Promise\<boolean> | Promise used to return the check result.| 341 342**Example** 343 344```ts 345import { BusinessError } from '@kit.BasicServicesKit'; 346 347avRecorder.isWatermarkSupported().then((isWatermarkSupported: boolean) => { 348 console.info(`Succeeded in get, isWatermarkSupported: ${isWatermarkSupported}`); 349}).catch((error: BusinessError) => { 350 console.error(`Failed to get and catch error is ${error.message}`); 351}); 352``` 353 354### setWatermark<sup>12+</sup> 355 356setWatermark(watermark: image.PixelMap, config: WatermarkConfig): Promise\<void> 357 358Sets a watermark for the AVRecorder. This API uses a promise to return the result. 359 360This 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. 361 362**System capability**: SystemCapability.Multimedia.Media.AVRecorder 363 364**System API**: This is a system API. 365 366**Parameters** 367 368| Name | Type | Mandatory| Description | 369| -------- | -------------------- | ---- | --------------------------- | 370| 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 8 KB, the watermark resolution is 3072 x 288; if the original image is 4 KB, the watermark resolution is 1536 x 144.| 371| config | [WatermarkConfig](#watermarkconfig12) | Yes | Watermark configuration.| 372 373**Return value** 374 375| Type | Description | 376| ---------------- | -------------------------------- | 377| Promise\<void> | Promise that returns no value.| 378 379**Error codes** 380 381For details about the error codes, see [Media Error Codes](errorcode-media.md). 382 383| ID| Error Message | 384| -------- | -------------------------------------- | 385| 401 | The parameter check failed. Return by promise. | 386| 801 | Capability not supported. Return by promise. | 387 388**Example** 389 390```ts 391import { BusinessError } from '@kit.BasicServicesKit'; 392import { image } from '@kit.ImageKit'; 393 394let watermark: image.PixelMap|undefined = undefined; // need data 395let watermarkConfig: media.WatermarkConfig = { top: 100, left: 100 } 396 397avRecorder.setWatermark(watermark, watermarkConfig).then(() => { 398 console.info('Succeeded in setWatermark'); 399}).catch((error: BusinessError) => { 400 console.error(`Failed to setWatermark and catch error is ${error.message}`); 401}); 402``` 403 404## VideoRecorder<sup>9+</sup> 405 406> **NOTE** 407> This class is deprecated after AVRecorder<sup>9+</sup> is released. You are advised to use [AVRecorder](js-apis-media.md#avrecorder9) instead. 408 409Implements video recording. Before calling any API in the **VideoRecorder** class, you must use [createVideoRecorder()](#mediacreatevideorecorder9) to create a [VideoRecorder](#videorecorder9) instance. 410 411### Attributes 412 413**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 414 415**System API**: This is a system API. 416 417| Name | Type | Readable| Writable| Description | 418| ------------------ | -------------------------------------- | ---- | ---- | ---------------- | 419| state<sup>9+</sup> | [VideoRecordState](#videorecordstate9) | Yes | No | Video recording state.| 420 421### prepare<sup>9+</sup> 422 423prepare(config: VideoRecorderConfig, callback: AsyncCallback\<void>): void 424 425Sets video recording parameters. This API uses an asynchronous callback to return the result. 426 427**Required permissions:** ohos.permission.MICROPHONE 428 429**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 430 431**System API**: This is a system API. 432 433**Parameters** 434 435| Name | Type | Mandatory| Description | 436| -------- | -------------------------------------------- | ---- | ----------------------------------- | 437| config | [VideoRecorderConfig](#videorecorderconfig9) | Yes | Video recording parameters to set. | 438| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 439 440**Error codes** 441 442For details about the error codes, see [Media Error Codes](errorcode-media.md). 443 444| ID| Error Message | 445| -------- | ------------------------------------------ | 446| 201 | Permission denied. Return by callback. | 447| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 448| 5400102 | Operation not allowed. Return by callback. | 449| 5400105 | Service died. Return by callback. | 450 451**Example** 452 453```ts 454import { BusinessError } from '@kit.BasicServicesKit'; 455 456// Configure the parameters based on those supported by the hardware device. 457let videoProfile: media.VideoRecorderProfile = { 458 audioBitrate : 48000, 459 audioChannels : 2, 460 audioCodec : media.CodecMimeType.AUDIO_AAC, 461 audioSampleRate : 48000, 462 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 463 videoBitrate : 2000000, 464 videoCodec : media.CodecMimeType.VIDEO_AVC, 465 videoFrameWidth : 640, 466 videoFrameHeight : 480, 467 videoFrameRate : 30 468} 469 470let videoConfig: media.VideoRecorderConfig = { 471 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 472 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 473 profile : videoProfile, 474 url : 'fd://xx', // The file must be created by the caller and granted with proper permissions. 475 rotation : 0, 476 location : { latitude : 30, longitude : 130 } 477} 478 479// asyncallback 480videoRecorder.prepare(videoConfig, (err: BusinessError) => { 481 if (err == null) { 482 console.info('prepare success'); 483 } else { 484 console.error('prepare failed and error is ' + err.message); 485 } 486}) 487``` 488 489### prepare<sup>9+</sup> 490 491prepare(config: VideoRecorderConfig): Promise\<void> 492 493Sets video recording parameters. This API uses a promise to return the result. 494 495**Required permissions:** ohos.permission.MICROPHONE 496 497**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 498 499**System API**: This is a system API. 500 501**Parameters** 502 503| Name| Type | Mandatory| Description | 504| ------ | -------------------------------------------- | ---- | ------------------------ | 505| config | [VideoRecorderConfig](#videorecorderconfig9) | Yes | Video recording parameters to set.| 506 507**Return value** 508 509| Type | Description | 510| -------------- | ---------------------------------------- | 511| Promise\<void> | Promise used to return the result.| 512 513**Error codes** 514 515For details about the error codes, see [Media Error Codes](errorcode-media.md). 516 517| ID| Error Message | 518| -------- | ----------------------------------------- | 519| 201 | Permission denied. Return by promise. | 520| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed. | 521| 5400102 | Operation not allowed. Return by promise. | 522| 5400105 | Service died. Return by promise. | 523 524**Example** 525 526```ts 527import { BusinessError } from '@kit.BasicServicesKit'; 528 529// Configure the parameters based on those supported by the hardware device. 530let videoProfile: media.VideoRecorderProfile = { 531 audioBitrate : 48000, 532 audioChannels : 2, 533 audioCodec : media.CodecMimeType.AUDIO_AAC, 534 audioSampleRate : 48000, 535 fileFormat : media.ContainerFormatType.CFT_MPEG_4, 536 videoBitrate : 2000000, 537 videoCodec : media.CodecMimeType.VIDEO_AVC, 538 videoFrameWidth : 640, 539 videoFrameHeight : 480, 540 videoFrameRate : 30 541} 542 543let videoConfig: media.VideoRecorderConfig = { 544 audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC, 545 videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV, 546 profile : videoProfile, 547 url : 'fd://xx', // The file must be created by the caller and granted with proper permissions. 548 rotation : 0, 549 location : { latitude : 30, longitude : 130 } 550} 551 552// promise 553videoRecorder.prepare(videoConfig).then(() => { 554 console.info('prepare success'); 555}).catch((err: BusinessError) => { 556 console.error('prepare failed and catch error is ' + err.message); 557}); 558``` 559 560### getInputSurface<sup>9+</sup> 561 562getInputSurface(callback: AsyncCallback\<string>): void 563 564Obtains 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. 565 566Note 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. 567 568This API can be called only after [prepare()](#prepare9) is called. 569 570**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 571 572**System API**: This is a system API. 573 574**Parameters** 575 576| Name | Type | Mandatory| Description | 577| -------- | ---------------------- | ---- | --------------------------- | 578| callback | AsyncCallback\<string> | Yes | Callback used to return the result.| 579 580**Error codes** 581 582For details about the error codes, see [Media Error Codes](errorcode-media.md). 583 584| ID| Error Message | 585| -------- | ------------------------------------------ | 586| 5400102 | Operation not allowed. Return by callback. | 587| 5400103 | I/O error. Return by callback. | 588| 5400105 | Service died. Return by callback. | 589 590**Example** 591 592```ts 593import { BusinessError } from '@kit.BasicServicesKit'; 594 595// asyncallback 596let surfaceID: string; // Surface ID passed to the external system. 597videoRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 598 if (err == null) { 599 console.info('getInputSurface success'); 600 surfaceID = surfaceId; 601 } else { 602 console.error('getInputSurface failed and error is ' + err.message); 603 } 604}); 605``` 606 607### getInputSurface<sup>9+</sup> 608 609getInputSurface(): Promise\<string>; 610 611 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. 612 613Note 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. 614 615This API can be called only after [prepare()](#prepare9-1) is called. 616 617**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 618 619**System API**: This is a system API. 620 621**Return value** 622 623| Type | Description | 624| ---------------- | -------------------------------- | 625| Promise\<string> | Promise used to return the result.| 626 627**Error codes** 628 629For details about the error codes, see [Media Error Codes](errorcode-media.md). 630 631| ID| Error Message | 632| -------- | ----------------------------------------- | 633| 5400102 | Operation not allowed. Return by promise. | 634| 5400103 | I/O error. Return by promise. | 635| 5400105 | Service died. Return by promise. | 636 637**Example** 638 639```ts 640import { BusinessError } from '@kit.BasicServicesKit'; 641 642// promise 643let surfaceID: string; // Surface ID passed to the external system. 644videoRecorder.getInputSurface().then((surfaceId: string) => { 645 console.info('getInputSurface success'); 646 surfaceID = surfaceId; 647}).catch((err: BusinessError) => { 648 console.error('getInputSurface failed and catch error is ' + err.message); 649}); 650``` 651 652### start<sup>9+</sup> 653 654start(callback: AsyncCallback\<void>): void 655 656Starts recording. This API uses an asynchronous callback to return the result. 657 658This API can be called only after [prepare()](#prepare9) and [getInputSurface()](#getinputsurface9) are called, because the data source must pass data to the surface first. 659 660**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 661 662**System API**: This is a system API. 663 664**Parameters** 665 666| Name | Type | Mandatory| Description | 667| -------- | -------------------- | ---- | ---------------------------- | 668| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 669 670**Error codes** 671 672For details about the error codes, see [Media Error Codes](errorcode-media.md). 673 674| ID| Error Message | 675| -------- | ------------------------------------------ | 676| 5400102 | Operation not allowed. Return by callback. | 677| 5400103 | I/O error. Return by callback. | 678| 5400105 | Service died. Return by callback. | 679 680**Example** 681 682```ts 683import { BusinessError } from '@kit.BasicServicesKit'; 684 685// asyncallback 686videoRecorder.start((err: BusinessError) => { 687 if (err == null) { 688 console.info('start videorecorder success'); 689 } else { 690 console.error('start videorecorder failed and error is ' + err.message); 691 } 692}); 693``` 694 695### start<sup>9+</sup> 696 697start(): Promise\<void> 698 699Starts recording. This API uses a promise to return the result. 700 701This 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. 702 703**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 704 705**System API**: This is a system API. 706 707**Return value** 708 709| Type | Description | 710| -------------- | ------------------------------------- | 711| Promise\<void> | Promise used to return the result.| 712 713**Error codes** 714 715For details about the error codes, see [Media Error Codes](errorcode-media.md). 716 717| ID| Error Message | 718| -------- | ----------------------------------------- | 719| 5400102 | Operation not allowed. Return by promise. | 720| 5400103 | I/O error. Return by promise. | 721| 5400105 | Service died. Return by promise. | 722 723**Example** 724 725```ts 726import { BusinessError } from '@kit.BasicServicesKit'; 727 728// promise 729videoRecorder.start().then(() => { 730 console.info('start videorecorder success'); 731}).catch((err: BusinessError) => { 732 console.error('start videorecorder failed and catch error is ' + err.message); 733}); 734``` 735 736### pause<sup>9+</sup> 737 738pause(callback: AsyncCallback\<void>): void 739 740Pauses recording. This API uses an asynchronous callback to return the result. 741 742This API can be called only after [start()](#start9) is called. You can resume recording by calling [resume()](#resume9). 743 744**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 745 746**System API**: This is a system API. 747 748**Parameters** 749 750| Name | Type | Mandatory| Description | 751| -------- | -------------------- | ---- | ---------------------------- | 752| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 753 754**Error codes** 755 756For details about the error codes, see [Media Error Codes](errorcode-media.md). 757 758| ID| Error Message | 759| -------- | ------------------------------------------ | 760| 5400102 | Operation not allowed. Return by callback. | 761| 5400103 | I/O error. Return by callback. | 762| 5400105 | Service died. Return by callback. | 763 764**Example** 765 766```ts 767import { BusinessError } from '@kit.BasicServicesKit'; 768 769// asyncallback 770videoRecorder.pause((err: BusinessError) => { 771 if (err == null) { 772 console.info('pause videorecorder success'); 773 } else { 774 console.error('pause videorecorder failed and error is ' + err.message); 775 } 776}); 777``` 778 779### pause<sup>9+</sup> 780 781pause(): Promise\<void> 782 783Pauses recording. This API uses a promise to return the result. 784 785This API can be called only after [start()](#start9-1) is called. You can resume recording by calling [resume()](#resume9-1). 786 787**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 788 789**System API**: This is a system API. 790 791**Return value** 792 793| Type | Description | 794| -------------- | ------------------------------------- | 795| Promise\<void> | Promise used to return the result.| 796 797**Error codes** 798 799For details about the error codes, see [Media Error Codes](errorcode-media.md). 800 801| ID| Error Message | 802| -------- | ----------------------------------------- | 803| 5400102 | Operation not allowed. Return by promise. | 804| 5400103 | I/O error. Return by promise. | 805| 5400105 | Service died. Return by promise. | 806 807**Example** 808 809```ts 810import { BusinessError } from '@kit.BasicServicesKit'; 811 812// promise 813videoRecorder.pause().then(() => { 814 console.info('pause videorecorder success'); 815}).catch((err: BusinessError) => { 816 console.error('pause videorecorder failed and catch error is ' + err.message); 817}); 818``` 819 820### resume<sup>9+</sup> 821 822resume(callback: AsyncCallback\<void>): void 823 824Resumes recording. This API uses an asynchronous callback to return the result. 825 826**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 827 828**System API**: This is a system API. 829 830**Parameters** 831 832| Name | Type | Mandatory| Description | 833| -------- | -------------------- | ---- | ---------------------------- | 834| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 835 836**Error codes** 837 838For details about the error codes, see [Media Error Codes](errorcode-media.md). 839 840| ID| Error Message | 841| -------- | ------------------------------------------ | 842| 5400102 | Operation not allowed. Return by callback. | 843| 5400103 | I/O error. Return by callback. | 844| 5400105 | Service died. Return by callback. | 845 846**Example** 847 848```ts 849import { BusinessError } from '@kit.BasicServicesKit'; 850 851// asyncallback 852videoRecorder.resume((err: BusinessError) => { 853 if (err == null) { 854 console.info('resume videorecorder success'); 855 } else { 856 console.error('resume videorecorder failed and error is ' + err.message); 857 } 858}); 859``` 860 861### resume<sup>9+</sup> 862 863resume(): Promise\<void> 864 865Resumes recording. This API uses a promise to return the result. 866 867**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 868 869**System API**: This is a system API. 870 871**Return value** 872 873| Type | Description | 874| -------------- | ------------------------------------- | 875| Promise\<void> | Promise used to return the result.| 876 877**Error codes** 878 879For details about the error codes, see [Media Error Codes](errorcode-media.md). 880 881| ID| Error Message | 882| -------- | ----------------------------------------- | 883| 5400102 | Operation not allowed. Return by promise. | 884| 5400103 | I/O error. Return by promise. | 885| 5400105 | Service died. Return by promise. | 886 887**Example** 888 889```ts 890import { BusinessError } from '@kit.BasicServicesKit'; 891 892// promise 893videoRecorder.resume().then(() => { 894 console.info('resume videorecorder success'); 895}).catch((err: BusinessError) => { 896 console.error('resume videorecorder failed and catch error is ' + err.message); 897}); 898``` 899 900### stop<sup>9+</sup> 901 902stop(callback: AsyncCallback\<void>): void 903 904Stops recording. This API uses an asynchronous callback to return the result. 905 906To start another recording, you must call [prepare()](#prepare9) and [getInputSurface()](#getinputsurface9) again. 907 908**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 909 910**System API**: This is a system API. 911 912**Parameters** 913 914| Name | Type | Mandatory| Description | 915| -------- | -------------------- | ---- | ---------------------------- | 916| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 917 918**Error codes** 919 920For details about the error codes, see [Media Error Codes](errorcode-media.md). 921 922| ID| Error Message | 923| -------- | ------------------------------------------ | 924| 5400102 | Operation not allowed. Return by callback. | 925| 5400103 | I/O error. Return by callback. | 926| 5400105 | Service died. Return by callback. | 927 928**Example** 929 930```ts 931import { BusinessError } from '@kit.BasicServicesKit'; 932 933// asyncallback 934videoRecorder.stop((err: BusinessError) => { 935 if (err == null) { 936 console.info('stop videorecorder success'); 937 } else { 938 console.error('stop videorecorder failed and error is ' + err.message); 939 } 940}); 941``` 942 943### stop<sup>9+</sup> 944 945stop(): Promise\<void> 946 947Stops recording. This API uses a promise to return the result. 948 949To start another recording, you must call [prepare()](#prepare9-1) and [getInputSurface()](#getinputsurface9-1) again. 950 951**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 952 953**System API**: This is a system API. 954 955**Return value** 956 957| Type | Description | 958| -------------- | ------------------------------------- | 959| Promise\<void> | Promise used to return the result.| 960 961**Error codes** 962 963For details about the error codes, see [Media Error Codes](errorcode-media.md). 964 965| ID| Error Message | 966| -------- | ----------------------------------------- | 967| 5400102 | Operation not allowed. Return by promise. | 968| 5400103 | I/O error. Return by promise. | 969| 5400105 | Service died. Return by promise. | 970 971**Example** 972 973```ts 974import { BusinessError } from '@kit.BasicServicesKit'; 975 976// promise 977videoRecorder.stop().then(() => { 978 console.info('stop videorecorder success'); 979}).catch((err: BusinessError) => { 980 console.error('stop videorecorder failed and catch error is ' + err.message); 981}); 982``` 983 984### release<sup>9+</sup> 985 986release(callback: AsyncCallback\<void>): void 987 988Releases the video recording resources. This API uses an asynchronous callback to return the result. 989 990**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 991 992**System API**: This is a system API. 993 994**Parameters** 995 996| Name | Type | Mandatory| Description | 997| -------- | -------------------- | ---- | -------------------------------- | 998| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 999 1000**Error codes** 1001 1002For details about the error codes, see [Media Error Codes](errorcode-media.md). 1003 1004| ID| Error Message | 1005| -------- | --------------------------------- | 1006| 5400105 | Service died. Return by callback. | 1007 1008**Example** 1009 1010```ts 1011import { BusinessError } from '@kit.BasicServicesKit'; 1012 1013// asyncallback 1014videoRecorder.release((err: BusinessError) => { 1015 if (err == null) { 1016 console.info('release videorecorder success'); 1017 } else { 1018 console.error('release videorecorder failed and error is ' + err.message); 1019 } 1020}); 1021``` 1022 1023### release<sup>9+</sup> 1024 1025release(): Promise\<void> 1026 1027Releases the video recording resources. This API uses a promise to return the result. 1028 1029**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1030 1031**System API**: This is a system API. 1032 1033**Return value** 1034 1035| Type | Description | 1036| -------------- | ----------------------------------------- | 1037| Promise\<void> | Promise used to return the result.| 1038 1039**Error codes** 1040 1041For details about the error codes, see [Media Error Codes](errorcode-media.md). 1042 1043| ID| Error Message | 1044| -------- | --------------------------------- | 1045| 5400105 | Service died. Return by callback. | 1046 1047**Example** 1048 1049```ts 1050import { BusinessError } from '@kit.BasicServicesKit'; 1051 1052// promise 1053videoRecorder.release().then(() => { 1054 console.info('release videorecorder success'); 1055}).catch((err: BusinessError) => { 1056 console.error('release videorecorder failed and catch error is ' + err.message); 1057}); 1058``` 1059 1060### reset<sup>9+</sup> 1061 1062reset(callback: AsyncCallback\<void>): void 1063 1064Resets video recording. This API uses an asynchronous callback to return the result. 1065 1066To start another recording, you must call [prepare()](#prepare9) and [getInputSurface()](#getinputsurface9) again. 1067 1068**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1069 1070**System API**: This is a system API. 1071 1072**Parameters** 1073 1074| Name | Type | Mandatory| Description | 1075| -------- | -------------------- | ---- | ---------------------------- | 1076| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 1077 1078**Error codes** 1079 1080For details about the error codes, see [Media Error Codes](errorcode-media.md). 1081 1082| ID| Error Message | 1083| -------- | --------------------------------- | 1084| 5400103 | I/O error. Return by callback. | 1085| 5400105 | Service died. Return by callback. | 1086 1087**Example** 1088 1089```ts 1090import { BusinessError } from '@kit.BasicServicesKit'; 1091 1092// asyncallback 1093videoRecorder.reset((err: BusinessError) => { 1094 if (err == null) { 1095 console.info('reset videorecorder success'); 1096 } else { 1097 console.error('reset videorecorder failed and error is ' + err.message); 1098 } 1099}); 1100``` 1101 1102### reset<sup>9+</sup> 1103 1104reset(): Promise\<void> 1105 1106Resets video recording. This API uses a promise to return the result. 1107 1108To start another recording, you must call [prepare()](#prepare9-1) and [getInputSurface()](#getinputsurface9-1) again. 1109 1110**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1111 1112**System API**: This is a system API. 1113 1114**Return value** 1115 1116| Type | Description | 1117| -------------- | ------------------------------------- | 1118| Promise\<void> | Promise used to return the result.| 1119 1120**Error codes** 1121 1122For details about the error codes, see [Media Error Codes](errorcode-media.md). 1123 1124| ID| Error Message | 1125| -------- | -------------------------------- | 1126| 5400103 | I/O error. Return by promise. | 1127| 5400105 | Service died. Return by promise. | 1128 1129**Example** 1130 1131```ts 1132import { BusinessError } from '@kit.BasicServicesKit'; 1133 1134// promise 1135videoRecorder.reset().then(() => { 1136 console.info('reset videorecorder success'); 1137}).catch((err: BusinessError) => { 1138 console.error('reset videorecorder failed and catch error is ' + err.message); 1139}); 1140``` 1141 1142### on('error')<sup>9+</sup> 1143 1144on(type: 'error', callback: ErrorCallback): void 1145 1146Subscribes to video recording error events. After an error event is reported, you must handle the event and exit the recording. 1147 1148**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1149 1150**System API**: This is a system API. 1151 1152**Parameters** 1153 1154| Name | Type | Mandatory| Description | 1155| -------- | ------------- | ---- | ------------------------------------------------------------ | 1156| type | string | Yes | Event type, which is **'error'** in this case.<br>This event is triggered when an error occurs during video recording.| 1157| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | Yes | Callback invoked when the event is triggered. | 1158 1159**Error codes** 1160 1161For details about the error codes, see [Media Error Codes](errorcode-media.md). 1162 1163| ID| Error Message | 1164| -------- | --------------------------------- | 1165| 5400103 | I/O error. Return by callback. | 1166| 5400105 | Service died. Return by callback. | 1167 1168**Example** 1169 1170```ts 1171import { BusinessError } from '@kit.BasicServicesKit'; 1172 1173// This event is reported when an error occurs during the retrieval of videoRecordState. 1174videoRecorder.on('error', (error: BusinessError) => { // Set the 'error' event callback. 1175 console.error(`audio error called, error: ${error}`); 1176}) 1177``` 1178 1179## VideoRecordState<sup>9+</sup> 1180 1181Enumerates the video recording states. You can obtain the state through the **state** attribute. 1182 1183**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1184 1185**System API**: This is a system API. 1186 1187| Name | Type | Description | 1188| -------- | ------ | ---------------------- | 1189| idle | string | The video recorder is idle. | 1190| prepared | string | The video recording parameters are set.| 1191| playing | string | Video recording is in progress. | 1192| paused | string | Video recording is paused. | 1193| stopped | string | Video recording is stopped. | 1194| error | string | Video recording is in the error state. | 1195 1196## VideoRecorderConfig<sup>9+</sup> 1197 1198Describes the video recording parameters. 1199 1200The **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**. 1201 1202**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1203 1204**System API**: This is a system API. 1205 1206| Name | Type | Mandatory| Description | 1207| --------------- | ---------------------------------------------- | ---- | ------------------------------------------------------------ | 1208| audioSourceType | [AudioSourceType](js-apis-media.md#audiosourcetype9) | No | Type of the audio source for video recording. This parameter is mandatory for audio recording. | 1209| videoSourceType | [VideoSourceType](js-apis-media.md#videosourcetype9) | Yes | Type of the video source for video recording. | 1210| profile | [VideoRecorderProfile](#videorecorderprofile9) | Yes | Video recording profile. | 1211| rotation | number | No | Rotation angle of the recorded video. The value can only be 0 (default), 90, 180, or 270. | 1212| location | [Location](js-apis-media.md#location) | No | Geographical location of the recorded video. By default, the geographical location information is not recorded. | 1213| url | string | Yes | Video output URL. Supported: fd://xx (fd number)<br> | 1214 1215## VideoRecorderProfile<sup>9+</sup> 1216 1217Describes the video recording profile. 1218 1219**System capability**: SystemCapability.Multimedia.Media.VideoRecorder 1220 1221**System API**: This is a system API. 1222 1223| Name | Type | Mandatory| Description | 1224| ---------------- | -------------------------------------------- | ---- | ---------------- | 1225| audioBitrate | number | No | Audio encoding bit rate. This parameter is mandatory for audio recording.| 1226| audioChannels | number | No | Number of audio channels. This parameter is mandatory for audio recording.| 1227| audioCodec | [CodecMimeType](js-apis-media.md#codecmimetype8) | No | Audio encoding format. This parameter is mandatory for audio recording. | 1228| audioSampleRate | number | No | Audio sampling rate. This parameter is mandatory for audio recording. | 1229| fileFormat | [ContainerFormatType](js-apis-media.md#containerformattype8) | Yes | Container format of a file.| 1230| videoBitrate | number | Yes | Video encoding bit rate.| 1231| videoCodec | [CodecMimeType](js-apis-media.md#codecmimetype8) | Yes | Video encoding format. | 1232| videoFrameWidth | number | Yes | Width of the recorded video frame.| 1233| videoFrameHeight | number | Yes | Height of the recorded video frame.| 1234| videoFrameRate | number | Yes | Video frame rate. | 1235 1236## WatermarkConfig<sup>12+</sup> 1237 1238Describes the watermark configuration set for the AVRecorder. The start point is the upper left corner of the image. 1239 1240**System capability**: SystemCapability.Multimedia.Media.Core 1241 1242**System API**: This is a system API. 1243 1244| Name | Type | Mandatory| Description | 1245| --------- | ------ | ---- | ---------------- | 1246| top | number | Yes | Pixel offset from the top edge of the image.| 1247| left | number | Yes | Pixel offset from the left edge of the image.| 1248
