# 屏幕采集 (/zh-CN/api-reference/rtc/react-native/video/screencapture) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## queryScreenCaptureCapability [#queryscreencapturecapability] 查询设备在屏幕共享时支持的最高帧率。 ```ts abstract queryScreenCaptureCapability(): number; ``` ### 适用场景 [#适用场景] 在屏幕共享场景下,如果你想启用高帧率(如 60 fps)、但不确定设备是否支持时,可以先调用该方法查询设备支持的最高帧率。如果设备不支持高帧率,你可以在开启屏幕共享时适当调低屏幕共享流的帧率,以确保共享场景的效果符合预期。 ### 返回值 [#返回值] - 方法调用成功时,返回设备支持的最高帧率。详见 [ScreenCaptureFramerateCapability](/zh-CN/api-reference/rtc/react-native/enum-screencaptureframeratecapability)。 - <0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类] - [IRtcEngine](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) ## setExternalMediaProjection [#setexternalmediaprojection] 设置 SDK 外部的 `MediaProjection` 采集屏幕视频流。 ```ts abstract setExternalMediaProjection(mediaProjection: any): number; ``` 成功调用该方法后,你设置的外部 `MediaProjection` 会替换掉 SDK 申请的 `MediaProjection` 采集屏幕视频流。 当停止屏幕共享或销毁 [IRtcEngine](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) 时,SDK 会自动释放 MediaProjection。 :::note 注: 该方法仅适用于 Android。 在调用该方法前,必须先申请 `MediaProjection` 权限。 ::: ### 适用场景 [#适用场景-1] 如果你具备自行申请 `MediaProjection` 的开发能力,可以直接使用该 `MediaProjection` 取代 SDK 申请的 `MediaProjection` 。以下列出两种使用场景: - 在定制系统的设备上,可避免系统弹窗(即需要用户授予屏幕采集权限),直接开始采集屏幕视频流。 - 一个屏幕共享进程中存在一个或多个子进程,避免在子进程中自行创建对象的过程出错而导致采集失败。 ### 调用时机 [#调用时机] 该方法需要在 [startScreenCapture](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_startscreencapture) 之前调用。 ### 参数 [#参数] 一个 [MediaProjection](https://developer.android.com/reference/android/media/projection/MediaProjection) 对象,用于采集屏幕视频流。 ### 返回值 [#返回值-1] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-1] - [IRtcEngine](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) ## setScreenCaptureContentHint [#setscreencapturecontenthint] 设置屏幕共享内容类型。 ```ts abstract setScreenCaptureContentHint(contentHint: VideoContentHint): number; ``` SDK 会根据不同的内容类型,使用不同的算法对共享效果进行优化。如果不调用该方法,SDK 会将屏幕共享的内容默认为 ContentHintNone,即无指定的内容类型。 :::note 注: 该方法在开始屏幕共享前后都能调用。 ::: ### 参数 [#参数-1] 屏幕共享的内容类型。详见 [VideoContentHint](/zh-CN/api-reference/rtc/react-native/enum-videocontenthint)。 ### 返回值 [#返回值-2] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:传入的参数无效。 - -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。 ### 所属接口类 [#所属接口类-2] - [IRtcEngine](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) ## setScreenCaptureScenario [#setscreencapturescenario] 设置屏幕共享的场景。 ```ts abstract setScreenCaptureScenario(screenScenario: ScreenScenarioType): number; ``` 开启屏幕共享或窗口共享时,你可以调用该方法设置屏幕共享的场景,SDK 会根据你设置的场景调整共享画面的画质。 :::note 注: 声网建议你在加入频道前调用该方法。 ::: ### 参数 [#参数-2] 屏幕共享的场景,详见 [ScreenScenarioType](/zh-CN/api-reference/rtc/react-native/enum-screenscenariotype)。 ### 返回值 [#返回值-3] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-3] - [IRtcEngine](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) ## startScreenCapture [#startscreencapture] 开始屏幕采集。 ```ts abstract startScreenCapture(captureParams: ScreenCaptureParameters2): number; ``` :::note 注: - 屏幕共享流的计费标准以 [ScreenVideoParameters](/zh-CN/api-reference/rtc/react-native/class-screenvideoparameters) 中的 `dimensions` 值为准: - 当你未传值时,以 1280 × 720 计费。 - 当你传值时,以你传入的值计费。 - 在 iOS 平台上,屏幕共享仅适用于 iOS 12.0 及以上。 - 在 iOS 平台上,如果你使用音频自采集而非 SDK 采集音频,为避免应用退后台后屏幕共享停止,建议你对应用添加保活处理逻辑。 - 在 iOS 平台上,该功能对设备性能要求较高,建议你在 iPhone X 及之后机型上使用。 - 在 iOS 平台上,该方法依赖于屏幕共享动态库 `AgoraReplayKitExtension.xcframework`,如果删除该动态库会导致无法正常开启屏幕共享。 - 在 Android 平台上,如果用户未授予 App 屏幕采集权限,SDK 会上报 `onPermissionError(2)` 回调。 - 在 Android 9 及之后版本上,为避免应用退后台后被系统杀死,建议你在 `/app/Manifests/AndroidManifest.xml` 文件中添加前台服务权限:`android.permission.FOREGROUND_SERVICE`。 - 因 Android 性能限制,屏幕共享不支持 Android TV。 - 因 Android 系统限制,使用华为手机进行屏幕共享时,为避免崩溃,请不要在共享过程中调节屏幕共享流的视频编码分辨率。 - 因 Android 系统限制,部分小米手机不支持屏幕共享时采集系统音频。 - 为提高屏幕共享时采集系统音频的成功率,建议你在加入频道前通过 [setAudioScenario](/zh-CN/api-reference/rtc/react-native/audio/audio-basic#api_irtcengine_setaudioscenario) 方法设置音频场景为 `AudioScenarioGameStreaming`。 ::: ### 适用场景 [#适用场景-2] 在屏幕共享场景下,你需要调用该方法开始采集屏幕视频流。有关屏幕共享的实现方法,详见[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share)。 ### 调用时机 [#调用时机-1] 该方法在加入频道前后均可调用,区别如下: - 如果在加入频道前调用该方法,然后调用 [joinChannel](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_joinchannel2) 加入频道,并设置 `publishScreenCaptureVideo` 为 true,即可开始屏幕共享。 - 如果在加入频道后调用该方法,然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_updatechannelmediaoptions) 更新频道媒体选项,并设置 `publishScreenCaptureVideo` 为 true,即可开始屏幕共享。 ### 参数 [#参数-3] 屏幕共享的编码参数配置。详见 [ScreenCaptureParameters2](/zh-CN/api-reference/rtc/react-native/class-screencaptureparameters2)。 ### 返回值 [#返回值-4] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2 (iOS 平台): 参数为空。 - -2 (Anroid 平台): 系统版本过低,请确保 Android API 级别不低于 21。 - -3 (Anroid 平台): 无法采集系统音频,请确保 Android API 级别不低于 29。 ### 所属接口类 [#所属接口类-4] - [IRtcEngine](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) ## stopScreenCapture [#stopscreencapture] 停止屏幕采集。 ```ts abstract stopScreenCapture(): number; ``` ### 适用场景 [#适用场景-3] 如果你调用了 `startScreenCaptureBySourceType`、`startScreenCaptureByWindowId` 或 `startScreenCaptureByDisplayId` 开启屏幕采集,则停止屏幕采集时需要调用该方法。 ### 调用时机 [#调用时机-2] 该方法在加入频道前后均可调用。 ### 返回值 [#返回值-5] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-5] - [IRtcEngine](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) ## updateScreenCapture [#updatescreencapture] 更新屏幕采集的参数配置。 ```ts abstract updateScreenCapture(captureParams: ScreenCaptureParameters2): number; ``` 如果在开启屏幕共享时未采集系统音频、然后想要更新参数配置、发布系统音频,可参考以下步骤: 1. 调用该方法并设置 `captureAudio` 为 true。 2. 调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_updatechannelmediaoptions) 设置 `publishScreenCaptureAudio` 为 true,即可发布屏幕采集的音频。 :::note 注: - 该方法仅适用于 Android 和 iOS 平台。 - 在 iOS 平台上,屏幕共享仅适用于 iOS 12.0 及以上。 ::: ### 参数 [#参数-4] 屏幕共享的编码参数配置。详见 [ScreenCaptureParameters2](/zh-CN/api-reference/rtc/react-native/class-screencaptureparameters2)。 ### 返回值 [#返回值-6] - 0: 方法调用成功。 - < 0: 方法调用失败。 - -2:传入的参数无效。 - -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。 ### 所属接口类 [#所属接口类-6] - [IRtcEngine](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) ## updateScreenCaptureParameters [#updatescreencaptureparameters] 更新屏幕采集的参数配置。 ```ts abstract updateScreenCaptureParameters( captureParams: ScreenCaptureParameters ): number; ``` :::note 注: - 请在开启屏幕共享或窗口共享后调用该方法。 ::: ### 参数 [#参数-5] 屏幕共享的编码参数配置。详见 [ScreenCaptureParameters2](/zh-CN/api-reference/rtc/react-native/class-screencaptureparameters2)。 :::note 注: 屏幕共享流的视频属性只需通过该参数设置,与 [setVideoEncoderConfiguration](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。 ::: ### 返回值 [#返回值-7] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:传入的参数无效。 - -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。 ### 所属接口类 [#所属接口类-7] - [IRtcEngine](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) ## updateScreenCaptureRegion [#updatescreencaptureregion] 更新屏幕采集的区域。 ```ts abstract updateScreenCaptureRegion(regionRect: Rectangle): number; ``` :::note 注: 请在开启屏幕共享或窗口共享后调用该方法。 ::: ### 返回值 [#返回值-8] - 0: 方法调用成功。 - < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:传入的参数无效。 - -8:屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,再重新开始共享屏幕。 ### 所属接口类 [#所属接口类-8] - [IRtcEngine](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine)