屏幕采集

getCount

获取可共享的窗口和屏幕的个数。

C++
virtual unsigned int getCount() = 0;

返回值

可共享的窗口和屏幕的个数。

所属接口类

IScreenCaptureSourceList

getScreenCaptureSources

获取可共享的屏幕和窗口对象列表。

C++
virtual IScreenCaptureSourceList* getScreenCaptureSources(const SIZE& thumbSize, const SIZE& iconSize, const bool includeScreen) = 0;

屏幕共享或窗口共享前，你可以调用该方法获取可共享的屏幕和窗口的对象列表，方便用户通过列表中的缩略图选择共享某个显示器的屏幕或某个窗口。列表中包含窗口 ID 和屏幕 ID 等重要信息，你可以获取到 ID 后再调用 startScreenCaptureByWindowId 或 startScreenCaptureByDisplayId 开启共享。

注：该方法仅适用于 macOS 和 Windows。

参数

参数名描述

参数名	描述
thumbSize	屏幕或窗口的缩略图的目标尺寸（宽高单位为像素）。详见 `SIZE`。 SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，`thumbSize` 为 100 x 100，缩略图实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，缩略图即为原图，SDK 不进行缩放操作。
iconSize	程序所对应的图标的目标尺寸（宽高单位为像素）。详见 `SIZE`。SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，`iconSize` 为 100 × 100，图标实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，图标即为原图，SDK 不进行缩放操作。
includeScreen	除了窗口信息外，SDK 是否返回屏幕信息： `true`：SDK 返回屏幕和窗口信息。 `false`：SDK 仅返回窗口信息。

thumbSize

屏幕或窗口的缩略图的目标尺寸（宽高单位为像素）。详见 SIZE。 SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，thumbSize 为 100 x 100，缩略图实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，缩略图即为原图，SDK 不进行缩放操作。

iconSize

程序所对应的图标的目标尺寸（宽高单位为像素）。详见 SIZE。SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，iconSize 为 100 × 100，图标实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，图标即为原图，SDK 不进行缩放操作。

includeScreen

除了窗口信息外，SDK 是否返回屏幕信息：

true：SDK 返回屏幕和窗口信息。
false：SDK 仅返回窗口信息。

返回值

IScreenCaptureSourceList

所属接口类

IRtcEngine

getSourceInfo

获取指定的可共享窗口或屏幕的信息。

C++
virtual ScreenCaptureSourceInfo getSourceInfo(unsigned int index) = 0;

获取到 IScreenCaptureSourceList 后，你可以传入指定的可共享窗口或屏幕的索引值，以获取到该窗口或屏幕的信息 ScreenCaptureSourceInfo。

参数

参数名	描述
index	指定的可共享窗口或屏幕的索引。索引值范围为 [0,`getCount()`)。

返回值

ScreenCaptureSourceInfo

所属接口类

IScreenCaptureSourceList

queryScreenCaptureCapability

查询设备在屏幕共享时支持的最高帧率。

C++
#if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS)
    virtual int queryScreenCaptureCapability() = 0;
#endif

自从

v4.2.0

返回值

方法调用成功时，返回设备支持的最高帧率。详见 SCREEN_CAPTURE_FRAMERATE_CAPABILITY。
<0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

release

释放 IScreenCaptureSourceList。

C++
virtual void release() = 0;

获取可共享的窗口和屏幕对象列表后，为避免内存泄露，请调用该方法释放 IScreenCaptureSourceList，不要直接删除 IScreenCaptureSourceList。

所属接口类

IScreenCaptureSourceList

setScreenCaptureContentHint

设置屏幕共享内容类型。

C++
virtual int setScreenCaptureContentHint(VIDEO_CONTENT_HINT contentHint) = 0;
            

SDK 会根据不同的内容类型，使用不同的算法对共享效果进行优化。如果不调用该方法，SDK 会将屏幕共享的内容默认为 CONTENT_HINT_NONE，即无指定的内容类型。

注意：该方法在开始屏幕共享前后都能调用。

参数

参数名	描述
contentHint	屏幕共享的内容类型。详见 `VIDEO_CONTENT_HINT`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2：传入的参数无效。
- -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture [1/2] 停止当前共享，再重新开始共享屏幕。

所属接口类

IRtcEngine

setScreenCaptureScenario

设置屏幕共享的场景。

C++
virtual int setScreenCaptureScenario(SCREEN_SCENARIO_TYPE screenScenario) = 0;

开启屏幕共享或窗口共享时，你可以调用该方法设置屏幕共享的场景，SDK 会根据你设置的场景调整共享画面的画质。

