# 屏幕采集 (/zh-CN/api-reference/rtc/macos/video/screencapture)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_screencapture"></a>

<a id="api_irtcengine_getscreencapturesources"></a>

<a id="ariaid-title2"></a>

## getScreenCaptureSourcesWithThumbSize\:iconSize\:includeScreen: [#getscreencapturesourceswiththumbsizeiconsizeincludescreen]

获取可共享的屏幕和窗口列表。

<a id="api_irtcengine_getscreencapturesources__prototype"></a>

```objc
- (NSArray<AgoraScreenCaptureSourceInfo*>* _Nullable)getScreenCaptureSourcesWithThumbSize:(NSSize)thumbSize iconSize:(NSSize)iconSize includeScreen:(BOOL)includeScreen NS_SWIFT_NAME(getScreenCaptureSources(withThumbSize:iconSize:includeScreen:));
```

<a id="api_irtcengine_getscreencapturesources__detailed_desc"></a>

你可以在共享屏幕或窗口前调用该方法，以获取可共享的屏幕和窗口列表。用户可以通过列表中的缩略图轻松选择要共享的特定屏幕或窗口。该列表还包含窗口 ID 和屏幕 ID 等信息，你可以使用这些信息调用 `startScreenCaptureByWindowId` 或 `startScreenCaptureByDisplayId` 开始共享。

<a id="api_irtcengine_getscreencapturesources__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="thumbsize"></a>
<Parameter name="thumbSize">

屏幕或窗口缩略图的目标尺寸（宽度和高度，单位为像素）。SDK 会对原始图像进行缩放，使图像最长边的长度与目标尺寸一致，同时不扭曲原始图像。例如，若原始图像为 400 × 300，`thumbSize` 为 100 × 100，则缩略图的实际尺寸为 100 × 75。如果目标尺寸大于原始尺寸，则缩略图为原始图像，SDK 不进行缩放。

</Parameter>
<a id="iconsize"></a>
<Parameter name="iconSize">

应用程序图标的目标尺寸（宽度和高度，单位为像素）。SDK 会对原始图像进行缩放，使图像最长边的长度与目标尺寸一致，同时不扭曲原始图像。例如，若原始图像为 400 × 300，`iconSize` 为 100 × 100，则图标的实际尺寸为 100 × 75。如果目标尺寸大于原始尺寸，则图标为原始图像，SDK 不进行缩放。

</Parameter>
<a id="includescreen"></a>
<Parameter name="includeScreen">

是否返回屏幕信息：

- YES：返回屏幕和窗口信息。
- NO：仅返回窗口信息。

</Parameter>
</ParameterList>

<a id="api_irtcengine_getscreencapturesources__return_values"></a>

### 返回值 [#返回值]

- 方法调用成功，返回 [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)

<a id="api_irtcengine_setscreencapturescenario"></a>

<a id="ariaid-title3"></a>

## setScreenCaptureScenario: [#setscreencapturescenario]

设置屏幕共享场景。

<a id="api_irtcengine_setscreencapturescenario__prototype"></a>

```objc
- (int)setScreenCaptureScenario:(AgoraScreenScenarioType)scenarioType  NS_SWIFT_NAME(setScreenCaptureScenario(_:));
```

<a id="api_irtcengine_setscreencapturescenario__detailed_desc"></a>

调用该方法设置屏幕共享场景。SDK 会根据设置的场景优化共享的视频质量和用户体验。

:::note
注： 声网建议你在加入频道前调用此方法。
:::

<a id="api_irtcengine_setscreencapturescenario__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="scenariotype"></a>
<Parameter name="scenarioType">

