1# Interface (AVScreenCaptureRecorder) 2<!--Kit: Media Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @zzs_911--> 5<!--Designer: @stupig001--> 6<!--Tester: @xdlinc--> 7<!--Adviser: @zengyawen--> 8 9> **NOTE** 10> 11> - 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. 12> - The initial APIs of this interface are supported since API version 12. 13 14AVScreenCaptureRecorder is a class for screen capture management. It provides APIs for screen capture. Before calling any API in AVScreenCaptureRecorder, you must use [createAVScreenCaptureRecorder()](arkts-apis-media-f.md#mediacreateavscreencapturerecorder12) to create an AVScreenCaptureRecorder instance. 15 16## Modules to Import 17 18```ts 19import { media } from '@kit.MediaKit'; 20``` 21 22## init<sup>12+</sup> 23 24init(config: AVScreenCaptureRecordConfig): Promise\<void> 25 26Initializes screen capture and sets screen capture parameters. This API uses a promise to return the result. 27 28**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 29 30**Parameters** 31 32| Name| Type | Mandatory| Description | 33| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 34| config | [AVScreenCaptureRecordConfig](arkts-apis-media-i.md#avscreencapturerecordconfig12) | Yes | Screen capture parameters to set.| 35 36**Return value** 37 38| Type | Description | 39| -------------- | ----------------------------------- | 40| Promise\<void> | Promise that returns no value.| 41 42**Error codes** 43 44For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](errorcode-media.md). 45 46| ID| Error Message | 47| -------- | ---------------------------------------------- | 48| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 49| 5400103 | IO error. Return by promise. | 50| 5400105 | Service died. Return by promise. | 51 52**Example** 53 54```ts 55import { BusinessError } from '@kit.BasicServicesKit'; 56import { fileIo as fs } from '@kit.CoreFileKit'; 57 58public getFileFd(): number { 59 let filesDir = '/data/storage/el2/base/haps'; 60 let file = fs.openSync(filesDir + '/screenCapture.mp4', fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); 61 return file.fd; 62} 63 64let avCaptureConfig: media.AVScreenCaptureRecordConfig = { 65 fd: this.getFileFd(), // Before passing in an FD to this parameter, the file (generally an MP4 file) must be created by the caller and granted with the write permissions. 66 frameWidth: 640, 67 frameHeight: 480 68 // Add other parameters. 69}; 70 71avScreenCaptureRecorder.init(avCaptureConfig).then(() => { 72 console.info('Succeeded in initing avScreenCaptureRecorder'); 73}).catch((err: BusinessError) => { 74 console.info('Failed to init avScreenCaptureRecorder, error: ' + err.message); 75}); 76``` 77 78## startRecording<sup>12+</sup> 79 80startRecording(): Promise\<void> 81 82Starts screen capture. This API uses a promise to return the result. 83 84**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 85 86**Return value** 87 88| Type | Description | 89| -------------- | -------------------------------- | 90| Promise\<void> | Promise that returns no value.| 91 92**Error codes** 93 94For details about the error codes, see [Media Error Codes](errorcode-media.md). 95 96| ID| Error Message | 97| -------- | -------------------------------- | 98| 5400103 | IO error. Return by promise. | 99| 5400105 | Service died. Return by promise. | 100 101**Example** 102 103```ts 104import { BusinessError } from '@kit.BasicServicesKit'; 105 106avScreenCaptureRecorder.startRecording().then(() => { 107 console.info('Succeeded in starting avScreenCaptureRecorder'); 108}).catch((err: BusinessError) => { 109 console.info('Failed to start avScreenCaptureRecorder, error: ' + err.message); 110}); 111``` 112 113## stopRecording<sup>12+</sup> 114 115stopRecording(): Promise\<void> 116 117Stops screen capture. This API uses a promise to return the result. 118 119**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 120 121**Return value** 122 123| Type | Description | 124| -------------- | --------------------------------- | 125| Promise\<void> | Promise that returns no value.| 126 127**Error codes** 128 129For details about the error codes, see [Media Error Codes](errorcode-media.md). 130 131| ID| Error Message | 132| -------- | -------------------------------- | 133| 5400103 | IO error. Return by promise. | 134| 5400105 | Service died. Return by promise. | 135 136**Example** 137 138```ts 139import { BusinessError } from '@kit.BasicServicesKit'; 140 141avScreenCaptureRecorder.stopRecording().then(() => { 142 console.info('Succeeded in stopping avScreenCaptureRecorder'); 143}).catch((err: BusinessError) => { 144 console.info('Failed to stop avScreenCaptureRecorder, error: ' + err.message); 145}); 146``` 147 148## skipPrivacyMode<sup>12+</sup> 149 150skipPrivacyMode(windowIDs: Array\<number>): Promise\<void> 151 152During screen capture, the application can exempt its privacy windows from security purposes. This API uses a promise to return the result. 153For example, if a user enters a password in this application during screen capture, the application will not display a black screen. 154 155**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 156 157**Parameters** 158 159| Name| Type | Mandatory| Description | 160| ------ | ------- | ---- | --------------------------------------------------------- | 161| windowIDs | Array\<number> | Yes | IDs of windows that require privacy exemption, including the main window IDs and subwindow IDs. For details about how to obtain window properties, see [Window API Reference](../apis-arkui/arkts-apis-window-Window.md#getwindowproperties9).| 162 163**Return value** 164 165| Type | Description | 166| -------------- | -------------------------------- | 167| Promise\<void> | Promise that returns no value.| 168 169**Error codes** 170 171For details about the error codes, see [Media Error Codes](errorcode-media.md). 172 173| ID| Error Message | 174| -------- | -------------------------------- | 175| 5400103 | IO error. Return by promise. | 176| 5400105 | Service died. Return by promise. | 177 178**Example** 179 180```ts 181import { BusinessError } from '@kit.BasicServicesKit'; 182 183let windowIDs = []; 184avScreenCaptureRecorder.skipPrivacyMode(windowIDs).then(() => { 185 console.info('Succeeded in skipping privacy mode'); 186}).catch((err: BusinessError) => { 187 console.info('Failed to skip privacy mode, error: ' + err.message); 188}); 189``` 190 191## setMicEnabled<sup>12+</sup> 192 193setMicEnabled(enable: boolean): Promise\<void> 194 195Enables or disables the microphone. This API uses a promise to return the result. 196 197**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 198 199**Parameters** 200 201| Name| Type | Mandatory| Description | 202| ------ | ------- | ---- | --------------------------------------------------------- | 203| enable | boolean | Yes | Whether to enable the microphone. **true** to enable, **false** otherwise.| 204 205**Return value** 206 207| Type | Description | 208| -------------- | --------------------------------------- | 209| Promise\<void> | Promise that returns no value.| 210 211**Error codes** 212 213For details about the error codes, see [Media Error Codes](errorcode-media.md). 214 215| ID| Error Message | 216| -------- | -------------------------------- | 217| 5400103 | IO error. Return by promise. | 218| 5400105 | Service died. Return by promise. | 219 220**Example** 221 222```ts 223import { BusinessError } from '@kit.BasicServicesKit'; 224 225avScreenCaptureRecorder.setMicEnabled(true).then(() => { 226 console.info('Succeeded in setMicEnabled avScreenCaptureRecorder'); 227}).catch((err: BusinessError) => { 228 console.info('Failed to setMicEnabled avScreenCaptureRecorder, error: ' + err.message); 229}); 230``` 231 232## release<sup>12+</sup> 233 234release(): Promise\<void> 235 236Releases this AVScreenCaptureRecorder instance. This API uses a promise to return the result. 237 238**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 239 240**Return value** 241 242| Type | Description | 243| -------------- | --------------------------------- | 244| Promise\<void> | Promise that returns no value.| 245 246**Error codes** 247 248For details about the error codes, see [Media Error Codes](errorcode-media.md). 249 250| ID| Error Message | 251| -------- | -------------------------------- | 252| 5400103 | IO error. Return by promise. | 253| 5400105 | Service died. Return by promise. | 254 255**Example** 256 257```ts 258import { BusinessError } from '@kit.BasicServicesKit'; 259 260avScreenCaptureRecorder.release().then(() => { 261 console.info('Succeeded in releasing avScreenCaptureRecorder'); 262}).catch((err: BusinessError) => { 263 console.error(`Failed to release avScreenCaptureRecorder. Code: ${err.code}, message: ${err.message}`); 264}); 265``` 266 267## on('stateChange')<sup>12+</sup> 268 269on(type: 'stateChange', callback: Callback\<AVScreenCaptureStateCode>): void 270 271Subscribes to screen capture state changes. An application can subscribe to only one screen capture state change event. When the application initiates multiple subscriptions to this event, the last subscription is applied. 272 273**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 274 275**Parameters** 276 277| Name | Type | Mandatory| Description | 278| -------- | -------- | ---- | ------------------------------------------------------------ | 279| type | string | Yes | Event type, which is **'stateChange'** in this case. | 280| callback | function | Yes | Callback invoked when the event is triggered. [AVScreenCaptureStateCode](arkts-apis-media-e.md#avscreencapturestatecode12) indicates the new state.| 281 282**Example** 283 284```ts 285avScreenCaptureRecorder.on('stateChange', (state: media.AVScreenCaptureStateCode) => { 286 console.info('avScreenCaptureRecorder stateChange to ' + state); 287}); 288``` 289 290## on('error')<sup>12+</sup> 291 292on(type: 'error', callback: ErrorCallback): void 293 294Subscribes to AVScreenCaptureRecorder errors. You can handle the errors based on the application logic. An application can subscribe to only one AVScreenCaptureRecorder error event. When the application initiates multiple subscriptions to this event, the last subscription is applied. 295 296**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 297 298**Parameters** 299 300| Name | Type | Mandatory| Description | 301| -------- | ------------- | ---- | --------------------------------------- | 302| type | string | Yes | Event type, which is **'error'** in this case.| 303| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | Yes | Callback invoked when the event is triggered. | 304 305**Error codes** 306 307For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Media Error Codes](errorcode-media.md). 308 309| ID| Error Message | 310| -------- | -------------------------------- | 311| 201 | permission denied. | 312| 5400103 | IO error. Return by ErrorCallback. | 313| 5400105 | Service died. Return by ErrorCallback. | 314 315**Example** 316 317```ts 318avScreenCaptureRecorder.on('error', (err: BusinessError) => { 319 console.error('avScreenCaptureRecorder error:' + err.message); 320}); 321``` 322 323## off('stateChange')<sup>12+</sup> 324 325 off(type: 'stateChange', callback?: Callback\<AVScreenCaptureStateCode>): void 326 327Unsubscribes from screen capture state changes. You can specify a callback to cancel the specified subscription. 328 329**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 330 331**Parameters** 332 333| Name | Type | Mandatory| Description | 334| -------- | -------- | ---- | ------------------------------------------------------------ | 335| type | string | Yes | Event type, which is **'stateChange'** in this case. | 336| callback | function | No | Callback used for unsubscription. [AVScreenCaptureStateCode](arkts-apis-media-e.md#avscreencapturestatecode12) indicates the new state. If this parameter is not specified, the last subscription is canceled.| 337 338**Example** 339 340```ts 341avScreenCaptureRecorder.off('stateChange'); 342``` 343 344## off('error')<sup>12+</sup> 345 346off(type: 'error', callback?: ErrorCallback): void 347 348Unsubscribes from AVScreenCaptureRecorder errors. You can specify a callback to cancel the specified subscription. 349 350**System capability**: SystemCapability.Multimedia.Media.AVScreenCapture 351 352**Parameters** 353 354| Name | Type | Mandatory| Description | 355| -------- | -------- | ---- | ---------------------------------------------------------- | 356| type | string | Yes | Event type, which is **'error'** in this case. | 357| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | No | Callback used for unsubscription. If this parameter is not specified, the last subscription is canceled.| 358 359**Example** 360 361```ts 362avScreenCaptureRecorder.off('error'); 363``` 364