Screen Capture

queryScreenCaptureCapability

Queries the maximum supported frame rate for screen sharing on the device.

public abstract int queryScreenCaptureCapability();
Since
Added since v4.2.0.

To ensure optimal screen sharing performance, especially when enabling high frame rates such as 60 fps, Agora recommends that you use this method to query the maximum supported frame rate before sharing. If the device does not support such high frame rates, you can adjust the screen sharing stream's frame rate accordingly to avoid affecting the sharing quality.

Return Values

  • 0: The device supports up to 15 fps.
  • 1: The device supports up to 30 fps.
  • 2: The device supports up to 60 fps.
  • < 0: Failure.

setExternalMediaProjection

Configures an external MediaProjection for the SDK to capture screen video streams.

public abstract int setExternalMediaProjection(MediaProjection mediaProjection);

After calling this method successfully, the provided external MediaProjection replaces the one requested by the SDK for capturing screen video streams. When screen sharing stops or RtcEngine is destroyed, the SDK automatically releases the MediaProjection.

Note: You must request [MediaProjection](https://developer.android.com/reference/android/media/projection/MediaProjection) permission before calling this method.

Scenario

If you have already obtained a MediaProjection, you can use your own MediaProjection directly without using the one requested by the SDK. Applicable scenarios include:
  • On customized system devices, avoid system pop-ups (such as user authorization for screen capture) and start capturing screen video streams directly.
  • In screen sharing processes involving one or more subprocesses, avoid potential errors when creating objects in subprocesses to prevent screen capture failure.
This method is applicable in multi-channel scenarios.

Timing

Call this method after startScreenCapture.

Parameters

mediaProjection
The object used to capture screen video streams.

Return Values

  • 0: Success.
  • < 0: Failure.

setScreenCaptureScenario

Sets the screen sharing scenario.

public abstract int setScreenCaptureScenario(Constants.ScreenScenarioType screenScenario);
Since
Available since v4.2.0.

The SDK automatically adjusts the quality and user experience of the shared video based on the selected scenario.

Note: Agora recommends calling this method before joining a channel.

Parameters

screenScenario
Screen sharing scenario. See ScreenScenarioType.

Return Values

  • 0: Success.
  • < 0: Failure.

startScreenCapture

Starts screen capture.

public abstract int startScreenCapture(ScreenCaptureParameters screenCaptureParameters);
Since
Added since v3.7.0.
You can call this method before or after joining a channel to start capturing the screen video stream as follows:
  • Call this method first, then call joinChannel and set publishScreenCaptureVideo to true to start screen sharing.
  • Call this method after joining the channel, then call updateChannelMediaOptions and set publishScreenCaptureVideo to true to start screen sharing.
Note:
  • On Android, if the user does not grant screen capture permission to the app, the SDK triggers the onPermissionError (error code 2) callback.
  • On Android 9 and above, to avoid the app being killed by the system when it goes to the background, Agora recommends adding the foreground service permission android.permission.FOREGROUND_SERVICE in the /app/Manifests/AndroidManifest.xml file.
  • Due to performance limitations, Android TV does not support screen sharing.
  • Due to system limitations, when using Huawei phones, do not change the video encoding resolution of the screen sharing stream during screen sharing, as it may cause a crash.
  • Due to system limitations, some Xiaomi devices do not support capturing system audio during screen sharing.
  • To avoid system audio capture failure during screen sharing, Agora recommends setting the audio scenario to AUDIO_SCENARIO_GAME_STREAMING using setAudioScenario before joining the channel.
  • The billing of the screen sharing stream is based on the dimensions in VideoCaptureParameters:
    • If the value is not provided, Agora charges based on 1280 × 720.
    • If the value is provided, Agora charges based on the provided value.

Scenario

Used in screen sharing scenarios.

Timing

You can call this method before or after joining a channel.

Parameters

screenCaptureParameters
Encoding parameters for screen sharing. See ScreenCaptureParameters.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: System version too low. Make sure the Android API level is no lower than 21.
    • -3: Failed to capture system audio. Make sure the Android API level is no lower than 29.

stopScreenCapture

Stops screen capture.

public abstract int stopScreenCapture();
Since
Available since v3.7.0.

If you started screen capture by calling startScreenCapture, you need to call stopScreenCapture to stop it.

Timing

You can call this method before or after joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure.

updateScreenCaptureParameters

Updates the screen capture parameters.

public abstract int updateScreenCaptureParameters(ScreenCaptureParameters screenCaptureParameters);
Since
Available since v3.7.0.
Note: Call this method after starting screen or window sharing.

Parameters

screenCaptureParameters
Encoding parameters for screen sharing. See ScreenCaptureParameters.
Note: The video properties of the screen sharing stream should only be set through this parameter and are not related to setVideoEncoderConfiguration.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid parameter.
    • -8: Invalid screen sharing state. This may occur if you are already sharing another screen or window. Try calling stopScreenCapture to stop the current sharing and then restart screen sharing.