# 屏幕采集 (/zh-CN/api-reference/rtc/macos/video/screencapture)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## getScreenCaptureSourcesWithThumbSize\:iconSize\:includeScreen: [#getscreencapturesourceswiththumbsizeiconsizeincludescreen]
获取可共享的屏幕和窗口列表。
```objc
- (NSArray* _Nullable)getScreenCaptureSourcesWithThumbSize:(NSSize)thumbSize iconSize:(NSSize)iconSize includeScreen:(BOOL)includeScreen NS_SWIFT_NAME(getScreenCaptureSources(withThumbSize:iconSize:includeScreen:));
```
你可以在共享屏幕或窗口前调用该方法,以获取可共享的屏幕和窗口列表。用户可以通过列表中的缩略图轻松选择要共享的特定屏幕或窗口。该列表还包含窗口 ID 和屏幕 ID 等信息,你可以使用这些信息调用 `startScreenCaptureByWindowId` 或 `startScreenCaptureByDisplayId` 开始共享。
### 参数 [#参数]
屏幕或窗口缩略图的目标尺寸(宽度和高度,单位为像素)。SDK 会对原始图像进行缩放,使图像最长边的长度与目标尺寸一致,同时不扭曲原始图像。例如,若原始图像为 400 × 300,`thumbSize` 为 100 × 100,则缩略图的实际尺寸为 100 × 75。如果目标尺寸大于原始尺寸,则缩略图为原始图像,SDK 不进行缩放。
应用程序图标的目标尺寸(宽度和高度,单位为像素)。SDK 会对原始图像进行缩放,使图像最长边的长度与目标尺寸一致,同时不扭曲原始图像。例如,若原始图像为 400 × 300,`iconSize` 为 100 × 100,则图标的实际尺寸为 100 × 75。如果目标尺寸大于原始尺寸,则图标为原始图像,SDK 不进行缩放。
是否返回屏幕信息:
- YES:返回屏幕和窗口信息。
- NO:仅返回窗口信息。
### 返回值 [#返回值]
- 方法调用成功,返回 [AgoraScreenCaptureSourceInfo](/zh-CN/api-reference/rtc/macos/class-screencapturesourceinfo) 对象数组,详见 [AgoraScreenCaptureSourceInfo](/zh-CN/api-reference/rtc/macos/class-screencapturesourceinfo)。
- 方法调用失败,返回 nil。
### 所属接口类 [#所属接口类]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## setScreenCaptureScenario: [#setscreencapturescenario]
设置屏幕共享场景。
```objc
- (int)setScreenCaptureScenario:(AgoraScreenScenarioType)scenarioType NS_SWIFT_NAME(setScreenCaptureScenario(_:));
```
调用该方法设置屏幕共享场景。SDK 会根据设置的场景优化共享的视频质量和用户体验。
:::note
注: 声网建议你在加入频道前调用此方法。
:::
### 参数 [#参数-1]
屏幕共享场景。详见 [AgoraScreenScenarioType](/zh-CN/api-reference/rtc/macos/enum-screenscenariotype)。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## startScreenCapture\:config: [#startscreencaptureconfig]
开始屏幕共享。
```objc
- (int)startScreenCapture:(AgoraVideoSourceType)sourceType config:(AgoraScreenCaptureConfiguration * _Nullable)config NS_SWIFT_NAME(startScreenCapture(_:config:));
```
### 适用场景 [#适用场景]
适用于屏幕共享场景,支持多频道使用。
### 参数 [#参数-2]
屏幕来源类型,详见 [AgoraVideoSourceType](/zh-CN/api-reference/rtc/macos/enum-videosourcetype)。
屏幕共享的配置,详见 [AgoraScreenCaptureConfiguration](/zh-CN/api-reference/rtc/macos/class-screencaptureconfiguration)。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## startScreenCaptureByDisplayId\:regionRect\:captureParams: [#startscreencapturebydisplayidregionrectcaptureparams]
通过指定屏幕 ID 采集屏幕。
```objc
- (int)startScreenCaptureByDisplayId:(UInt32)displayId
regionRect:(CGRect)regionRect
captureParams:(AgoraScreenCaptureParameters *_Nonnull)captureParams NS_SWIFT_NAME(startScreenCapture(byDisplayId:regionRect:captureParams:));
```
采集整个屏幕或部分屏幕区域的视频流。该方法仅创建主屏幕视频轨道。
### 适用场景 [#适用场景-1]
在屏幕共享场景中,你需要调用此方法开始采集屏幕视频流。
### 调用时机 [#调用时机]
你可以在加入频道前或加入频道后调用此方法,具体区别如下:
- 在加入频道前调用此方法,然后调用 `joinChannelByToken` 加入频道,并将 `publishScreenTrack` 设置为 YES,以开始屏幕共享。
- 在加入频道后调用此方法,然后调用 [updateChannelWithMediaOptions:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatechannelmediaoptions) 并将 `publishScreenTrack` 设置为 YES,以开始屏幕共享。
### 参数 [#参数-3]
要共享的屏幕的屏幕 ID。
(可选)相对于窗口的区域位置。如果未设置该参数,SDK 共享整个窗口。该参数包含以下字段:
- `x`:距窗口左上角的水平偏移。
- `y`:距窗口左上角的垂直偏移。
- `width`:区域的宽度。
- `height`:区域的高度。
如果指定的区域超出窗口范围,SDK 仅共享窗口内的区域;如果设置 `width` 或 `height` 为 0,SDK 共享整个窗口。
屏幕共享配置。默认视频分辨率为 1920 × 1080,即 2,073,600 像素。声网会根据该参数的值计算费用。屏幕共享视频流的视频属性仅需通过该参数设置,与 [setVideoEncoderConfiguration:](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。详见 [AgoraScreenCaptureParameters](/zh-CN/api-reference/rtc/macos/class-screencaptureparameters)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:参数无效。
- -8:屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,然后重新开始屏幕共享。
### 所属接口类 [#所属接口类-3]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## startScreenCaptureByWindowId\:regionRect\:captureParams: [#startscreencapturebywindowidregionrectcaptureparams]
通过指定窗口 ID 采集整个或部分窗口的屏幕内容。
```objc
- (int)startScreenCaptureByWindowId:(UInt32)windowId
regionRect:(CGRect)regionRect
captureParams:(AgoraScreenCaptureParameters *_Nonnull)captureParams NS_SWIFT_NAME(startScreenCapture(byWindowId:regionRect:captureParams:));
```
你需要指定要采集的窗口的 ID,可以采集整个窗口或窗口的部分区域。
:::note
注: 该方法仅适用于 macOS 和 Windows 平台。
该方法仅创建主屏幕视频轨道。
:::
### 适用场景 [#适用场景-2]
在屏幕共享场景中,你需要调用该方法开始采集屏幕视频流。
### 调用时机 [#调用时机-1]
你可以在加入频道前或加入频道后调用该方法,具体如下:
- 在加入频道前调用该方法,然后调用 `joinChannelByToken` 加入频道,并将 `publishScreenTrack` 设置为 YES,以开始屏幕共享。
- 在加入频道后调用该方法,然后调用 [updateChannelWithMediaOptions:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatechannelmediaoptions) 并将 `publishScreenTrack` 设置为 YES,以开始屏幕共享。
### 参数 [#参数-4]
要共享的窗口的 ID。
(可选)相对于窗口的区域位置。如果未设置该参数,SDK 会共享整个窗口。该参数包含以下字段:
- x:距窗口左上角的水平偏移。
- y:距窗口左上角的垂直偏移。
- width:区域的宽度。
- height:区域的高度。
如果指定的区域超出窗口范围,SDK 只共享窗口内的区域;如果设置 width 或 height 为 0,SDK 会共享整个窗口。
屏幕共享配置。默认视频分辨率为 1920 × 1080,即 2,073,600 像素。声网会根据该参数的值计算费用。详见 [AgoraScreenCaptureParameters](/zh-CN/api-reference/rtc/macos/class-screencaptureparameters)。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:参数无效。
- -8:屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,然后重新开始共享屏幕。
### 所属接口类 [#所属接口类-4]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## stopScreenCapture [#stopscreencapture]
停止屏幕采集。
```objc
- (int)stopScreenCapture NS_SWIFT_NAME(stopScreenCapture());
```
### 适用场景 [#适用场景-3]
适用于以下场景:
- iOS:如果你通过调用 `startScreenCapture:` 开始屏幕采集,则需要调用此方法停止屏幕采集。
- macOS:如果你通过调用 `startScreenCaptureByWindowId:regionRect:captureParams:` 或 `startScreenCaptureByDisplayId:regionRect:captureParams:` 开始屏幕采集,则需要调用此方法停止屏幕采集。
### 调用时机 [#调用时机-2]
你可以在加入频道前或后调用此方法。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## stopScreenCapture: [#stopscreencapture-1]
停止来自指定视频源的屏幕采集。
```objc
- (int)stopScreenCapture:(AgoraVideoSourceType)sourceType NS_SWIFT_NAME(stopScreenCapture(_:));
```
调用 [startScreenCapture\:config:](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_startscreencapture2) 开始从一个或多个屏幕采集屏幕后,需调用此方法停止屏幕采集。你需要通过 `sourceType` 参数指定要停止的屏幕。
### 调用时机 [#调用时机-3]
你可以在加入频道前或后调用此方法。
### 参数 [#参数-5]
视频源的类型,详见 [AgoraVideoSourceType](/zh-CN/api-reference/rtc/macos/enum-videosourcetype)。
### 返回值 [#返回值-6]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## updateScreenCaptureParameters: [#updatescreencaptureparameters]
更新屏幕采集参数。
```objc
- (int)updateScreenCaptureParameters:(AgoraScreenCaptureParameters * _Nonnull)captureParams NS_SWIFT_NAME(updateScreenCaptureParameters(_:));
```
:::note
注: 请在开始屏幕共享或窗口共享后调用此方法。
:::
### 参数 [#参数-6]
屏幕共享的编码参数。屏幕共享流的视频属性只需通过该参数设置,与 [setVideoEncoderConfiguration:](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。详见 [AgoraScreenCaptureParameters](/zh-CN/api-reference/rtc/macos/class-screencaptureparameters)。
### 返回值 [#返回值-7]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:参数无效。
- -8:屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,然后重新开始共享屏幕。
### 所属接口类 [#所属接口类-7]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## updateScreenCaptureRegion: [#updatescreencaptureregion]
更新屏幕采集区域。
```objc
- (int)updateScreenCaptureRegion:(CGRect)rect NS_SWIFT_NAME(updateScreenCaptureRegion(_:));
```
你可以通过该方法更新屏幕或窗口的采集区域。
### 参数 [#参数-7]
相对于屏幕或窗口的区域位置。
- 如果不设置该参数,SDK 会共享整个屏幕。
- 如果指定的区域超出屏幕或窗口范围,SDK 仅共享其中的区域。
- 如果设置的宽度或高度为 0,SDK 会共享整个屏幕或窗口。
### 返回值 [#返回值-8]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)