# 屏幕采集 (/zh-CN/api-reference/rtc/ios/video/screencapture)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## queryScreenCaptureCapability [#queryscreencapturecapability]
查询设备在屏幕共享时支持的最高帧率。
```objc
- (AgoraScreenCaptureFrameRateCapability)queryScreenCaptureCapability NS_SWIFT_NAME(queryScreenCaptureCapability());
```
:::info[自从]
自 v4.2.0 版本新增。
:::
### 适用场景 [#适用场景]
为确保屏幕共享的最佳性能,特别是在启用如 60 fps 的高帧率时,建议你在共享前使用该方法查询设备支持的最高帧率。
### 调用时机 [#调用时机]
你可以在开始屏幕共享前调用该方法,查询设备支持的最高帧率,以确保屏幕共享的最佳性能,特别是在启用如 60 fps 的高帧率时。如果设备不支持高帧率,你可以相应地降低屏幕共享流的帧率,以避免影响共享质量,确保共享效果符合预期。
### 返回值 [#返回值]
- 方法调用成功,返回设备支持的最高帧率。详见 [AgoraScreenCaptureFrameRateCapability](/zh-CN/api-reference/rtc/ios/enum-screencaptureframeratecapability)。
- 方法调用失败,返回 nil。
### 所属接口类 [#所属接口类]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## setScreenCaptureScenario: [#setscreencapturescenario]
设置屏幕共享场景。
```objc
- (int)setScreenCaptureScenario:(AgoraScreenScenarioType)scenarioType NS_SWIFT_NAME(setScreenCaptureScenario(_:));
```
调用该方法设置屏幕共享场景。SDK 会根据设置的场景优化共享的视频质量和用户体验。
:::note
注: 声网建议你在加入频道前调用此方法。
:::
### 参数 [#参数]
屏幕共享场景。详见 [AgoraScreenScenarioType](/zh-CN/api-reference/rtc/ios/enum-screenscenariotype)。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## startScreenCapture: [#startscreencapture]
开始屏幕采集。
```objc
- (int)startScreenCapture:(AgoraScreenCaptureParameters2* _Nullable)parameters NS_SWIFT_NAME(startScreenCapture(_:));
```
你可以调用该方法开始采集屏幕视频流。
:::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 计费。
- 如果传入该值,声网按传入的值计费。
:::
### 适用场景 [#适用场景-1]
在屏幕共享场景中。
### 调用时机 [#调用时机-1]
你可以在加入频道前或加入频道后调用此方法,具体区别如下:
- 先调用此方法,再调用 `joinChannelByToken` 加入频道,并将 `publishScreenCaptureVideo` 设置为 YES,即可开始屏幕共享。
- 加入频道后调用此方法,再调用 `updateChannelWithMediaOptions` 并将 `publishScreenCaptureVideo` 设置为 YES,即可开始屏幕共享。
### 相关回调 [#相关回调]
当屏幕共享扩展进程的状态发生变化时,SDK 会触发 [rtcEngine\:localVideoStateChangedOfState\:reason\:sourceType:](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调。当 `sourceType` 的类型为 `AgoraVideoSourceTypeScreen` 时,`state` 参数表示屏幕共享的状态。
### 参数 [#参数-1]
屏幕共享的编码参数。详见 [AgoraScreenCaptureParameters2](/zh-CN/api-reference/rtc/ios/class-screencaptureparameters2)。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:参数为 nil。
### 所属接口类 [#所属接口类-2]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## stopScreenCapture [#stopscreencapture]
停止屏幕采集。
```objc
- (int)stopScreenCapture NS_SWIFT_NAME(stopScreenCapture());
```
### 适用场景 [#适用场景-2]
适用于以下场景:
- iOS:如果你通过调用 `startScreenCapture:` 开始屏幕采集,则需要调用此方法停止屏幕采集。
- macOS:如果你通过调用 `startScreenCaptureByWindowId:regionRect:captureParams:` 或 `startScreenCaptureByDisplayId:regionRect:captureParams:` 开始屏幕采集,则需要调用此方法停止屏幕采集。
### 调用时机 [#调用时机-2]
你可以在加入频道前或后调用此方法。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)
## updateScreenCapture: [#updatescreencapture]
更新屏幕共享配置。
```objc
- (int)updateScreenCapture:(AgoraScreenCaptureParameters2* _Nullable)parameters NS_SWIFT_NAME(updateScreenCapture(_:));
```
:::note
注: 该方法仅适用于 iOS 11 及以上版本。
:::
### 参数 [#参数-2]
屏幕共享的配置参数。详见 [AgoraScreenCaptureParameters2](/zh-CN/api-reference/rtc/ios/class-screencaptureparameters2)。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine)