# 屏幕采集 (/zh-CN/api-reference/rtc/csharp-windows/video/screencapture)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## GetScreenCaptureSources [#getscreencapturesources]
获取可共享的屏幕和窗口对象列表。
```csharp
public abstract ScreenCaptureSourceInfo[] GetScreenCaptureSources(SIZE thumbSize, SIZE iconSize, bool includeScreen);
```
### 详情 [#详情]
屏幕共享或窗口共享前,你可以调用该方法获取可共享的屏幕和窗口的对象列表,方便用户通过列表中的缩略图选择共享某个显示器的屏幕或某个窗口。列表中包含窗口 ID 和屏幕 ID 等重要信息,你可以获取到 ID 后再调用 [StartScreenCaptureByWindowId](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_startscreencapturebywindowid) 或 [StartScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 开启共享。
### 参数 [#参数]
屏幕或窗口的缩略图的目标尺寸(宽高单位为像素)。SDK 会在保证原图不变形的前提下,缩放原图,使图片最长边和目标尺寸的最长边的长度一致。例如,原图宽高为 400 × 300,thumbSize 为 100 x 100,缩略图实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸,缩略图即为原图,SDK 不进行缩放操作。
程序所对应的图标的目标尺寸(宽高单位为像素)。SDK 会在保证原图不变形的前提下,缩放原图,使图片最长边和目标尺寸的最长边的长度一致。例如,原图宽高为 400 × 300,iconSize 为 100 × 100,图标实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸,图标即为原图,SDK 不进行缩放操作。
除了窗口信息外,SDK 是否返回屏幕信息:
- `true`:SDK 返回屏幕和窗口信息。
- `false`:SDK 仅返回窗口信息。
### 返回值 [#返回值]
[ScreenCaptureSourceInfo](/zh-CN/api-reference/rtc/csharp-windows/class-screencapturesourceinfo) 数组。
## QueryScreenCaptureCapability [#queryscreencapturecapability]
查询设备在屏幕共享时支持的最高帧率。
```csharp
public abstract int QueryScreenCaptureCapability();
```
### 详情 [#详情-1]
### 适用场景 [#适用场景]
在屏幕共享场景下,如果你想启用高帧率(如 60 fps)、但不确定设备是否支持时,可以先调用该方法查询设备支持的最高帧率。如果设备不支持高帧率,你可以在开启屏幕共享时适当调低屏幕共享流的帧率,以确保共享场景的效果符合预期。
### 返回值 [#返回值-1]
- 方法调用成功时,返回设备支持的最高帧率。详见 SCREEN_CAPTURE_FRAMERATE_CAPABILITY。
- <0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
## SetScreenCaptureContentHint [#setscreencapturecontenthint]
设置屏幕共享内容类型。
```csharp
public abstract int SetScreenCaptureContentHint(VIDEO_CONTENT_HINT contentHint);
```
### 详情 [#详情-2]
SDK 会根据不同的内容类型,使用不同的算法对共享效果进行优化。如果不调用该方法,SDK 会将屏幕共享的内容默认为 CONTENT_HINT_NONE,即无指定的内容类型。
:::caution
注意: 该方法在开始屏幕共享前后都能调用。
:::
### 参数 [#参数-1]
屏幕共享的内容类型。详见 [VIDEO_CONTENT_HINT](/zh-CN/api-reference/rtc/csharp-windows/enum-videocontenthint)。
### 返回值 [#返回值-2]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [StopScreenCapture [1/2]](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
### 所属接口类 [#所属接口类]
- [IRtcEngine](/zh-CN/api-reference/rtc/csharp-windows/rtc-interface-class#class_irtcengine)
## SetScreenCaptureScenario [#setscreencapturescenario]
设置屏幕共享的场景。
```csharp
public abstract int SetScreenCaptureScenario(SCREEN_SCENARIO_TYPE screenScenario);
```
### 详情 [#详情-3]
开启屏幕共享或窗口共享时,你可以调用该方法设置屏幕共享的场景,SDK 会根据你设置的场景调整共享画面的画质。
:::note
注: 声网建议你在加入频道前调用该方法。
:::
### 参数 [#参数-2]
屏幕共享的场景,详见 [SCREEN_SCENARIO_TYPE](/zh-CN/api-reference/rtc/csharp-windows/enum-screenscenariotype)。
### 返回值 [#返回值-3]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [IRtcEngine](/zh-CN/api-reference/rtc/csharp-windows/rtc-interface-class#class_irtcengine)
## StartScreenCapture [2/2] [#startscreencapture-22]
开始屏幕采集并指定视频源。
```csharp
public abstract int StartScreenCapture(VIDEO_SOURCE_TYPE sourceType, ScreenCaptureConfiguration config);
```
:::caution
注意: 该方法仅适用于 macOS 和 Windows 平台。
:::
### 适用场景 [#适用场景-1]
在屏幕共享场景下,你需要调用该方法开始采集屏幕视频流。
SDK 支持一系列开启屏幕采集的方法,它们之间存在以下区别,请根据实际场景选用:
- [StartScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_startscreencapturebydisplayid)/[StartScreenCaptureByWindowId](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_startscreencapturebywindowid):仅支持采集单个屏幕或窗口,适合仅共享单个屏幕的场景。
- [StartScreenCapture [2/2]](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_startscreencapture2):支持指定多个视频源,以采集多路屏幕共享流,用于本地合图或者多频道发布场景。
### 调用时机 [#调用时机]
该方法在加入频道前后均可调用,区别如下:
- 如果在加入频道前调用该方法,然后调用 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/csharp-windows/channel#api_irtcengine_joinchannel2) 加入频道,并设置 publishScreenCaptureVideo 为 `true`,即可开始屏幕共享。
- 如果在加入频道后调用该方法,然后调用 [UpdateChannelMediaOptions](/zh-CN/api-reference/rtc/csharp-windows/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项,并设置 publishScreenCaptureVideo 为 `true`,即可开始屏幕共享。
### 调用限制 [#调用限制]
- 如果调用该方法开始屏幕采集,则停止屏幕采集时需要调用 [StopScreenCapture [2/2]](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_stopscreencapture2)。
- 在 Windows 平台上,最多支持 4 路屏幕采集的视频流。
### 参数 [#参数-3]
视频源的类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/csharp-windows/enum-videosourcetype)。
屏幕采集配置。详见 [ScreenCaptureConfiguration](/zh-CN/api-reference/rtc/csharp-windows/class-screencaptureconfiguration)。
### 返回值 [#返回值-4]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
## StartScreenCaptureByDisplayId [#startscreencapturebydisplayid]
开始采集指定屏幕的视频流。
```csharp
public abstract int StartScreenCaptureByDisplayId(uint displayId, Rectangle regionRect, ScreenCaptureParameters captureParams);
```
采集一个屏幕或该屏幕部分区域的视频流。
### 适用场景 [#适用场景-2]
在屏幕共享场景下,你需要调用该方法开始采集屏幕视频流。有关屏幕共享的实现方法,详见[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share)。
### 调用时机 [#调用时机-1]
该方法在加入频道前后均可调用,区别如下:
- 如果在加入频道前调用该方法,然后调用 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/csharp-windows/channel#api_irtcengine_joinchannel2) 加入频道,并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`,即可开始屏幕共享。
- 如果在加入频道后调用该方法,然后调用 [UpdateChannelMediaOptions](/zh-CN/api-reference/rtc/csharp-windows/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项,并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`,即可开始屏幕共享。
### 调用限制 [#调用限制-1]
无。
### 参数 [#参数-4]
指定待共享的屏幕 ID。
(可选)指定待共享区域相对于整个屏幕的位置。如需共享整个屏幕,则填 `nil`。详见 [Rectangle](/zh-CN/api-reference/rtc/csharp-windows/class-rectangle)。
如果设置的共享区域超出了屏幕的边界,则只共享屏幕内的内容;如果宽或高设为 0,则共享整个屏幕。
屏幕共享的参数配置。默认的视频编码分辨率为 1920 × 1080,即 2073600 像素。该像素值为计费标准。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/csharp-windows/class-screencaptureparameters)。
:::caution
注意: 屏幕共享流的视频属性只需通过该参数设置,与 [SetVideoEncoderConfiguration](/zh-CN/api-reference/rtc/csharp-windows/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。
:::
### 返回值 [#返回值-5]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [StopScreenCapture [1/2]](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
## StartScreenCaptureByScreenRect [#startscreencapturebyscreenrect]
开始采集指定屏幕区域的视频流。
```csharp
public abstract int StartScreenCaptureByScreenRect(Rectangle screenRect, Rectangle regionRect,
ScreenCaptureParameters captureParams);
```
### 详情 [#详情-4]
:::error[弃用:]
该方法已废弃。请改用 [StartScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_startscreencapturebydisplayid)。如果你需要在设备外接其他显示屏的情况下开启屏幕共享,强烈建议你使用 StartScreenCaptureByDisplayId。
:::
共享一个屏幕或该屏幕的部分区域。你需要在该方法中指定想要共享的屏幕区域。
该方法在加入频道前后均可调用,区别如下:
- 如果在加入频道前调用该方法,然后调用 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/csharp-windows/channel#api_irtcengine_joinchannel2) 加入频道,并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`,即可开始屏幕共享。
- 如果在加入频道后调用该方法,然后调用 [UpdateChannelMediaOptions](/zh-CN/api-reference/rtc/csharp-windows/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项,并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`,即可开始屏幕共享。
### 参数 [#参数-5]
指定待共享的屏幕相对于虚拟屏的位置。
(可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 [Rectangle](/zh-CN/api-reference/rtc/csharp-windows/class-rectangle)。如果设置的共享区域超出了屏幕的边界,则只共享屏幕内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕。
屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/csharp-windows/class-screencaptureparameters)。
### 返回值 [#返回值-6]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [StopScreenCapture [1/2]](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
## StartScreenCaptureByWindowId [#startscreencapturebywindowid]
开始采集指定窗口的视频流。
```csharp
public abstract int StartScreenCaptureByWindowId(long windowId, Rectangle regionRect, ScreenCaptureParameters captureParams);
```
共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。
:::caution
注意: 该方法仅适用于 macOS 和 Windows 平台。
:::
该方法支持共享通用 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(系统自带) |
全部 |
否 |
### 适用场景 [#适用场景-3]
在屏幕共享场景下,你需要调用该方法开始采集屏幕视频流。有关屏幕共享的实现方法,详见[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share)。
### 调用时机 [#调用时机-2]
该方法在加入频道前后均可调用,区别如下:
- 如果在加入频道前调用该方法,然后调用 [JoinChannel [2/2]](/zh-CN/api-reference/rtc/csharp-windows/channel#api_irtcengine_joinchannel2) 加入频道,并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`,即可开始屏幕共享。
- 如果在加入频道后调用该方法,然后调用 [UpdateChannelMediaOptions](/zh-CN/api-reference/rtc/csharp-windows/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项,并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 `true`,即可开始屏幕共享。
### 调用限制 [#调用限制-2]
SDK 的窗口共享功能依赖于 WGC(Windows Graphics Capture)或 GDI(Graphics Device Interface)采集,WGC 在早于 Windows 10 2004 的系统上无法设置关闭鼠标采集,因此,当你在搭载早于 Windows 10 2004 系统的设备上进行窗口共享时,可能出现 `captureMouseCursor(false)` 不生效的现象。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/csharp-windows/class-screencaptureparameters)。
### 参数 [#参数-6]
指定待共享的窗口 ID。
(可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 [Rectangle](/zh-CN/api-reference/rtc/csharp-windows/class-rectangle)。如果设置的共享区域超出了窗口的边界,则只共享窗口内的内容;如果宽或高为 0,则共享整个窗口。
屏幕共享的参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/csharp-windows/class-screencaptureparameters)。
### 返回值 [#返回值-7]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [StopScreenCapture [1/2]](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
## StopScreenCapture [1/2] [#stopscreencapture-12]
停止屏幕采集。
```csharp
public abstract int StopScreenCapture();
```
### 适用场景 [#适用场景-4]
如果你调用了 [StartScreenCaptureByWindowId](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_startscreencapturebywindowid) 或 [StartScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 开启屏幕采集,则停止屏幕采集时需要调用该方法。
### 调用时机 [#调用时机-3]
该方法在加入频道前后均可调用。
### 调用限制 [#调用限制-3]
无。
### 返回值 [#返回值-8]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [IRtcEngine](/zh-CN/api-reference/rtc/csharp-windows/rtc-interface-class#class_irtcengine)
## StopScreenCapture [2/2] [#stopscreencapture-22]
停止对指定的视频源进行屏幕采集。
```csharp
public abstract int StopScreenCapture(VIDEO_SOURCE_TYPE sourceType);
```
### 适用场景 [#适用场景-5]
如果你调用了 [StartScreenCapture [2/2]](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_startscreencapture2) 开启一路或多路屏幕采集,则停止屏幕采集时需要调用该方法,并通过 sourceType 参数指定屏幕。
### 调用时机 [#调用时机-4]
该方法在加入频道前后均可调用。
### 调用限制 [#调用限制-4]
无。
### 参数 [#参数-7]
视频源的类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/csharp-windows/enum-videosourcetype)。
### 返回值 [#返回值-9]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
## UpdateScreenCaptureParameters [#updatescreencaptureparameters]
更新屏幕采集的参数配置。
```csharp
public abstract int UpdateScreenCaptureParameters(ScreenCaptureParameters captureParams);
```
### 详情 [#详情-5]
:::caution
注意:
- 请在开启屏幕共享或窗口共享后调用该方法。
:::
### 参数 [#参数-8]
屏幕共享的编码参数配置。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/csharp-windows/class-screencaptureparameters)。
:::caution
注意: 屏幕共享流的视频属性只需通过该参数设置,与 [SetVideoEncoderConfiguration](/zh-CN/api-reference/rtc/csharp-windows/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。
:::
### 返回值 [#返回值-10]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [StopScreenCapture [1/2]](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
### 所属接口类 [#所属接口类-3]
- [IRtcEngine](/zh-CN/api-reference/rtc/csharp-windows/rtc-interface-class#class_irtcengine)
## UpdateScreenCaptureRegion [#updatescreencaptureregion]
更新屏幕采集的区域。
```csharp
public abstract int UpdateScreenCaptureRegion(Rectangle regionRect);
```
### 详情 [#详情-6]
:::caution
注意: 请在开启屏幕共享或窗口共享后调用该方法。
:::
### 参数 [#参数-9]
待共享区域相对于整个屏幕或窗口的位置,如不填,则表示共享整个屏幕或窗口。详见 [Rectangle](/zh-CN/api-reference/rtc/csharp-windows/class-rectangle)。如果设置的共享区域超出了屏幕或窗口的边界,则只共享屏幕或窗口内的内容;如果将 width 或 height 设为 0,则共享整个屏幕或窗口。
### 返回值 [#返回值-11]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [StopScreenCapture [1/2]](/zh-CN/api-reference/rtc/csharp-windows/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
### 所属接口类 [#所属接口类-4]
- [IRtcEngine](/zh-CN/api-reference/rtc/csharp-windows/rtc-interface-class#class_irtcengine)