屏幕共享场景。详见 [AgoraScreenScenarioType](/zh-CN/api-reference/rtc/macos/enum-screenscenariotype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setscreencapturescenario__return_values"></a>

### 返回值 [#返回值-1]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-1]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_startscreencapture2"></a>

<a id="ariaid-title4"></a>

## startScreenCapture\:config: [#startscreencaptureconfig]

开始屏幕共享。

<a id="api_irtcengine_startscreencapture2__prototype"></a>

```objc
- (int)startScreenCapture:(AgoraVideoSourceType)sourceType config:(AgoraScreenCaptureConfiguration * _Nullable)config NS_SWIFT_NAME(startScreenCapture(_:config:));
```

<a id="api_irtcengine_startscreencapture2__detailed_desc"></a>

<a id="api_irtcengine_startscreencapture2__scenario"></a>

### 适用场景 [#适用场景]

适用于屏幕共享场景，支持多频道使用。

<a id="api_irtcengine_startscreencapture2__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="sourcetype"></a>
<Parameter name="sourceType">

屏幕来源类型，详见 [AgoraVideoSourceType](/zh-CN/api-reference/rtc/macos/enum-videosourcetype)。

</Parameter>
<a id="config"></a>
<Parameter name="config">

屏幕共享的配置，详见 [AgoraScreenCaptureConfiguration](/zh-CN/api-reference/rtc/macos/class-screencaptureconfiguration)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startscreencapture2__return_values"></a>

### 返回值 [#返回值-2]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-2]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_startscreencapturebydisplayid"></a>

<a id="ariaid-title5"></a>

## startScreenCaptureByDisplayId\:regionRect\:captureParams: [#startscreencapturebydisplayidregionrectcaptureparams]

通过指定屏幕 ID 采集屏幕。

<a id="api_irtcengine_startscreencapturebydisplayid__prototype"></a>

```objc
- (int)startScreenCaptureByDisplayId:(UInt32)displayId
                          regionRect:(CGRect)regionRect
                       captureParams:(AgoraScreenCaptureParameters *_Nonnull)captureParams  NS_SWIFT_NAME(startScreenCapture(byDisplayId:regionRect:captureParams:));
```

<a id="api_irtcengine_startscreencapturebydisplayid__detailed_desc"></a>

采集整个屏幕或部分屏幕区域的视频流。

<a id="api_irtcengine_startscreencapturebydisplayid__scenario"></a>

### 适用场景 [#适用场景-1]

在屏幕共享场景中，你需要调用此方法开始采集屏幕视频流。

<a id="api_irtcengine_startscreencapturebydisplayid__timing"></a>

### 调用时机 [#调用时机]

你可以在加入频道前或加入频道后调用此方法，具体区别如下：

- 在加入频道前调用此方法，然后调用 `joinChannelByToken` 加入频道，并将 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 设置为 YES，以开始屏幕共享。
- 在加入频道后调用此方法，然后调用 [updateChannelWithMediaOptions:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatechannelmediaoptions) 并将 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 设置为 YES，以开始屏幕共享。

<a id="api_irtcengine_startscreencapturebydisplayid__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="displayid"></a>
<Parameter name="displayId">

要共享的屏幕的屏幕 ID。

</Parameter>
<a id="regionrect"></a>
<Parameter name="regionRect">

（可选）相对于窗口的区域位置。如果未设置该参数，SDK 共享整个窗口。该参数包含以下字段：

- `x`：距窗口左上角的水平偏移。
- `y`：距窗口左上角的垂直偏移。
- `width`：区域的宽度。
- `height`：区域的高度。

如果指定的区域超出窗口范围，SDK 仅共享窗口内的区域；如果设置 `width` 或 `height` 为 0，SDK 共享整个窗口。

</Parameter>
<a id="captureparams"></a>
<Parameter name="captureParams">

屏幕共享配置。默认视频分辨率为 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)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startscreencapturebydisplayid__return_values"></a>

### 返回值 [#返回值-3]

- 0：方法调用成功。
- &lt; 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)

<a id="api_irtcengine_startscreencapturebywindowid"></a>

<a id="ariaid-title6"></a>

## startScreenCaptureByWindowId\:regionRect\:captureParams: [#startscreencapturebywindowidregionrectcaptureparams]

通过指定窗口 ID 采集整个或部分窗口的屏幕内容。

<a id="api_irtcengine_startscreencapturebywindowid__prototype"></a>

```objc
- (int)startScreenCaptureByWindowId:(UInt32)windowId
                         regionRect:(CGRect)regionRect
                      captureParams:(AgoraScreenCaptureParameters *_Nonnull)captureParams  NS_SWIFT_NAME(startScreenCapture(byWindowId:regionRect:captureParams:));
```

<a id="api_irtcengine_startscreencapturebywindowid__detailed_desc"></a>

你需要指定要采集的窗口的 ID，可以采集整个窗口或窗口的部分区域。

:::note
注： 该方法仅适用于 macOS 和 Windows 平台。
:::

<a id="api_irtcengine_startscreencapturebywindowid__scenario"></a>

### 适用场景 [#适用场景-2]

在屏幕共享场景中，你需要调用该方法开始采集屏幕视频流。

<a id="api_irtcengine_startscreencapturebywindowid__timing"></a>

### 调用时机 [#调用时机-1]

你可以在加入频道前或加入频道后调用该方法，具体如下：

- 在加入频道前调用该方法，然后调用 `joinChannelByToken` 加入频道，并将 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 设置为 YES，以开始屏幕共享。
- 在加入频道后调用该方法，然后调用 [updateChannelWithMediaOptions:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatechannelmediaoptions) 并将 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 设置为 YES，以开始屏幕共享。

<a id="api_irtcengine_startscreencapturebywindowid__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="windowid"></a>
<Parameter name="windowId">

要共享的窗口的 ID。

</Parameter>
<a id="regionrect-1"></a>
<Parameter name="regionRect">

（可选）相对于窗口的区域位置。如果未设置该参数，SDK 会共享整个窗口。该参数包含以下字段：

- x：距窗口左上角的水平偏移。
- y：距窗口左上角的垂直偏移。
- width：区域的宽度。
- height：区域的高度。

如果指定的区域超出窗口范围，SDK 只共享窗口内的区域；如果设置 width 或 height 为 0，SDK 会共享整个窗口。

</Parameter>
<a id="captureparams-1"></a>
<Parameter name="captureParams">

