• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Screen Capture
2
3Screen capture is mainly used to record the main screen.
4
5You can call the native APIs of the **AVScreenCapture** module to record the screen and collect audio and video source data output by the device and microphone. When developing a live streaming or an office application, you can call the APIs to obtain original audio and video streams and transfer the streams to other modules for processing. In this way, the home screen can be shared during live streaming.
6
7The **AVScreenCapture**, **Window**, and **Graphics** modules together implement the entire video capture process.
8
9By default, the main screen is captured, and the **Graphics** module generates the screen capture frame data based on the main screen and places the data to the display data buffer queue. The screen capture framework obtains the data from the display data buffer queue for consumption processing.
10
11## Development Guidelines
12
13The full screen capture process involves creating an **AVScreenCapture** instance, configuring audio and video capture parameters, starting and stopping screen capture, and releasing the instance. This topic describes how to use the **AVScreenCapture** module to carry out one-time screen capture. For details about the API reference, see [AVScreenCapture](../reference/native-apis/_a_v_screen_capture.md).
14
15After an **AVScreenCapture** instance is created, different APIs can be called to switch the AVScreenCapture to different states and trigger the required behavior. If an API is called when the AVScreenCapture is not in the given state, the system may throw an exception or generate other undefined behavior. Therefore, you are advised to check the AVScreenCapture state before triggering state transition.
16
17### Permission Description
18
19Before development, configure the following permissions for your application. For details about permission configuration, see [Permission Application Guide](../security/accesstoken-guidelines.md).
20
21| Permission| Description| Authorization Mode| APL|
22| ------ | ----- | --------| ------- |
23| ohos.permission.CAPTURE_SCREEN | Allows an application to take screenshots.| system_grant | system_core |
24| ohos.permission.MICROPHONE | Allows an application to access the microphone.<br>This permission is required only when you need to record the audio output by the microphone.| user_grant | normal |
25
26### How to Develop
27
28The following walks you through how to implement simple screen capture:
29
301. Create an **AVScreenCapture** instance, named **capture** in this example.
31
32    ```c++
33    OH_AVScreenCapture* capture = AVScreenCapture_Create();
34    ```
35
362. Set screen capture parameters.
37
38      After creating the **capture** instance, you can set the parameters required for screen capture.
39
40    ```c++
41    OH_AudioCaptureInfo miccapinfo = {
42        .audioSampleRate = 16000,
43        .audioChannels = 2,
44        .audioSource = OH_MIC
45    };
46
47    OH_VideoCaptureInfo videocapinfo = {
48        .videoFrameWidth = display->GetWidth(),
49        .videoFrameHeight = display->Height(),
50        .videoSource = OH_VIDEO_SOURCE_SURFACE_RGBA
51    };
52
53    OH_AudioInfo audioinfo = {
54        .micCapInfo = miccapinfo,
55    };
56
57    OH_VideoInfo videoinfo = {
58        .videoCapInfo = videocapinfo
59    };
60
61    OH_RecorderInfo recorderinfo = {
62        .url = name
63    };
64
65    OH_AVScreenCaptureConfig config = {
66        .captureMode = OH_CAPTURE_HOME_SCREEN,
67        .dataType = OH_ORIGINAL_STREAM,
68        .audioInfo = audioinfo,
69        .videoInfo = videoinfo,
70        .recorderInfo = recorderinfo
71    };
72
73    OH_AVScreenCapture_Init(capture, config);
74    ```
75
763. Enable the microphone.
77
78    ```c++
79    bool isMic = true;
80    OH_AVScreenCapture_SetMicrophoneEnabled(capture, isMic);
81    ```
82
834. Set callback functions, which are used to listen for errors that may occur during screen capture and the generation of audio and video stream data.
84
85    ```c++
86    OH_AVScreenCaptureCallback callback;
87    callback.onAudioBufferAvailable = OnAudioBufferAvailable;
88    callback.onVideoBufferAvailable = OnVideoBufferAvailable;
89    OH_AVScreenCapture_SetCallback(capture, callback);
90    ```
91
925. Call **StartScreenCapture** to start screen capture.
93
94    ```c++
95    OH_AVScreenCapture_StartScreenCapture(capture);
96    ```
97
986. Call **StopScreenCapture()** to stop screen capture.
99
100    ```c++
101    OH_AVScreenCapture_StopScreenCapture(capture_);
102    ```
103
1047. Call **AcquireAudioBuffer()** to obtain an audio buffer.
105
106    ```c++
107    OH_AVScreenCapture_AcquireAudioBuffer(capture, &audiobuffer, type);
108    ```
109
1108. Call **AcquireVideoBuffer()** to obtain a video buffer.
111
112    ```c++
113    OH_NativeBuffer* buffer = OH_ScreenCapture_AcquireVideoBuffer(capture, &fence, &timestamp, &damage);
114    ```
115
1169. Call **ReleaseAudioBuffer()** to release the audio buffer.
117
118    ```c++
119    OH_ScreenCapture_ReleaseAudioBuffer(capture, type);
120    ```
121
12210. Call **ReleaseVideoBuffer()** to release the video buffer.
123
124    ```c++
125    OH_ScreenCapture_ReleaseVideoBuffer(capture);
126    ```
127
12811. Call **release()** to release the instance.
129
130    ```c++
131    OH_AVScreenCapture_Release(capture);
132    ```
133
134### Sample Code
135
136Refer to the sample code below to implement screen capture using **AVScreenCapture**.
137Currently, the buffer holds original streams, which can be encoded and saved in MP4 format for playback. The encoding format and file format are reserved and will be implemented in later versions.
138
139```c++
140
141#include "multimedia/player_framework/native_avscreen_capture.h"
142#include "multimedia/player_framework/native_avscreen_capture_base.h"
143#include "multimedia/player_framework/native_avscreen_capture_errors.h"
144
145void OnError(struct OH_AVScreenCapture *capture, int32_t errorCode)
146{
147    (void) capture;
148    (void) errorCode;
149}
150
151void OnAudioBufferAvailable(struct OH_AVScreenCapture *capture, bool isReady, OH_AudioCapSourceType type)
152{
153    if (isReady) {
154        OH_AudioBuffer *audiobuffer = (struct OH_AudioBuffer*) malloc (sizeof(OH_AudioBuffer));
155        // Obtain an audio buffer.
156        int32_t ret = OH_AVScreenCapture_AcquireAudioBuffer(capture, &audiobuffer, type);
157        /* Obtain a buffer. */
158        (void)audiobuffer->buf;
159        /* Obtain the buffer size. */
160        (void)audiobuffer->size;
161        /* Obtain the timestamp of the audio buffer. */
162        (void)audiobuffer->timestamp;
163        free(audiobuffer);
164        audiobuffer = nullptr;
165        // Release the audio buffer.
166        int32_t ret = OH_ScreenCapture_ReleaseAudioBuffer(capture, type);
167    }
168}
169
170void OnVideoBufferAvailable(struct OH_ScreenCapture *capture, bool isReady)
171{
172    if (isReady) {
173        int32_t fence = 0;
174        int64_t timestamp = 0;
175        struct OH_Rect damage;
176        // Obtain a video buffer.
177        OH_NativeBuffer* buffer = OH_ScreenCapture_AcquireVideoBuffer(capture, &fence, &timestamp, &damage);
178        void *virAddr = nullptr;
179        OH_NativeBuffer_Map (buffer, &virAddr); // Obtain a buffer.
180        OH_NativeBuffer_Config config;
181        OH_NativeBuffer_GetNativeBufferConfig(buffer, config); // Obtain the width, height, and format.
182        // Obtain the fence, timestamp, and coordinate information.
183        OH_NativeBuffer_UnMap (buffer); // Release the buffer.
184        // Release the video buffer.
185        int32_t ret = OH_ScreenCapture_ReleaseVideoBuffer(capture);
186    }
187}
188
189int main()
190{
191    // Instantiate AVScreenCapture.
192    struct OH_AVScreenCapture* capture = OH_AVScreenCapture_Create(void);
193    // Set the callbacks.
194    struct OH_AVScreenCaptureCallback callback;
195    callback.onError = OnError;
196    callack.onAudioBufferAvailable = OnAudioBufferAvailable ;
197    callack.onVideoBufferAvailable = OnVideoBufferAvailable;
198    int32_t ret = OH_AVScreenCapture_SetCallback(capture, callback);
199    // Initialize AVScreenCapture and pass in an OH_AVScreenRecorderConfig struct.
200    OH_AudioCaptureInfo miccapinfo = {
201        .audioSampleRate = 16000,
202        .audioChannels = 2,
203        .audioSource = OH_MIC
204    };
205    OH_VideoCaptureInfo videocapinfo = {
206        .videoFrameWidth = 720,
207        .videoFrameHeight = 1280,
208        .videoSource = OH_VIDEO_SOURCE_SURFACE_RGBA
209    };
210    OH_AudioInfo audioinfo = {
211        .micCapInfo = miccapinfo,
212    };
213    OH_VideoInfo videoinfo = {
214        .videoCapInfo = videocapinfo
215    };
216    OH_AVScreenCaptureConfig config = {
217        .captureMode = OH_CAPTURE_HOME_SCREEN,
218        .dataType = OH_ORIGINAL_STREAM,
219        .audioInfo = audioinfo,
220        .videoInfo = videoinfo,
221        .recorderInfo = recorderinfo
222    };
223    OH_AVScreenCapture_Init(capture, config);
224    int32_t ret = OH_AVScreenCapture_Init(capture, &config);
225    // Start screen capture.
226    int32_t ret = OH_AVScreenCapture_StartScreenCapture(capture);
227    // Enable the microphone.
228    int32_t ret = OH_ScreenCapture_SetMicrophoneEnable(capture, true);
229    sleep(10); // Capture the screen for 10s.
230    // Stop screen capture.
231    int32_t ret = OH_ScreenCapture_StopScreenCapture(capture);
232    // Release the AVScreenCapture instance.
233    int32_t ret = OH_ScreenCapture_Realease(capture);
234    return 0;
235}
236```
237