屏幕采集
getCount
getScreenCaptureSources
获取可共享的屏幕和窗口列表。
C++
virtual IScreenCaptureSourceList* getScreenCaptureSources(const SIZE& thumbSize, const SIZE& iconSize, const bool includeScreen) = 0;
你可以在共享屏幕或窗口前调用该方法，获取可共享的屏幕和窗口列表。用户可通过列表中的缩略图轻松选择要共享的屏幕或窗口。该列表还包含窗口 ID 和屏幕 ID 等信息，你可以使用这些信息调用 startScreenCaptureByWindowId 或 startScreenCaptureByDisplayId 开始共享。
信息
该方法仅适用于 macOS 和 Windows 平台。
参数
- thumbSize
- 屏幕或窗口缩略图的目标尺寸（宽度和高度，单位为像素）。SDK 会缩放原始图像，使图像最长边的长度与目标尺寸一致，同时不扭曲原始图像。例如，若原始图像为 400 × 300，
thumbSize为 100 × 100，则缩略图的实际尺寸为 100 × 75。如果目标尺寸大于原始尺寸，则缩略图为原始图像，SDK 不进行缩放。详见SIZE。 - iconSize
- 应用程序图标的目标尺寸（宽度和高度，单位为像素）。SDK 会缩放原始图像，使图像最长边的长度与目标尺寸一致，同时不扭曲原始图像。例如，若原始图像为 400 × 300，
iconSize为 100 × 100，则图标的实际尺寸为 100 × 75。如果目标尺寸大于原始尺寸，则图标为原始图像，SDK 不进行缩放。详见SIZE。 - includeScreen
- 是否返回屏幕信息：
- true：返回屏幕和窗口信息。
- false：仅返回窗口信息。
返回值
- 方法调用成功，返回 IScreenCaptureSourceList 实例，详见 IScreenCaptureSourceList。
- 方法调用失败，返回 NULL。
getSourceInfo
获取指定可共享窗口或屏幕的信息。
C++
virtual ScreenCaptureSourceInfo getSourceInfo(unsigned int index) = 0;
在获取 IScreenCaptureSourceList 后，传入指定窗口或屏幕的索引值，从 ScreenCaptureSourceInfo 中获取该窗口或屏幕的信息。
信息
该方法仅适用于 macOS 和 Windows 平台。
参数
- index
- 指定可共享窗口或屏幕的索引。取值范围为 [0, getCount() )。
返回值
方法调用成功，返回 ScreenCaptureSourceInfo 对象，详见 ScreenCaptureSourceInfo。
所属接口类queryScreenCaptureCapability
查询设备在屏幕共享时支持的最高帧率。
C++
virtual int queryScreenCaptureCapability() = 0;
自从
自 v4.2.0 版本新增。
为了确保屏幕共享的最佳性能，特别是在启用如 60 fps 的高帧率时，建议你在共享前调用该方法，查询设备支持的最高帧率。如果设备不支持高帧率，你可以相应地降低屏幕共享流的帧率，以避免影响共享质量。
信息
该方法仅适用于 Android 和 iOS 平台。
适用场景
为确保屏幕共享的最佳性能，特别是在启用如 60 fps 的高帧率时，建议你在共享前使用该方法查询设备支持的最高帧率。
返回值
- 方法调用成功，返回设备支持的最高帧率，详见 SCREEN_CAPTURE_FRAMERATE_CAPABILITY。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
release
C++
virtual void release() = 0;
获取可共享窗口和屏幕列表后，为避免内存泄漏，请调用该方法释放 IScreenCaptureSourceList，而不是直接删除该对象。
信息
该方法仅适用于 macOS 和 Windows 平台。
setExternalMediaProjection
配置 SDK 外部的 MediaProjection 以采集屏幕视频流。
C++
virtual int setExternalMediaProjection(void* mediaProjection) = 0;
调用该方法后，你设置的外部 MediaProjection 将替代 SDK 申请的 MediaProjection 用于采集屏幕视频流。当屏幕共享停止或 IRtcEngine 被销毁时，SDK 会自动释放该 MediaProjection。
信息
调用该方法前，你必须先申请
MediaProjection 权限。该方法仅适用于 Android 平台。适用场景
如果你已申请到
MediaProjection，可以直接使用你自己的 MediaProjection，而无需使用 SDK 申请的对象。适用场景包括： - 在定制系统设备上，避免系统弹窗（如用户授权采集屏幕）并直接开始采集屏幕视频流。
- 在涉及一个或多个子进程的屏幕共享流程中，避免在子进程中创建对象时可能出现的错误，从而防止屏幕采集失败。
调用时机
在调用 startScreenCapture 之后调用该方法。
参数
- mediaProjection
- 用于采集屏幕视频流的
MediaProjection对象。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setScreenCaptureContentHint
设置屏幕共享的内容提示。
C++
virtual int setScreenCaptureContentHint(VIDEO_CONTENT_HINT contentHint) = 0;
该方法用于设置屏幕共享的内容类型提示，以便 SDK 针对不同类型的内容应用相应的优化算法。如果你未调用该方法，默认内容提示为 CONTENT_HINT_NONE。
信息
你可以在开始或停止屏幕共享之前或之后调用此方法。
参数
- contentHint
- 屏幕共享的内容提示，详见 VIDEO_CONTENT_HINT。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数无效。
- -8：屏幕共享状态无效，可能是因为你已共享了其他屏幕或窗口。请调用
stopScreenCapture停止当前共享后重新开始。
setScreenCaptureScenario
设置屏幕共享场景。
C++
virtual int setScreenCaptureScenario(SCREEN_SCENARIO_TYPE screenScenario) = 0;
调用该方法设置屏幕共享场景，SDK 会根据场景自动优化共享的视频质量和用户体验。
信息
建议在加入频道前调用此方法。
参数
- screenScenario
- 屏幕共享场景。详见 SCREEN_SCENARIO_TYPE。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
startScreenCapture [1/2]
开始屏幕采集。
C++
virtual int startScreenCapture(const ScreenCaptureParameters2& captureParams) = 0;
你可以在加入频道前或后调用该方法，具体如下：
- 先调用该方法，再调用
joinChannel加入频道，并将publishScreenCaptureVideo设置为 true，以开始屏幕共享。 - 加入频道后调用该方法，再调用 updateChannelMediaOptions 并将
publishScreenCaptureVideo设置为 true，以开始屏幕共享。
信息
- 该方法仅适用于 Android 和 iOS 平台。
- 在 iOS 平台，屏幕共享仅支持 iOS 12.0 及以上版本。
- 如果你使用自定义音频源而非 SDK 采集音频，声网建议你在应用中添加保活处理逻辑，以避免应用进入后台后屏幕共享中断。
- 该功能对设备性能要求较高，声网建议你在 iPhone X 及以上机型上使用。
- 该方法依赖 iOS 屏幕共享动态库
AgoraReplayKitExtension.xcframework。如果该动态库被删除，屏幕共享将无法正常启用。 - 在 Android 平台，如果用户未授予应用屏幕采集权限，SDK 会触发 onPermissionError
(2)回调。 - 在 Android 9 及以上版本，为避免应用进入后台后被系统杀死，声网建议你在
/app/Manifests/AndroidManifest.xml文件中添加前台服务权限android.permission.FOREGROUND_SERVICE。 - 由于性能限制，Android TV 不支持屏幕共享。
- 由于系统限制，使用华为手机时，请勿在屏幕共享过程中调整屏幕共享流的视频编码分辨率，否则可能导致崩溃。
- 由于系统限制，部分小米设备在屏幕共享时不支持采集系统音频。
- 为避免屏幕共享时系统音频采集失败，声网建议你在加入频道前通过 setAudioScenario 方法将音频应用场景设置为
AUDIO_SCENARIO_GAME_STREAMING。 - 屏幕共享流的计费基于 ScreenVideoParameters 中的
dimensions：- 如果你未传入该值，声网按 1280 × 720 计费。
- 如果你传入该值，声网按该值计费。
适用场景
在屏幕共享场景中。
参数
- captureParams
- 屏幕共享的编码参数，详见 ScreenCaptureParameters2。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2（iOS 平台）：参数为 NULL。
- -2（Android 平台）：系统版本过低。请确保 Android API 级别不低于 21。
- -3（Android 平台）：无法采集系统音频。请确保 Android API 级别不低于 29。
startScreenCapture [2/2]
从指定的视频源开始屏幕采集。
C++
virtual int startScreenCapture(VIDEO_SOURCE_TYPE sourceType, const ScreenCaptureConfiguration& config) = 0;
该方法支持从指定的视频源开始屏幕采集，适用于多频道或本地合图等场景。声网 SDK 提供多种屏幕采集方法，请根据实际需求选择：
- startScreenCapture [1/2] / startScreenCaptureByDisplayId / startScreenCaptureByWindowId：仅支持采集单个屏幕或窗口，适用于只共享一个屏幕的场景。
- startScreenCapture [2/2]：支持指定多个视频源采集多个屏幕共享流，适用于本地合图或多频道场景。
信息
- 如果通过该方法开始屏幕采集，你需要调用
stopScreenCapture停止屏幕采集。 - 在 Windows 平台上，最多支持四路屏幕采集视频流。
- 在 macOS 平台上，仅支持一路屏幕采集视频流。
- 该方法仅适用于 macOS 和 Windows 平台。
适用场景
适用于屏幕共享场景，支持多频道使用。
调用时机
你可以在加入频道前或后调用该方法，具体如下：
- 先调用该方法，再调用
joinChannel加入频道，并将publishScreenCaptureVideo设置为 true，以开始屏幕共享。 - 加入频道后调用该方法，再调用 updateChannelMediaOptions 并将
publishScreenCaptureVideo设置为 true，以开始屏幕共享。
参数
- sourceType
- 视频源的类型，详见 VIDEO_SOURCE_TYPE。信息在 macOS 平台上，该参数只能设置为
VIDEO_SOURCE_SCREEN（2）。 - config
- 屏幕采集的配置，详见 ScreenCaptureConfiguration。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
startScreenCaptureByDisplayId
通过指定屏幕 ID 采集屏幕。
C++
virtual int startScreenCaptureByDisplayId(int64_t displayId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0;
信息
该方法仅适用于 Windows 和 macOS 平台。
适用场景
在屏幕共享场景中，你需要调用此方法开始采集屏幕视频流。
调用时机
你可以在加入频道前或加入频道后调用该方法，具体区别如下：
- 在加入频道前调用该方法，然后调用
joinChannel加入频道，并将publishScreenTrack或publishSecondaryScreenTrack设置为 true，以开始屏幕共享。 - 在加入频道后调用该方法，然后调用 updateChannelMediaOptions 并将
publishScreenTrack或publishSecondaryScreenTrack设置为 true，以开始屏幕共享。
参数
- displayId
- 要共享的屏幕的屏幕 ID。信息在 Windows 平台，如果需要同时共享两个屏幕（主屏幕和副屏幕），可以在调用该方法时将
displayId设置为-1。 - regionRect
- （可选）设置相对于屏幕的区域位置。传入 NULL 表示共享整个屏幕。详见 Rectangle。
- captureParams
- 屏幕共享配置。默认视频尺寸为 1920 × 1080，即 2,073,600 像素。声网会根据该参数的值计算费用。屏幕共享视频流的视频属性只需通过该参数设置，与 setVideoEncoderConfiguration 无关。详见 ScreenCaptureParameters。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数无效。
- -8：屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请调用
stopScreenCapture停止当前共享后重新开始。
startScreenCaptureByScreenRect
通过指定屏幕区域采集整个屏幕或部分屏幕。
C++
virtual int startScreenCaptureByScreenRect(const Rectangle& screenRect, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) __deprecated = 0;
废弃
你可以通过该方法共享整个屏幕或部分屏幕，需要指定要共享的屏幕区域。你可以在加入频道前或加入频道后调用该方法：
- 加入频道前调用该方法，然后调用
joinChannel加入频道，并将publishScreenTrack或publishSecondaryScreenTrack设置为 true，以开始屏幕共享。 - 加入频道后调用该方法，然后调用 updateChannelMediaOptions，并将
publishScreenTrack或publishSecondaryScreenTrack设置为 true，以开始屏幕共享。
信息
该方法仅适用于 Windows 平台。
参数
- screenRect
- 屏幕相对于虚拟屏幕的位置。详见 Rectangle。
- regionRect
- （可选）区域相对于屏幕的位置。详见 Rectangle。如果未设置该参数，SDK 会共享整个屏幕。如果指定的区域超出屏幕范围，SDK 仅共享屏幕内的部分；如果设置的宽或高为 0，SDK 会共享整个屏幕。
- captureParams
- 屏幕共享的编码参数。默认视频分辨率为 1920 × 1080（即 2,073,600 像素）。声网会根据该参数的值计算费用。详见 ScreenCaptureParameters。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数无效。
- -8：屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请调用
stopScreenCapture停止当前共享后重新开始。
startScreenCaptureByWindowId
通过指定窗口 ID 采集整个或部分窗口。
C++
virtual int startScreenCaptureByWindowId(int64_t windowId, const Rectangle& regionRect, const ScreenCaptureParameters& captureParams) = 0;
该方法支持通过指定窗口 ID 采集整个或部分窗口，支持 UWP（通用 Windows 平台）应用的窗口共享。 声网使用最新 SDK 对主流 UWP 应用进行了测试，详情如下：
| 系统版本 | 软件名称 | 兼容版本 | 是否支持 |
|---|---|---|---|
| Windows 10 | Chrome | 76.0.3809.100 | 否 |
| Office Word | 18.1903.1152.0 | 是 | |
| Office Excel | 18.1903.1152.0 | 否 | |
| Office PPT | 18.1903.1152.0 | 是 | |
| WPS Word | 11.1.0.9145 | 是 | |
| WPS Excel | 11.1.0.9145 | 是 | |
| WPS PPT | 11.1.0.9145 | 是 | |
| 系统自带的 Media Player | 所有版本 | 是 | |
| Windows 8 | Chrome | 所有版本 | 是 |
| Office Word | 所有版本 | 是 | |
| Office Excel | 所有版本 | 是 | |
| Office PPT | 所有版本 | 是 | |
| WPS Word | 11.1.0.9098 | 是 | |
| WPS Excel | 11.1.0.9098 | 是 | |
| WPS PPT | 11.1.0.9098 | 是 | |
| 系统自带的 Media Player | 所有版本 | 是 | |
| Windows 7 | Chrome | 73.0.3683.103 | 否 |
| Office Word | 所有版本 | 是 | |
| Office Excel | 所有版本 | 是 | |
| Office PPT | 所有版本 | 是 | |
| WPS Word | 11.1.0.9098 | 否 | |
| WPS Excel | 11.1.0.9098 | 否 | |
| WPS PPT | 11.1.0.9098 | 是 | |
| 系统自带的 Media Player | 所有版本 | 否 |
信息
startScreenCaptureByWindowId 依赖于 WGC（Windows 图形采集）或 GDI（图形设备接口）进行窗口共享。在 Windows 10 2004 之前的系统中，WGC 无法禁用鼠标采集。因此，在系统版本低于 Windows 10 2004 的设备上调用
captureMouseCursor(false) 可能无效。详见 ScreenCaptureParameters。 该方法仅适用于 macOS 和 Windows 平台。适用场景
在屏幕共享场景中，你需要调用该方法开始采集屏幕视频流。
调用时机
你可以在加入频道前或加入频道后调用该方法，具体如下：
- 在加入频道前调用该方法，然后调用
joinChannel加入频道，并将publishScreenTrack或publishSecondaryScreenTrack设置为 true 以开始屏幕共享。 - 在加入频道后调用该方法，然后调用 updateChannelMediaOptions 并将
publishScreenTrack或publishSecondaryScreenTrack设置为 true 以开始屏幕共享。
参数
- windowId
- 要共享的窗口的 ID。
- regionRect
- （可选）设置共享区域相对于屏幕的位置。
- 如果未设置该参数，SDK 共享整个屏幕。
- 如果指定区域超出窗口范围，SDK 仅共享窗口内的区域。
- 如果设置的宽或高为 0，SDK 共享整个窗口。
- captureParams
- 屏幕共享配置。默认视频分辨率为 1920 × 1080，即 2,073,600 像素。声网使用该参数的值计算费用。详见 ScreenCaptureParameters。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数无效。
- -8：屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请调用
stopScreenCapture停止当前共享后重新开始。
stopScreenCapture [1/2]
停止屏幕采集。
C++
virtual int stopScreenCapture() = 0;
如果你通过调用 startScreenCapture、startScreenCaptureByWindowId 或 startScreenCaptureByDisplayId 开始屏幕采集，则需要调用该方法停止屏幕采集。
适用场景
适用于以下场景：
- iOS：如果你通过调用
startScreenCapture:开始屏幕采集，则需要调用此方法停止屏幕采集。 - macOS：如果你通过调用
startScreenCaptureByWindowId:regionRect:captureParams:或startScreenCaptureByDisplayId:regionRect:captureParams:开始屏幕采集，则需要调用此方法停止屏幕采集。
调用时机
你可以在加入频道前或加入频道后调用该方法。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
stopScreenCapture [2/2]
停止来自指定视频源的视频采集。
C++
virtual int stopScreenCapture(VIDEO_SOURCE_TYPE sourceType) = 0;
如果你通过调用 startScreenCapture 开始了一个或多个屏幕的采集，则需要调用该方法停止屏幕采集，并通过 sourceType 参数指定要停止采集的屏幕。
信息
该方法仅适用于 macOS 和 Windows 平台。
调用时机
你可以在加入频道前或后调用此方法。
参数
- sourceType
- 视频源的类型，详见 VIDEO_SOURCE_TYPE。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
updateScreenCapture
更新屏幕采集参数。
C++
virtual int updateScreenCapture(const ScreenCaptureParameters2& captureParams) = 0;
如果在开启屏幕共享时未采集系统音频，之后希望更新参数并发布系统音频，可参考以下步骤：
- 调用该方法，并将
captureAudio设置为 true。 - 调用 updateChannelMediaOptions，并将
publishScreenCaptureAudio设置为 true，以发布通过屏幕采集的音频。
信息
- 该方法仅适用于 Android 和 iOS 平台。
- 在 iOS 平台上，屏幕共享仅支持 iOS 12.0 及以上版本。
参数
- captureParams
- 屏幕共享的编码参数。详见 ScreenCaptureParameters2。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数无效。
- -8：屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用
stopScreenCapture停止当前共享，然后重新开始共享屏幕。
updateScreenCaptureParameters
更新屏幕采集参数。
C++
virtual int updateScreenCaptureParameters(const ScreenCaptureParameters& captureParams) = 0;
信息
该方法仅适用于 Windows 和 macOS 平台。请在开始屏幕共享或窗口共享后调用该方法。
参数
- captureParams
- 屏幕共享的编码参数。屏幕共享流的视频属性仅需通过该参数设置，与 setVideoEncoderConfiguration 无关。详见 ScreenCaptureParameters。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数无效。
- -8：屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用
stopScreenCapture停止当前共享，然后重新开始共享屏幕。
updateScreenCaptureRegion
更新屏幕共享区域。
C++
virtual int updateScreenCaptureRegion(const Rectangle& regionRect) = 0;
调用时机
请在开始屏幕共享或窗口共享后调用此方法。
参数
- regionRect
- 屏幕共享区域相对于屏幕或窗口的位置。
- 如果不设置该参数，SDK 会共享整个屏幕或窗口。
- 如果设置的区域超出屏幕或窗口范围，SDK 仅共享其中的有效区域。
- 如果设置的宽度或高度为 0，SDK 会共享整个屏幕或窗口。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数无效。
- -8：屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用
stopScreenCapture停止当前共享，然后重新开始共享屏幕。