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

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

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

<a id="api_irtcengine_queryscreencapturecapability"></a>

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

## queryScreenCaptureCapability [#queryscreencapturecapability]

查询设备在屏幕共享时支持的最高帧率。

<a id="api_irtcengine_queryscreencapturecapability__prototype"></a>

```objc
- (AgoraScreenCaptureFrameRateCapability)queryScreenCaptureCapability NS_SWIFT_NAME(queryScreenCaptureCapability());
```

<a id="api_irtcengine_queryscreencapturecapability__detailed_desc"></a>

:::info[自从]
自 v4.2.0 版本新增。
:::

<a id="api_irtcengine_queryscreencapturecapability__scenario"></a>

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

为确保屏幕共享的最佳性能，特别是在启用如 60 fps 的高帧率时，建议你在共享前使用该方法查询设备支持的最高帧率。

<a id="api_irtcengine_queryscreencapturecapability__timing"></a>

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

你可以在开始屏幕共享前调用该方法，查询设备支持的最高帧率，以确保屏幕共享的最佳性能，特别是在启用如 60 fps 的高帧率时。如果设备不支持高帧率，你可以相应地降低屏幕共享流的帧率，以避免影响共享质量，确保共享效果符合预期。

<a id="api_irtcengine_queryscreencapturecapability__return_values"></a>

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

- 方法调用成功，返回设备支持的最高帧率。详见 [AgoraScreenCaptureFrameRateCapability](/zh-CN/api-reference/rtc/ios/enum-screencaptureframeratecapability)。
- 方法调用失败，返回 nil。

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

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/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>

### 参数 [#参数]

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

屏幕共享场景。详见 [AgoraScreenScenarioType](/zh-CN/api-reference/rtc/ios/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/ios/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_startscreencapture"></a>

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

## startScreenCapture: [#startscreencapture]

开始屏幕采集。

<a id="api_irtcengine_startscreencapture__prototype"></a>

```objc
- (int)startScreenCapture:(AgoraScreenCaptureParameters2* _Nullable)parameters  NS_SWIFT_NAME(startScreenCapture(_:));
```

<a id="api_irtcengine_startscreencapture__detailed_desc"></a>

你可以调用该方法开始采集屏幕视频流。

:::note
注：

- 在 iOS 平台，屏幕共享仅支持 iOS 12.0 及以上版本。
- 如果你使用自定义音频源而非 SDK 采集音频，声网建议你在应用中添加保活处理逻辑，以避免应用进入后台后屏幕共享中断。
- 此功能对设备性能要求较高，声网建议在 iPhone X 及以上机型上使用。
- 此方法依赖 iOS 屏幕共享动态库 `AgoraReplayKitExtension.xcframework`。如果该动态库被删除，将无法正常启用屏幕共享。
- 为避免屏幕共享时系统音频采集失败，声网建议你在加入频道前通过 [setAudioScenario:](/zh-CN/api-reference/rtc/ios/audio/audio-basic#api_irtcengine_setaudioscenario) 方法将音频应用场景设置为 `AgoraAudioScenarioGameStreaming`。
- 屏幕共享流的计费基于 [AgoraScreenVideoParameters](/zh-CN/api-reference/rtc/ios/class-screenvideoparameters) 中的 `dimensions`：

  - 如果未传入该值，声网按 1280 × 720 计费。
  - 如果传入该值，声网按传入的值计费。
:::

<a id="api_irtcengine_startscreencapture__scenario"></a>

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

在屏幕共享场景中。

<a id="api_irtcengine_startscreencapture__timing"></a>

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

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

- 先调用此方法，再调用 `joinChannelByToken` 加入频道，并将 `publishScreenCaptureVideo` 设置为 YES，即可开始屏幕共享。
- 加入频道后调用此方法，再调用 `updateChannelWithMediaOptions` 并将 `publishScreenCaptureVideo` 设置为 YES，即可开始屏幕共享。

<a id="api_irtcengine_startscreencapture__related"></a>

### 相关回调 [#相关回调]

当屏幕共享扩展进程的状态发生变化时，SDK 会触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调。当 `sourceType` 的类型为 `AgoraVideoSourceTypeScreen` 时，`state` 参数表示屏幕共享的状态。

<a id="api_irtcengine_startscreencapture__parameters"></a>

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

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

屏幕共享的编码参数。详见 [AgoraScreenCaptureParameters2](/zh-CN/api-reference/rtc/ios/class-screencaptureparameters2)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_startscreencapture__return_values"></a>

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

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

  - -2：参数为 nil。

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

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

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

<a id="ariaid-title5"></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>

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

适用于以下场景：

- 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>

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

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

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

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

<a id="api_irtcengine_updatescreencapture"></a>

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

## updateScreenCapture: [#updatescreencapture]

更新屏幕共享配置。

<a id="api_irtcengine_updatescreencapture__prototype"></a>

```objc
- (int)updateScreenCapture:(AgoraScreenCaptureParameters2* _Nullable)parameters  NS_SWIFT_NAME(updateScreenCapture(_:));
```

<a id="api_irtcengine_updatescreencapture__detailed_desc"></a>

:::note
注： 该方法仅适用于 iOS 11 及以上版本。
:::

<a id="api_irtcengine_updatescreencapture__parameters"></a>

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

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

屏幕共享的配置参数。详见 [AgoraScreenCaptureParameters2](/zh-CN/api-reference/rtc/ios/class-screencaptureparameters2)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_updatescreencapture__return_values"></a>

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

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

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

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