注：声网建议你在加入频道前调用该方法。

参数

参数名	描述
screenScenario	屏幕共享的场景，详见 `SCREEN_SCENARIO_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

startScreenCapture [1/2]

开始屏幕采集。

C++
#if defined(__ANDROID__) || (defined(__APPLE__) && TARGET_OS_IOS)
                virtual int startScreenCapture(const ScreenCaptureParameters2& captureParams) = 0;
              #endif

开启屏幕共享有如下两种方案，你可以根据实际场景进行选择：

在加入频道前调用该方法，然后调用 joinChannel [2/2] 加入频道并设置 publishScreenCaptureVideo 为 true，即可开始屏幕共享。
在加入频道后调用该方法，然后调用 updateChannelMediaOptions 设置 publishScreenCaptureVideo 为 true，即可开始屏幕共享。

注意：

该方法仅适用于 Android 和 iOS 平台。
在 iOS 平台上，屏幕共享仅适用于 iOS 12.0 及以上。
屏幕共享流的计费以 ScreenVideoParameters 中的 dimensions 值为准：当你未传值时，以 1280 × 720 计费；当你传值时，以你传入的值计费。详细的计费规则请参考计费说明。
在 iOS 平台上，如果你使用音频自采集而非 SDK 采集音频，为避免应用退后台后屏幕共享停止，建议你对应用添加保活处理逻辑。
在 iOS 平台上，该功能对设备性能要求较高，建议你在 iPhone X 及之后机型上使用。
在 iOS 平台上，该方法依赖于屏幕共享动态库 AgoraReplayKitExtension.xcframework，如果删除该动态库会导致无法正常开启屏幕共享。
在 Android 平台上，请确保用户已授予 app 屏幕采集权限。
请确保 Android API 级别不低于 21，否则 SDK 会报告错误码 ERR_SCREEN_CAPTURE_PERMISSION_DENIED(16) 和 ERR_SCREEN_CAPTURE_SYSTEM_NOT_SUPPORTED(2)。
如需在屏幕共享时采集系统音频，你还需确保 Android API 级别不低于 29，否则 SDK 会报告错误码 ERR_SCREEN_CAPTURE_SYSTEM_AUDIO_NOT_SUPPORTED(3)。
在 Android 9 及之后版本上，为避免应用退后台后被系统杀死，建议你在 /app/Manifests/AndroidManifest.xml 文件中添加前台服务权限：android.permission.FOREGROUND_SERVICE。
因 Android 性能限制，屏幕共享不支持 Android TV。
因 Android 系统限制，使用华为手机进行屏幕共享时，为避免崩溃，请不要在共享过程中调节屏幕共享流的视频编码分辨率。
因 Android 系统限制，部分小米手机不支持屏幕共享时采集系统音频。
为提高屏幕共享时采集系统音频的成功率，建议你在加入频道前通过 setAudioScenario 方法设置音频场景为 AUDIO_SCENARIO_GAME_STREAMING。

参数

参数名	描述
captureParams	屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080，即 2,073,600 像素。该像素值为计费标准。详见 `ScreenCaptureParameters2`。

返回值

0: 方法调用成功。
< 0: 方法调用失败
- -2: 参数为空。

所属接口类

IRtcEngine

startScreenCapture [2/2]

开始屏幕采集。

C++
virtual int startScreenCapture(VIDEO_SOURCE_TYPE sourceType, const ScreenCaptureConfiguration& config) = 0;

自从

v4.2.0

该方法和 startScreenCapture [1/2]、startScreenCaptureByDisplayId 和 startScreenCaptureByWindowId 均可以开启屏幕采集，区别如下：

startScreenCapture [1/2] 仅适用于移动端，该方法仅适用于桌面端。
startScreenCaptureByDisplayId 和 startScreenCaptureByWindowId 仅支持采集单个屏幕或窗口；调用该方法可以通过 sourceType 指定多个视频源，以采集多路屏幕共享流，用于本地合图或者多频道发布。

注意：

该方法仅适用于 macOS 和 Windows 平台。
如果调用该方法开始屏幕采集，声网建议你使用 stopScreenCapture [2/2] 停止采集，不要与 stopScreenCapture [1/2] 混用。

参数

参数名描述

参数名	描述
sourceType	视频源的类型，详见 `VIDEO_SOURCE_TYPE`。注： Windows 平台最多支持 4 路屏幕采集的视频流。 macOS 平台最多支持 1 路屏幕采集的视频流，当前仅支持将该参数设置为 `VIDEO_SOURCE_SCREEN(2)`。
config	屏幕采集配置。详见 `ScreenCaptureConfiguration`。

sourceType

视频源的类型，详见 VIDEO_SOURCE_TYPE。
注：

Windows 平台最多支持 4 路屏幕采集的视频流。
macOS 平台最多支持 1 路屏幕采集的视频流，当前仅支持将该参数设置为 VIDEO_SOURCE_SCREEN(2)。

config

屏幕采集配置。详见 ScreenCaptureConfiguration。

所属接口类

IRtcEngine

startScreenCaptureByDisplayId

开始采集指定屏幕的视频流。

C++
virtual int startScreenCaptureByDisplayId(uint32_t displayId, const Rectangle& regionRect,
                                            const ScreenCaptureParameters& captureParams) = 0;

共享一个屏幕或该屏幕的部分区域。

开启屏幕共享有如下两种方案，你可以根据实际场景进行选择：

在加入频道前调用该方法，然后调用 joinChannel [2/2] 加入频道并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。
在加入频道后调用该方法，然后调用 updateChannelMediaOptions 设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。

注意：该方法仅适用于 Windows 和 macOS。

参数

参数名	描述
displayId	指定待共享的屏幕 ID。注：对于 Windows 平台，如果你需要同时共享两个屏幕（主屏 + 副屏），可以在调用该方法时，将 `displayId` 设置为 `-1`。
regionRect	（可选）指定待共享区域相对于整个屏幕的位置。如需共享整个屏幕，则填 `nil`。详见 `Rectangle`。
captureParams	如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果宽或高设为 0，则共享整个屏幕。

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2：传入的参数无效。
- -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture [1/2] 停止当前共享，再重新开始共享屏幕。

所属接口类

IRtcEngine

startScreenCaptureByScreenRect

开始采集指定屏幕区域的视频流。

C++
virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect,
     const Rectangle& regionRect,
     const ScreenCaptureParameters& captureParams) = 0;

弃用

该方法已废弃。请改用 startScreenCaptureByDisplayId。如果你需要在设备外接其他显示屏的情况下开启屏幕共享，强烈建议你使用 startScreenCaptureByDisplayId。

共享一个屏幕或该屏幕的部分区域。你需要在该方法中指定想要共享的屏幕区域。

开启屏幕共享有如下两种方案，你可以根据实际场景进行选择：

在加入频道前调用该方法，然后调用 joinChannel [2/2] 加入频道并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。
在加入频道后调用该方法，然后调用 updateChannelMediaOptions 设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。

注意：该方法仅适用于 Windows 平台。

参数

参数名	描述
screenRect	指定待共享的屏幕相对于虚拟屏的位置。
regionRect	(可选）指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见 `Rectangle`。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕。
captureParams	屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 `ScreenCaptureParameters`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2：传入的参数无效。
- -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture [1/2] 停止当前共享，再重新开始共享屏幕。

所属接口类

IRtcEngine

startScreenCaptureByWindowId

开始采集指定窗口的视频流。

C++
virtual int startScreenCaptureByWindowId(view_t windowId,
                const Rectangle& regionRect,
                const ScreenCaptureParameters& captureParams) = 0;

共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。

开启屏幕共享有如下两种方案，你可以根据实际场景进行选择：

在加入频道前调用该方法，然后调用 joinChannel [2/2] 加入频道并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。
在加入频道后调用该方法，然后调用 updateChannelMediaOptions 设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。

注意：

该方法仅适用于 macOS 和 Windows 平台。
SDK 的窗口共享功能依赖于 WGC（Windows Graphics Capture）或 GDI（Graphics Device Interface）采集，WGC 在早于 Windows 10 2004 的系统上无法设置关闭鼠标采集，因此，当你在搭载早于 Windows 10 2004 系统的设备上进行窗口共享时，可能出现 captureMouseCursor(false) 不生效的现象。详见 ScreenCaptureParameters。

该方法支持共享通用 Windows 平台（UWP）应用窗口。声网使用最新版 SDK 对主流的 UWP 应用进行了测试，结果如下：

系统版本	软件	软件版本	是否支持
win10	Chrome	76.0.3809.100	否
Office Word	18.1903.1152.0	是
Office Excel	否
Office PPT	是
WPS Word	11.1.0.9145	是
WPS Excel
WPS PPT
Media Player（系统自带）	全部	是
win8	Chrome	全部	是
Office Word	全部	是
Office Excel
Office PPT
WPS Word	11.1.0.9098	是
WPS Excel
WPS PPT
Media Player（系统自带）	全部	是
win7	Chrome	73.0.3683.103	否
Office Word	全部	是
Office Excel
Office PPT
WPS Word	11.1.0.9098	否
WPS Excel
WPS PPT	11.1.0.9098	是
Media Player（系统自带）	全部	否

参数

参数名	描述
windowId	指定待共享的窗口 ID。
regionRect	（可选）指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见 `Rectangle`。如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容；如果宽或高为 0，则共享整个窗口。
captureParams	屏幕共享的参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 `ScreenCaptureParameters`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2：传入的参数无效。
- -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture [1/2] 停止当前共享，再重新开始共享屏幕。

所属接口类

IRtcEngine

stopScreenCapture [1/2]

停止屏幕采集。

C++
#if defined(_WIN32) || defined(__APPLE__) || defined(__ANDROID__)
  virtual int stopScreenCapture() = 0;
#endif

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

stopScreenCapture [2/2]

停止屏幕采集。

C++
virtual int stopScreenCapture(VIDEO_SOURCE_TYPE sourceType) = 0;

自从

v4.2.0

调用 startScreenCapture [2/2] 开始一路或多路屏幕采集后，你可以通过调用该方法并设置 sourceType 停止指定屏幕采集。

注意：

该方法仅适用于 macOS 和 Windows 平台。
如果你调用 startScreenCapture [1/2]、startScreenCaptureByWindowId 和 startScreenCaptureByDisplayId 开始屏幕采集，声网建议你使用 stopScreenCapture [1/2] 停止采集，不要与该方法混用。

参数

参数名	描述
sourceType	视频源的类型，详见 `VIDEO_SOURCE_TYPE`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

updateScreenCapture

更新屏幕采集的参数配置。

C++
virtual int updateScreenCapture(const ScreenCaptureParameters2& captureParams) = 0;

如果在开启屏幕共享时未采集系统音频、然后想要更新参数配置、发布系统音频，可参考以下步骤：

调用该方法并设置 captureAudio 为 true。
调用 updateChannelMediaOptions 设置 publishScreenCaptureAudio 为 true，即可发布屏幕采集的音频。

注意：

该方法仅适用于 Android 和 iOS 平台。
在 iOS 平台上，屏幕共享仅适用于 iOS 12.0 及以上。

参数

参数名	描述
captureParams	屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 `ScreenCaptureParameters2`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2：传入的参数无效。
- -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture [1/2] 停止当前共享，再重新开始共享屏幕。

所属接口类

IRtcEngine

updateScreenCaptureParameters

更新屏幕采集的参数配置。

C++
virtual int updateScreenCaptureParameters(const ScreenCaptureParameters& captureParams) = 0;

注意：

该方法仅适用于 Windows 和 macOS 平台。
请在开启屏幕共享或窗口共享后调用该方法。

参数

参数名	描述
captureParams	屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 `ScreenCaptureParameters`。

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2：传入的参数无效。
- -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture [1/2] 停止当前共享，再重新开始共享屏幕。

所属接口类

IRtcEngine

updateScreenCaptureRegion

更新屏幕采集的区域。

C++
virtual int updateScreenCaptureRegion(const Rectangle& regionRect) = 0;

注意：请在开启屏幕共享或窗口共享后调用该方法。

参数

参数名	描述
regionRect	待共享区域相对于整个屏幕或窗口的位置，如不填，则表示共享整个屏幕或窗口。详见 `Rectangle`。如果设置的共享区域超出了屏幕或窗口的边界，则只共享屏幕或窗口内的内容；如果将 width 或 height 设为 0，则共享整个屏幕或窗口。

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2：传入的参数无效。
- -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture [1/2] 停止当前共享，再重新开始共享屏幕。

所属接口类

IRtcEngine

getCount

返回值​

getScreenCaptureSources

参数​

返回值​

getSourceInfo

参数​

返回值​

queryScreenCaptureCapability

返回值​

release

setScreenCaptureContentHint

参数​

返回值​

setScreenCaptureScenario

参数​

返回值​

startScreenCapture [1/2]

参数​

返回值​

startScreenCapture [2/2]

参数​

startScreenCaptureByDisplayId

参数​

返回值​

startScreenCaptureByScreenRect

参数​

返回值​

startScreenCaptureByWindowId

参数​

返回值​

stopScreenCapture [1/2]

返回值​

stopScreenCapture [2/2]

参数​

返回值​

updateScreenCapture

参数​

返回值​

updateScreenCaptureParameters

参数​

返回值​

updateScreenCaptureRegion

参数​

返回值​

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值