# 屏幕采集 (/zh-CN/api-reference/rtc/electron/video/screencapture)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## getScreenCaptureSources [#getscreencapturesources]
获取可共享的屏幕和窗口对象列表。
```ts
abstract getScreenCaptureSources(
thumbSize: Size,
iconSize: Size,
includeScreen: boolean
): ScreenCaptureSourceInfo[];
```
屏幕共享或窗口共享前,你可以调用该方法获取可共享的屏幕和窗口的对象列表,方便用户通过列表中的缩略图选择共享某个显示器的屏幕或某个窗口。列表中包含窗口 ID 和屏幕 ID 等重要信息,你可以获取到 ID 后再调用 [startScreenCaptureByWindowId](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebywindowid) 或 [startScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/electron/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/electron/class-screencapturesourceinfo) 数组。
### 所属接口类 [#所属接口类]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## setScreenCaptureContentHint [#setscreencapturecontenthint]
设置屏幕共享内容类型。
```ts
abstract setScreenCaptureContentHint(contentHint: VideoContentHint): number;
```
SDK 会根据不同的内容类型,使用不同的算法对共享效果进行优化。如果不调用该方法,SDK 会将屏幕共享的内容默认为 ContentHintNone,即无指定的内容类型。
:::note
注: 该方法在开始屏幕共享前后都能调用。
:::
### 参数 [#参数-1]
屏幕共享的内容类型。详见 [VideoContentHint](/zh-CN/api-reference/rtc/electron/enum-videocontenthint)。
### 返回值 [#返回值-1]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
### 所属接口类 [#所属接口类-1]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## setScreenCaptureScenario [#setscreencapturescenario]
设置屏幕共享的场景。
```ts
abstract setScreenCaptureScenario(screenScenario: ScreenScenarioType): number;
```
开启屏幕共享或窗口共享时,你可以调用该方法设置屏幕共享的场景,SDK 会根据你设置的场景调整共享画面的画质。
:::note
注: 声网建议你在加入频道前调用该方法。
:::
### 参数 [#参数-2]
屏幕共享的场景,详见 [ScreenScenarioType](/zh-CN/api-reference/rtc/electron/enum-screenscenariotype)。
### 返回值 [#返回值-2]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## startScreenCaptureBySourceType [#startscreencapturebysourcetype]
开始屏幕采集并指定视频源。
```ts
abstract startScreenCaptureBySourceType(
sourceType: VideoSourceType,
config: ScreenCaptureConfiguration
): number;
```
:::note
注: 该方法仅适用于 macOS 和 Windows 平台。
- 如果调用该方法开始屏幕采集,则停止屏幕采集时需要调用 [stopScreenCaptureBySourceType](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_stopscreencapture2)。
- 在 Windows 平台上,最多支持 4 路屏幕采集的视频流。
- 在 macOS 平台上,最多支持 1 路屏幕采集的视频流。
:::
### 适用场景 [#适用场景]
在屏幕共享场景下,你需要调用该方法开始采集屏幕视频流。
SDK 支持一系列开启屏幕采集的方法,它们之间存在以下区别,请根据实际场景选用:
- `startScreenCaptureByDisplayId`/`startScreenCaptureByWindowId`:仅支持采集单个屏幕或窗口,适合仅共享单个屏幕的场景。
- `startScreenCaptureBySourceType`:支持指定多个视频源,以采集多路屏幕共享流,用于本地合图或者多频道发布场景。
### 调用时机 [#调用时机]
该方法在加入频道前后均可调用,区别如下:
- 如果在加入频道前调用该方法,然后调用 [joinChannel](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 加入频道,并设置 `publishScreenCaptureVideo` 为 true,即可开始屏幕共享。
- 如果在加入频道后调用该方法,然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项,并设置 `publishScreenCaptureVideo` 为 true,即可开始屏幕共享。
### 参数 [#参数-3]
视频源的类型,详见 [VideoSourceType](/zh-CN/api-reference/rtc/electron/enum-videosourcetype)。
:::note
注: 在 macOS 平台上,仅支持将该参数设置为 VideoSourceScreen (2)。
:::
屏幕采集配置。详见 [ScreenCaptureConfiguration](/zh-CN/api-reference/rtc/electron/class-screencaptureconfiguration)。
### 返回值 [#返回值-3]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## startScreenCaptureByDisplayId [#startscreencapturebydisplayid]
开始采集指定屏幕的视频流。
```ts
abstract startScreenCaptureByDisplayId(
displayId: number,
regionRect: Rectangle,
captureParams: ScreenCaptureParameters
): number;
```
采集一个屏幕或该屏幕部分区域的视频流。
### 适用场景 [#适用场景-1]
在屏幕共享场景下,你需要调用该方法开始采集屏幕视频流。有关屏幕共享的实现方法,详见[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share)。
### 调用时机 [#调用时机-1]
该方法在加入频道前后均可调用,区别如下:
- 如果在加入频道前调用该方法,然后调用 [joinChannel](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 加入频道,并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 true,即可开始屏幕共享。
- 如果在加入频道后调用该方法,然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项,并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 true,即可开始屏幕共享。
### 参数 [#参数-4]
指定待共享的屏幕 ID。
:::note
注: 对于 Windows 平台,如果你需要同时共享两个屏幕(主屏 + 副屏),可以在调用该方法时,将 `displayId` 设置为 `-1`。
:::
(可选)指定待共享区域相对于整个屏幕的位置。如需共享整个屏幕,则填 `nil`。
屏幕共享的参数配置。默认的视频编码分辨率为 1920 × 1080,即 2073600 像素。该像素值为计费标准。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters)。
:::note
注: 屏幕共享流的视频属性只需通过该参数设置,与 [setVideoEncoderConfiguration](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。
:::
### 返回值 [#返回值-4]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
### 所属接口类 [#所属接口类-4]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## startScreenCaptureByScreenRect [#startscreencapturebyscreenrect]
开始采集指定屏幕区域的视频流。
```ts
abstract startScreenCaptureByScreenRect(
screenRect: Rectangle,
regionRect: Rectangle,
captureParams: ScreenCaptureParameters
): number;
```
:::error[废弃]
弃用: 该方法已废弃。请改用 [startScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebydisplayid)。如果你需要在设备外接其他显示屏的情况下开启屏幕共享,强烈建议你使用 [startScreenCaptureByDisplayId](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebydisplayid)。
:::
共享一个屏幕或该屏幕的部分区域。你需要在该方法中指定想要共享的屏幕区域。
该方法在加入频道前后均可调用,区别如下:
- 如果在加入频道前调用该方法,然后调用 [joinChannel](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 加入频道,并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 true,即可开始屏幕共享。
- 如果在加入频道后调用该方法,然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项,并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 true,即可开始屏幕共享。
:::note
注: 该方法仅适用于 Windows 平台。
:::
### 参数 [#参数-5]
指定待共享的屏幕相对于虚拟屏的位置。
指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 [Rectangle](/zh-CN/api-reference/rtc/electron/class-rectangle)。如果设置的共享区域超出了屏幕的边界,则只共享屏幕内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕。
屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters)。
### 返回值 [#返回值-5]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
### 所属接口类 [#所属接口类-5]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## startScreenCaptureByWindowId [#startscreencapturebywindowid]
开始采集指定窗口的视频流。
```ts
abstract startScreenCaptureByWindowId(
windowId: any,
regionRect: Rectangle,
captureParams: ScreenCaptureParameters
): number;
```
共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。
该方法支持共享通用 Windows 平台(UWP)应用窗口。声网使用最新版 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 | 所有版本 | 否 |
:::note
注: 该方法仅适用于 macOS 和 Windows 平台。
SDK 的窗口共享功能依赖于 WGC(Windows Graphics Capture)或 GDI(Graphics Device Interface)采集,WGC 在早于 Windows 10 2004 的系统上无法设置关闭鼠标采集,因此,当你在搭载早于 Windows 10 2004 系统的设备上进行窗口共享时,可能出现 `captureMouseCursor(false)` 不生效的现象。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters)。
:::
### 适用场景 [#适用场景-2]
在屏幕共享场景下,你需要调用该方法开始采集屏幕视频流。有关屏幕共享的实现方法,详见[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share)。
### 调用时机 [#调用时机-2]
该方法在加入频道前后均可调用,区别如下:
- 如果在加入频道前调用该方法,然后调用 [joinChannel](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 加入频道,并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 true,即可开始屏幕共享。
- 如果在加入频道后调用该方法,然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项,并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 true,即可开始屏幕共享。
### 参数 [#参数-6]
指定待共享的窗口 ID。
(可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 [Rectangle](/zh-CN/api-reference/rtc/electron/class-rectangle)。如果设置的共享区域超出了窗口的边界,则只共享窗口内的内容;如果宽或高为 0,则共享整个窗口。
:::note
注: Electron for 统信 OS SDK 暂不支持该参数。
:::
屏幕共享的参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters)。
### 返回值 [#返回值-6]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
### 所属接口类 [#所属接口类-6]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## stopScreenCapture [#stopscreencapture]
停止屏幕采集。
```ts
abstract stopScreenCapture(): number;
```
### 适用场景 [#适用场景-3]
如果你调用了 `startScreenCaptureBySourceType`、`startScreenCaptureByWindowId` 或 `startScreenCaptureByDisplayId` 开启屏幕采集,则停止屏幕采集时需要调用该方法。
### 调用时机 [#调用时机-3]
该方法在加入频道前后均可调用。
### 返回值 [#返回值-7]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-7]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## stopScreenCaptureBySourceType [#stopscreencapturebysourcetype]
停止对指定的视频源进行屏幕采集。
```ts
abstract stopScreenCaptureBySourceType(sourceType: VideoSourceType): number;
```
### 适用场景 [#适用场景-4]
如果你调用了 `startScreenCaptureBySourceType` 开启一路或多路屏幕采集,则停止屏幕采集时需要调用该方法,并通过 `sourceType` 参数指定屏幕。
### 调用时机 [#调用时机-4]
该方法在加入频道前后均可调用。
### 参数 [#参数-7]
视频源的类型,详见 [VideoSourceType](/zh-CN/api-reference/rtc/electron/enum-videosourcetype)。
### 返回值 [#返回值-8]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## updateScreenCaptureParameters [#updatescreencaptureparameters]
更新屏幕采集的参数配置。
```ts
abstract updateScreenCaptureParameters(
captureParams: ScreenCaptureParameters
): number;
```
:::note
注:
- 请在开启屏幕共享或窗口共享后调用该方法。
:::
### 参数 [#参数-8]
屏幕共享的编码参数配置。详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters)。
:::note
注: 屏幕共享流的视频属性只需通过该参数设置,与 [setVideoEncoderConfiguration](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。
:::
### 返回值 [#返回值-9]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
### 所属接口类 [#所属接口类-9]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## updateScreenCaptureRegion [#updatescreencaptureregion]
更新屏幕采集的区域。
```ts
abstract updateScreenCaptureRegion(regionRect: Rectangle): number;
```
:::note
注: 请在开启屏幕共享或窗口共享后调用该方法。
:::
### 参数 [#参数-9]
待共享区域相对于整个屏幕或窗口的位置,如不填,则表示共享整个屏幕或窗口。详见 [Rectangle](/zh-CN/api-reference/rtc/electron/class-rectangle)。如果设置的共享区域超出了屏幕或窗口的边界,则只共享屏幕或窗口内的内容;如果将 width 或 height 设为 0,则共享整个屏幕或窗口。
### 返回值 [#返回值-10]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:传入的参数无效。
- -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。
### 所属接口类 [#所属接口类-10]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)