需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

屏幕采集

  • C++

更新时间不可用

getCount

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

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

注： getCount 方法仅适用于 macOS 和 Windows 平台。

返回值

方法调用成功，返回可共享窗口和屏幕的数量。

所属接口类

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：仅返回窗口信息。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

所属接口类

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 的高帧率时，建议你在共享前使用该方法查询设备支持的最高帧率。

返回值

所属接口类

release

释放 IScreenCaptureSourceList。

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 提供多种屏幕采集方法，请根据实际需求选择：

注：

  • 如果通过该方法开始屏幕采集，你需要调用 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;

废弃

自 v4.5.0 版本废弃，请改用 startScreenCaptureByDisplayId。

你可以通过该方法共享整个屏幕或部分屏幕，需要指定要共享的屏幕区域。你可以在加入频道前或加入频道后调用该方法：

  • 加入频道前调用该方法，然后调用 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 10Chrome76.0.3809.100否
Office Word18.1903.1152.0是
Office Excel18.1903.1152.0否
Office PPT18.1903.1152.0是
WPS Word11.1.0.9145是
WPS Excel11.1.0.9145是
WPS PPT11.1.0.9145是
系统自带的 Media Player所有版本是
Windows 8Chrome所有版本是
Office Word所有版本是
Office Excel所有版本是
Office PPT所有版本是
WPS Word11.1.0.9098是
WPS Excel11.1.0.9098是
WPS PPT11.1.0.9098是
系统自带的 Media Player所有版本是
Windows 7Chrome73.0.3683.103否
Office Word所有版本是
Office Excel所有版本是
Office PPT所有版本是
WPS Word11.1.0.9098否
WPS Excel11.1.0.9098否
WPS PPT11.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 共享整个窗口。

详见 Rectangle。

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;

如果在开启屏幕共享时未采集系统音频，之后希望更新参数并发布系统音频，可参考以下步骤：

  1. 调用该方法，并将 captureAudio 设置为 true。
  2. 调用 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 会共享整个屏幕或窗口。

详见 Rectangle。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。

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

    • -2：参数无效。
    • -8：屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 stopScreenCapture 停止当前共享，然后重新开始共享屏幕。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利