• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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> **说明：**
10>
11> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
12> - 本Interface首批接口从API version 12开始支持。
13
14屏幕录制管理类，用于进行屏幕录制。在调用AVScreenCaptureRecorder的方法前，需要先通过[createAVScreenCaptureRecorder()](arkts-apis-media-f.md#mediacreateavscreencapturerecorder12)创建一个AVScreenCaptureRecorder实例。
15
16## 导入模块
17
18```ts
19import { media } from '@kit.MediaKit';
20```
21
22## init<sup>12+</sup>
23
24init(config: AVScreenCaptureRecordConfig): Promise\<void>
25
26异步方式进行录屏初始化，设置录屏参数。通过Promise获取返回值。
27
28**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture
29
30**参数：**
31
32| 参数名 | 类型                                                         | 必填 | 说明                     |
33| ------ | ------------------------------------------------------------ | ---- | ------------------------ |
34| config | [AVScreenCaptureRecordConfig](arkts-apis-media-i.md#avscreencapturerecordconfig12) | 是   | 配置屏幕录制的相关参数。 |
35
36**返回值：**
37
38| 类型           | 说明                                |
39| -------------- | ----------------------------------- |
40| Promise\<void> | 异步录屏初始化方法的Promise返回值。 |
41
42**错误码：**
43
44以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体错误码](errorcode-media.md)。
45
46| 错误码ID | 错误信息                                       |
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**示例：**
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(), // 文件需要先由调用者创建，通常是MP4文件，赋予写权限，将文件fd传给此参数。
66    frameWidth: 640,
67    frameHeight: 480
68    // 补充其他参数。
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
82异步方式开始录屏。通过Promise获取返回值。
83
84**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture
85
86**返回值：**
87
88| 类型           | 说明                             |
89| -------------- | -------------------------------- |
90| Promise\<void> | Promise对象，无返回结果。 |
91
92**错误码：**
93
94以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
95
96| 错误码ID | 错误信息                         |
97| -------- | -------------------------------- |
98| 5400103  | IO error. Return by promise.     |
99| 5400105  | Service died. Return by promise. |
100
101**示例：**
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
117异步方式结束录屏。通过Promise获取返回值。
118
119**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture
120
121**返回值：**
122
123| 类型           | 说明                              |
124| -------------- | --------------------------------- |
125| Promise\<void> | 异步结束录屏方法的Promise返回值。 |
126
127**错误码：**
128
129以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
130
131| 错误码ID | 错误信息                         |
132| -------- | -------------------------------- |
133| 5400103  | IO error. Return by promise.     |
134| 5400105  | Service died. Return by promise. |
135
136**示例：**
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.error(`Failed to stop avScreenCaptureRecorder. Code: ${err.code}, message: ${err.message}`);
145});
146```
147
148## skipPrivacyMode<sup>12+</sup>
149
150skipPrivacyMode(windowIDs: Array\<number>): Promise\<void>
151
152录屏时，应用可对本应用的隐私窗口做安全豁免。通过Promise获取返回值。
153如录屏时，用户在本应用进行输入密码等操作，应用不会进行黑屏处理。
154
155**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture
156
157**参数：**
158
159| 参数名 | 类型    | 必填 | 说明                                                      |
160| ------ | ------- | ---- | --------------------------------------------------------- |
161| windowIDs | Array\<number> | 是   | 需要豁免隐私的窗口列表，包括主窗口id和子窗口id，窗口属性获取方法可以参考[窗口API引用](../apis-arkui/arkts-apis-window-Window.md#getwindowproperties9)。 |
162
163**返回值：**
164
165| 类型           | 说明                             |
166| -------------- | -------------------------------- |
167| Promise\<void> | Promise对象，无返回结果。 |
168
169**错误码：**
170
171以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
172
173| 错误码ID | 错误信息                         |
174| -------- | -------------------------------- |
175| 5400103  | IO error. Return by promise.     |
176| 5400105  | Service died. Return by promise. |
177
178**示例：**
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
195异步方式设置麦克风开关。通过Promise获取返回值。
196
197**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture
198
199**参数：**
200
201| 参数名 | 类型    | 必填 | 说明                                                      |
202| ------ | ------- | ---- | --------------------------------------------------------- |
203| enable | boolean | 是   | 麦克风开关控制，true代表麦克风打开，false代表麦克风关闭。 |
204
205**返回值：**
206
207| 类型           | 说明                                    |
208| -------------- | --------------------------------------- |
209| Promise\<void> | 异步设置麦克风开关方法的Promise返回值。 |
210
211**错误码：**
212
213以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
214
215| 错误码ID | 错误信息                         |
216| -------- | -------------------------------- |
217| 5400103  | IO error. Return by promise.     |
218| 5400105  | Service died. Return by promise. |
219
220**示例：**
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.error(`Failed to setMicEnabled avScreenCaptureRecorder. Code: ${err.code}, message: ${err.message}`);
229});
230```
231
232## release<sup>12+</sup>
233
234release(): Promise\<void>
235
236异步方式释放录屏。通过Promise获取返回值。
237
238**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture
239
240**返回值：**
241
242| 类型           | 说明                              |
243| -------------- | --------------------------------- |
244| Promise\<void> | 异步释放录屏方法的Promise返回值。 |
245
246**错误码：**
247
248以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
249
250| 错误码ID | 错误信息                         |
251| -------- | -------------------------------- |
252| 5400103  | IO error. Return by promise.     |
253| 5400105  | Service died. Return by promise. |
254
255**示例：**
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
271订阅录屏状态切换的事件，当状态发生的时候，会通过订阅的回调通知用户。用户只能订阅一个状态切换的回调方法，重复订阅时，以最后一次订阅的回调接口为准。
272
273**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture
274
275**参数：**
276
277| 参数名   | 类型     | 必填 | 说明                                                         |
278| -------- | -------- | ---- | ------------------------------------------------------------ |
279| type     | string   | 是   | 状态切换事件回调类型，支持的事件：'stateChange'。            |
280| callback | Callback\<[AVScreenCaptureStateCode](arkts-apis-media-e.md#avscreencapturestatecode12)> | 是   | 状态切换事件回调方法，[AVScreenCaptureStateCode](arkts-apis-media-e.md#avscreencapturestatecode12)表示切换到的状态。 |
281
282**示例：**
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
294订阅AVScreenCaptureRecorder的错误事件，用户可以根据应用自身逻辑对错误事件进行处理。用户只能订阅一个错误事件的回调方法，重复订阅时，以最后一次订阅的回调接口为准。
295
296**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture
297
298**参数：**
299
300| 参数名   | 类型          | 必填 | 说明                                    |
301| -------- | ------------- | ---- | --------------------------------------- |
302| type     | string        | 是   | 错误事件回调类型，支持的事件：'error'。 |
303| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是   | 录屏错误事件回调方法。                  |
304
305**错误码：**
306
307以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体错误码](errorcode-media.md)。
308
309| 错误码ID | 错误信息                         |
310| -------- | -------------------------------- |
311| 201      | permission denied.     |
312| 5400103  | IO error. Return by ErrorCallback. |
313| 5400105  | Service died. Return by ErrorCallback. |
314
315**示例：**
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
327取消订阅状态切换回调事件。用户可以指定填入状态切换的回调方法来取消订阅。
328
329**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture
330
331**参数：**
332
333| 参数名   | 类型     | 必填 | 说明                                                         |
334| -------- | -------- | ---- | ------------------------------------------------------------ |
335| type     | string   | 是   | 状态切换事件回调类型，支持的事件：'stateChange'。            |
336| callback | Callback\<[AVScreenCaptureStateCode](arkts-apis-media-e.md#avscreencapturestatecode12)> | 否   | 状态切换事件回调方法，[AVScreenCaptureStateCode](arkts-apis-media-e.md#avscreencapturestatecode12)表示切换到的状态，不填此参数则会取消最后一次订阅事件。 |
337
338**示例：**
339
340```ts
341avScreenCaptureRecorder.off('stateChange');
342```
343
344## off('error')<sup>12+</sup>
345
346off(type: 'error', callback?: ErrorCallback): void
347
348取消订阅错误回调事件。用户可以指定填入错误回调方法来取消订阅。
349
350**系统能力：** SystemCapability.Multimedia.Media.AVScreenCapture
351
352**参数：**
353
354| 参数名   | 类型     | 必填 | 说明                                                       |
355| -------- | -------- | ---- | ---------------------------------------------------------- |
356| type     | string   | 是   | 状态切换事件回调类型，支持的事件：'error'。                |
357| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否   | 录屏错误事件回调方法，不填此参数则会取消最后一次订阅事件。 |
358
359**示例：**
360
361```ts
362avScreenCaptureRecorder.off('error');
363```