屏幕共享配置。默认视频分辨率为 1920 × 1080，即 2,073,600 像素。声网会根据该参数的值计算费用。详见 [AgoraScreenCaptureParameters](/zh-CN/api-reference/rtc/macos/class-screencaptureparameters)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startscreencapturebywindowid__return_values"></a>

### 返回值 [#返回值-4]

- 0：方法调用成功。
- &lt; 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)

<a id="api_irtcengine_stopscreencapture"></a>

<a id="ariaid-title7"></a>

## stopScreenCapture [#stopscreencapture]

停止屏幕采集。

<a id="api_irtcengine_stopscreencapture__prototype"></a>

```objc
- (int)stopScreenCapture NS_SWIFT_NAME(stopScreenCapture());
```

<a id="api_irtcengine_stopscreencapture__detailed_desc"></a>

<a id="api_irtcengine_stopscreencapture__scenario"></a>

### 适用场景 [#适用场景-3]

适用于以下场景：

- iOS：如果你通过调用 `startScreenCapture:` 开始屏幕采集，则需要调用此方法停止屏幕采集。
- macOS：如果你通过调用 `startScreenCaptureByWindowId:regionRect:captureParams:` 或 `startScreenCaptureByDisplayId:regionRect:captureParams:` 开始屏幕采集，则需要调用此方法停止屏幕采集。

<a id="api_irtcengine_stopscreencapture__timing"></a>

### 调用时机 [#调用时机-2]

你可以在加入频道前或后调用此方法。

<a id="api_irtcengine_stopscreencapture__return_values"></a>

### 返回值 [#返回值-5]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-5]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_stopscreencapture2"></a>

<a id="ariaid-title8"></a>

## stopScreenCapture: [#stopscreencapture-1]

停止来自指定视频源的屏幕采集。

<a id="api_irtcengine_stopscreencapture2__prototype"></a>

```objc
- (int)stopScreenCapture:(AgoraVideoSourceType)sourceType NS_SWIFT_NAME(stopScreenCapture(_:));
```

<a id="api_irtcengine_stopscreencapture2__detailed_desc"></a>

调用 [startScreenCapture\:config:](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_startscreencapture2) 开始从一个或多个屏幕采集屏幕后，需调用此方法停止屏幕采集。你需要通过 `sourceType` 参数指定要停止的屏幕。

<a id="api_irtcengine_stopscreencapture2__timing"></a>

### 调用时机 [#调用时机-3]

你可以在加入频道前或后调用此方法。

<a id="api_irtcengine_stopscreencapture2__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="sourcetype-1"></a>
<Parameter name="sourceType">

视频源的类型，详见 [AgoraVideoSourceType](/zh-CN/api-reference/rtc/macos/enum-videosourcetype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_stopscreencapture2__return_values"></a>

### 返回值 [#返回值-6]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-6]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_updatescreencaptureparameters"></a>

<a id="ariaid-title9"></a>

## updateScreenCaptureParameters: [#updatescreencaptureparameters]

更新屏幕采集参数。

<a id="api_irtcengine_updatescreencaptureparameters__prototype"></a>

```objc
- (int)updateScreenCaptureParameters:(AgoraScreenCaptureParameters * _Nonnull)captureParams  NS_SWIFT_NAME(updateScreenCaptureParameters(_:));
```

<a id="api_irtcengine_updatescreencaptureparameters__detailed_desc"></a>

:::note
注： 请在开始屏幕共享或窗口共享后调用此方法。
:::

<a id="api_irtcengine_updatescreencaptureparameters__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="captureparams-2"></a>
<Parameter name="captureParams">

屏幕共享的编码参数。屏幕共享流的视频属性只需通过该参数设置，与 [setVideoEncoderConfiguration:](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。详见 [AgoraScreenCaptureParameters](/zh-CN/api-reference/rtc/macos/class-screencaptureparameters)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_updatescreencaptureparameters__return_values"></a>

### 返回值 [#返回值-7]

- 0：方法调用成功。
- &lt; 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)

<a id="api_irtcengine_updatescreencaptureregion2"></a>

<a id="ariaid-title10"></a>

## updateScreenCaptureRegion: [#updatescreencaptureregion]

更新屏幕采集区域。

<a id="api_irtcengine_updatescreencaptureregion2__prototype"></a>

```objc
- (int)updateScreenCaptureRegion:(CGRect)rect  NS_SWIFT_NAME(updateScreenCaptureRegion(_:));
```

<a id="api_irtcengine_updatescreencaptureregion2__detailed_desc"></a>

你可以通过该方法更新屏幕或窗口的采集区域。

<a id="api_irtcengine_updatescreencaptureregion2__parameters"></a>

### 参数 [#参数-7]

<ParameterList>
<a id="rect"></a>
<Parameter name="rect">

相对于屏幕或窗口的区域位置。

- 如果不设置该参数，SDK 会共享整个屏幕。
- 如果指定的区域超出屏幕或窗口范围，SDK 仅共享其中的区域。
- 如果设置的宽度或高度为 0，SDK 会共享整个屏幕或窗口。

</Parameter>
</ParameterList>

<a id="api_irtcengine_updatescreencaptureregion2__return_values"></a>

### 返回值 [#返回值-8]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-8]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)