Screen Sharing
getCount
Gets the number of shareable windows and screens.
virtual unsigned int getCount() = 0;
Returns
The number of shareable windows and screens.
getScreenCaptureSources
Gets a list of shareable screens and windows.
virtual IScreenCaptureSourceList* getScreenCaptureSources(const SIZE& thumbSize, const SIZE& iconSize, const bool includeScreen) = 0;
You can call this method before sharing a screen or window to get a list of shareable screens and windows, which enables a user to use thumbnails in the list to choose a particular screen or window to share. This list also contains important information such as window ID and screen ID, with which you can call startScreenCaptureByWindowId or startScreenCaptureByDisplayId to start the sharing.
Parameters
- thumbSize
- The target size of the screen or window thumbnail (the width and height are in pixels). See SIZE. The SDK scales the original image to make the length of the longest side of the image the same as that of the target size without distorting the original image. For example, if the original image is 400 × 300 and thumbSize is 100 × 100, the actual size of the thumbnail is 100 × 75. If the target size is larger than the original size, the thumbnail is the original image and the SDK does not scale it.
- iconSize
- The target size of the icon corresponding to the application program (the width and height are in pixels). See SIZE. The SDK scales the original image to make the length of the longest side of the image the same as that of the target size without distorting the original image. For example, if the original image is 400 × 300 and iconSize is 100 × 100, the actual size of the icon is 100 × 75. If the target size is larger than the original size, the icon is the original image and the SDK does not scale it.
- includeScreen
- Whether the SDK returns the screen information in addition to the window information:
true
: The SDK returns screen and window information.false
: The SDK returns the window information only.
Returns
getSourceInfo
Gets information about the specified shareable window or screen.
virtual ScreenCaptureSourceInfo getSourceInfo(unsigned int index) = 0;
After you get IScreenCaptureSourceList, you can pass in the index value of the specified shareable window or screen to get information about that window or screen from ScreenCaptureSourceInfo.
Parameters
- index
- The index of the specified shareable window or screen. The value range is [0, getCount
()
).
Returns
ScreenCaptureSourceInforelease
Releases IScreenCaptureSourceList.
virtual void release() = 0;
After you get the list of shareable windows and screens, to avoid memory leaks, call this method to release IScreenCaptureSourceList instead of deleting IScreenCaptureSourceList directly.
setScreenCaptureContentHint
Sets the content hint for screen sharing.
virtual int setScreenCaptureContentHint(VIDEO_CONTENT_HINT contentHint) = 0;
A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithms to different types of content. If you don't call this method, the default content hint is CONTENT_HINT_NONE.
Parameters
- contentHint
- The content hint for screen sharing. See VideoContentHint.
Returns
- 0: Success.
- < 0: Failure.
ERR_INVALID_STATE
: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again.ERR_INVALID_ARGUMENT
: The parameter is invalid.
setScreenCaptureScenario
Sets the screen sharing scenario.
virtual int setScreenCaptureScenario(SCREEN_SCENARIO_TYPE screenScenario) = 0;
When you start screen sharing or window sharing, you can call this method to set the screen sharing scenario. The SDK adjusts the video quality and experience of the sharing according to the scenario.
Parameters
- screenScenario
- The screen sharing scenario. See SCREEN_SCENARIO_TYPE.
Returns
- 0: Success.
- < 0: Failure.
startPrimaryScreenCapture
Starts sharing the primary screen.
virtual int startPrimaryScreenCapture(const ScreenCaptureConfiguration& config) = 0;
Parameters
- config
-
The configuration of the captured screen. See ScreenCaptureConfiguration.
Returns
- 0: Success.
- < 0: Failure.
startScreenCapture
Starts screen sharing.
#if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS) virtual int startScreenCapture(const ScreenCaptureParameters2& captureParams) = 0; #endif
- Call this method before joining a channel, then call joinChannel [2/2] to join channel and set publishScreenCaptureVideo to
true
to start screen sharing. - Call this method after joining a channel, then call updateChannelMediaOptions and set publishScreenCaptureVideo to
true
to start screen sharing.
- This method applies to Android and iOS only.
- On the iOS platform, screen sharing is only available on iOS 12.0 and later.
- The billing for the screen sharing stream is based on the dimensions in ScreenVideoParameters. When you do not pass in a value, Agora bills you at 1280 × 720; when you pass a value in, Agora bills you at that value. See Pricing.
- If you are using the custom audio source instead of the SDK to capture audio, Agora recommends you add the keep-alive processing logic to your application to avoid screen sharing stopping when the application goes to the background.
- This feature requires high-performance device, and Agora recommends that you use it on iPhone X and later models.
- This method relies on the iOS screen sharing dynamic library
AgoraReplayKitExtension.xcframework
. If the dynamic library is deleted, screen sharing cannot be enabled normally. - On the Android platform, make sure the user has granted the app screen capture permission.
- Make sure that the Android API level is not earlier than 21, otherwise, the SDK reports error codes
ERR_SCREEN_CAPTURE_PERMISSION_DENIED(16)
andERR_SCREEN_CAPTURE_SYSTEM_NOT_SUPPORTED(2)
. - To capture system audio during screen sharing, ensure that the Android API level is not earlier than 29 as well; otherwise, the SDK reports the error code
ERR_SCREEN_CAPTURE_SYSTEM_AUDIO_NOT_SUPPORTED(3)
. - On Android 9 and later, to avoid the application being killed by the system after going to the background, Agora recommends you add the foreground service permission
android.permission.FOREGROUND_SERVICE
to the/app/Manifests/AndroidManifest.xml
file. - Due to performance limitations, screen sharing is not supported on Android TV.
- Due to system limitations, if you are using Huawei phones, do not adjust the video encoding resolution of the screen sharing stream during the screen sharing, or you could experience crashes.
- Due to system limitations, some Xiaomi devices do not support capturing system audio during screen sharing.
- To avoid system audio capture failure when screen sharing, Agora recommends that you set the audio application scenario to AUDIO_SCENARIO_GAME_STREAMING by using thesetAudioScenario method before joining the channel.
Parameters
- captureParams
- The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters2.
Returns
- 0: Success.
- < 0: Failure.
- -2: The parameter is null.
startScreenCaptureByDisplayId
Shares the screen by specifying the display ID.
virtual int startScreenCaptureByDisplayId(uint32_t displayId, const Rectangle& regionRect,
const ScreenCaptureParameters& captureParams) = 0;
This method shares a screen or part of the screen.
- Call this method before joining a channel, and then call joinChannel [2/2] to join a channel and set publishScreenTrack or publishSecondaryScreenTrack to
true
to start screen sharing. - Call this method after joining a channel, and then call updateChannelMediaOptions and set publishScreenTrack or publishSecondaryScreenTrack to
true
to start screen sharing.
Parameters
- displayId
- The display ID of the screen to be shared.
For more information on how to get the display ID, see Share the Screen.
- regionRect
- (Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
- captureParams
- Screen sharing configurations. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters.
Returns
- 0: Success.
- < 0: Failure.
ERR_INVALID_STATE
: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again.ERR_INVALID_ARGUMENT
: The parameter is invalid.
startScreenCaptureByScreenRect
Shares the whole or part of a screen by specifying the screen rect.
virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect,
const Rectangle& regionRect,
const ScreenCaptureParameters& captureParams) = 0;
- Deprecated:
- This method is deprecated. Use startScreenCaptureByDisplayId instead. Agora strongly recommends using startScreenCaptureByDisplayId if you need to start screen sharing on a device connected to another display.
This method shares a screen or part of the screen. You need to specify the area of the screen to be shared.
- Call this method before joining a channel, and then call joinChannel [2/2] to join a channel and set publishScreenTrack or publishSecondaryScreenTrack to
true
to start screen sharing. - Call this method after joining a channel, and then call updateChannelMediaOptions and set publishScreenTrack or publishSecondaryScreenTrack to
true
to start screen sharing.
Parameters
- screenRect
- Sets the relative location of the screen to the virtual screen.
- regionRect
- (Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
- captureParams
- The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters.
Returns
- 0: Success.
- < 0: Failure.
ERR_INVALID_STATE
: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again.ERR_INVALID_ARGUMENT
: The parameter is invalid.
startScreenCaptureByWindowId
Shares the whole or part of a window by specifying the window ID.
virtual int startScreenCaptureByWindowId(view_t windowId,
const Rectangle& regionRect,
const ScreenCaptureParameters& captureParams) = 0;
This method shares a window or part of the window. You need to specify the ID of the window to be shared.
- Call this method before joining a channel, and then call joinChannel [2/2] to join a channel and set publishScreenTrack or publishSecondaryScreenTrack to
true
to start screen sharing. - Call this method after joining a channel, and then call updateChannelMediaOptions and set publishScreenTrack or publishSecondaryScreenTrack to
true
to start screen sharing.
- Applies to the macOS and Windows platforms only.
- The window sharing feature of the Agora SDK relies on WGC (Windows Graphics Capture) or GDI (Graphics Device Interface) capture, and WGC cannot be set to disable mouse capture on systems earlier than Windows 10 2004. Therefore,
captureMouseCursor(false)
might not work when you start window sharing on a device with a system earlier than Windows 10 2004. See ScreenCaptureParameters.
This method supports window sharing of UWP (Universal Windows Platform) applications. Agora tests the mainstream UWP applications by using the lastest SDK, see details as follows:
System version | Software | Compatible versions | Support |
---|---|---|---|
win10 | Chrome | 76.0.3809.100 | No |
Office Word | 18.1903.1152.0 | Yes | |
Office Excel | No | ||
Office PPT | Yes | ||
WPS Word | 11.1.0.9145 | Yes | |
WPS Excel | |||
WPS PPT | |||
Media Player (come with the system) | All | Yes | |
win8 | Chrome | All | Yes |
Office Word | All | Yes | |
Office Excel | |||
Office PPT | |||
WPS Word | 11.1.0.9098 | Yes | |
WPS Excel | |||
WPS PPT | |||
Media Player (come with the system) | All | Yes | |
win7 | Chrome | 73.0.3683.103 | No |
Office Word | All | Yes | |
Office Excel | |||
Office PPT | |||
WPS Word | 11.1.0.9098 | No | |
WPS Excel | |||
WPS PPT | 11.1.0.9098 | Yes | |
Media Player (come with the system) | All | No |
Parameters
- windowId
- The ID of the window to be shared.
- regionRect
- (Optional) Sets the relative location of the region to the screen. If you do not set this parameter, the SDK shares the whole screen. See Rectangle. If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window.
- captureParams
- Screen sharing configurations. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters.
Returns
- 0: Success.
- < 0: Failure.
ERR_INVALID_STATE
: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again.ERR_INVALID_ARGUMENT
: The parameter is invalid.
startSecondaryScreenCapture
Starts sharing a secondary screen.
virtual int startSecondaryScreenCapture(const ScreenCaptureConfiguration& config) = 0;
Parameters
- config
-
The configuration of the captured screen. See ScreenCaptureConfiguration.
Returns
- 0: Success.
- < 0: Failure.
stopPrimaryScreenCapture
Stop sharing the first screen.
virtual int stopPrimaryScreenCapture() = 0;
After calling startPrimaryScreenCapture, you can call this method to stop sharing the first screen.
Returns
- 0: Success.
- < 0: Failure.
stopScreenCapture
Stops screen sharing.
#if defined(_WIN32) || defined(__APPLE__) || defined(__ANDROID__) virtual int stopScreenCapture() = 0; #endif
Returns
- 0: Success.
- < 0: Failure.
stopSecondaryScreenCapture
Stops sharing the secondary screen.
virtual int stopSecondaryScreenCapture() = 0;
After calling startSecondaryScreenCapture, you can call this method to stop sharing the secondary screen.
Returns
- 0: Success.
- < 0: Failure.
updateScreenCapture
Updates the screen sharing parameters.
virtual int updateScreenCapture(const ScreenCaptureParameters2& captureParams) = 0;
- Call this method, and set captureAudio to
true
. - Call updateChannelMediaOptions, and set publishScreenCaptureAudio to
true
to publish the audio captured by the screen.
- This method applies to Android and iOS only.
- On the iOS platform, screen sharing is only available on iOS 12.0 and later.
Parameters
- captureParams
- The screen sharing encoding parameters. The default video resolution is 1920 × 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters2.
Returns
- 0: Success.
- < 0: Failure.
ERR_INVALID_STATE
: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again.ERR_INVALID_ARGUMENT
: The parameter is invalid.
updateScreenCaptureParameters
Updates the screen sharing parameters.
virtual int updateScreenCaptureParameters(const ScreenCaptureParameters& captureParams) = 0;
- This method is for Windows and macOS only.
- Call this method after starting screen sharing or window sharing.
Parameters
- captureParams
- The screen sharing encoding parameters. The default video dimension is 1920 x 1080, that is, 2,073,600 pixels. Agora uses the value of this parameter to calculate the charges. See ScreenCaptureParameters.
Returns
- 0: Success.
- < 0: Failure.
ERR_INVALID_STATE
: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again.ERR_INVALID_ARGUMENT
: The parameter is invalid.
updateScreenCaptureRegion
Updates the screen sharing region.
virtual int updateScreenCaptureRegion(const Rectangle& regionRect) = 0;
Parameters
- regionRect
- The relative location of the screen-share area to the screen or window. If you do not set this parameter, the SDK shares the whole screen or window. See Rectangle. If the specified region overruns the screen or window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen or window.
Returns
- 0: Success.
- < 0: Failure.
ERR_INVALID_STATE
: The screen sharing state is invalid. Probably because you have shared other screens or windows. Try calling stopScreenCapture to stop the current sharing and start sharing the screen again.ERR_INVALID_ARGUMENT
: The parameter is invalid.