# 屏幕采集 (/zh-CN/api-reference/rtc/android/video/screencapture) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## queryScreenCaptureCapability [#queryscreencapturecapability] 查询设备在屏幕共享时支持的最高帧率。 ```java public abstract int queryScreenCaptureCapability(); ``` :::info[自从] 自 v4.2.0 版本新增。 ::: 为了确保屏幕共享的最佳性能,特别是在启用如 60 fps 的高帧率时,声网建议你在共享前使用该方法查询设备支持的最大帧率。如果设备无法支持如此高的帧率,你可以相应地调整屏幕共享流的帧率,以避免影响共享质量。 ### 适用场景 [#适用场景] 为确保屏幕共享的最佳性能,特别是在启用如 60 fps 的高帧率时,建议你在共享前使用该方法查询设备支持的最高帧率。 ### 返回值 [#返回值] - 0:设备最多支持 15 fps 的帧率。 - 1:设备最多支持 30 fps 的帧率。 - 2:设备最多支持 60 fps 的帧率。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## setExternalMediaProjection [#setexternalmediaprojection] 配置 SDK 外部的 `MediaProjection` 以采集屏幕视频流。 ```java public abstract int setExternalMediaProjection(MediaProjection mediaProjection); ``` 调用该方法成功后,设置的外部 `MediaProjection` 将替代 SDK 申请的 `MediaProjection` 用于采集屏幕视频流。当屏幕共享停止或 [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) 被销毁时,SDK 会自动释放该 `MediaProjection`。 :::note 注: 在调用该方法前,必须先申请 [`MediaProjection`](https://developer.android.com/reference/android/media/projection/MediaProjection) 权限。 ::: ### 适用场景 [#适用场景-1] 如果你已申请到 `MediaProjection`,可以直接使用你自己的 `MediaProjection`,而无需使用 SDK 申请的对象。适用场景包括: - 在定制系统设备上,避免系统弹窗(如用户授权采集屏幕)并直接开始采集屏幕视频流。 - 在涉及一个或多个子进程的屏幕共享流程中,避免在子进程中创建对象时可能出现的错误,从而防止屏幕采集失败。 该方法适用于多频道场景。 ### 调用时机 [#调用时机] 在调用 [startScreenCapture](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_startscreencapture) 之后调用该方法。 ### 参数 [#参数] 用于采集屏幕视频流的对象。 ### 返回值 [#返回值-1] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-1] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## setScreenCaptureScenario [#setscreencapturescenario] 设置屏幕共享场景。 ```java public abstract int setScreenCaptureScenario(Constants.ScreenScenarioType screenScenario); ``` :::info[自从] 自 v4.2.0 版本新增。 ::: SDK 会根据设置的场景自动调整共享的视频质量和用户体验。 :::note 注: 声网建议你在加入频道前调用此方法。 ::: ### 参数 [#参数-1] 屏幕共享场景。详见 [ScreenScenarioType](/zh-CN/api-reference/rtc/android/enum-screenscenariotype)。 ### 返回值 [#返回值-2] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-2] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## startScreenCapture [#startscreencapture] 开始屏幕采集。 ```java public abstract int startScreenCapture(ScreenCaptureParameters screenCaptureParameters); ``` :::info[自从] 自 v3.7.0 版本新增。 ::: 你可以在加入频道前或加入频道后调用该方法开始采集屏幕视频流,具体如下: - 先调用该方法,再调用 `joinChannel` 加入频道,并将 `publishScreenCaptureVideo` 设置为 true,以开始屏幕共享。 - 加入频道后调用该方法,再调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_updatechannelmediaoptions) 并将 `publishScreenCaptureVideo` 设置为 true,以开始屏幕共享。 :::note 注: - 在 Android 平台,如果用户未授予应用屏幕采集权限,SDK 会触发 [onPermissionError](/zh-CN/api-reference/rtc/android/network#callback_irtcengineeventhandler_onpermissionerror)(错误码 2)回调。 - 在 Android 9 及以上版本,为避免应用进入后台后被系统杀死,声网建议你在 `/app/Manifests/AndroidManifest.xml` 文件中添加前台服务权限 `android.permission.FOREGROUND_SERVICE`。 - 由于性能限制,Android TV 不支持屏幕共享。 - 由于系统限制,使用华为手机时,请勿在屏幕共享过程中调整屏幕共享流的视频编码分辨率,否则可能会导致崩溃。 - 由于系统限制,部分小米设备在屏幕共享时不支持采集系统音频。 - 为避免屏幕共享时系统音频采集失败,声网建议你在加入频道前通过 [setAudioScenario](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_setaudioscenario) 方法将音频应用场景设置为 `AUDIO_SCENARIO_GAME_STREAMING`。 - 屏幕共享流的计费基于 [VideoCaptureParameters](/zh-CN/api-reference/rtc/android/class-screenvideoparameters) 中的 `dimensions`: - 如果未传入该值,声网按 1280 × 720 计费。 - 如果传入该值,声网按传入的值计费。 ::: ### 适用场景 [#适用场景-2] 在屏幕共享场景中。 ### 调用时机 [#调用时机-1] 你可以在加入频道前或加入频道后调用此方法。 ### 参数 [#参数-2] 屏幕共享的编码参数,详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/android/class-screencaptureparameters2)。 ### 返回值 [#返回值-3] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:系统版本过低。请确保 Android API 级别不低于 21。 - -3:无法采集系统音频。请确保 Android API 级别不低于 29。 ### 所属接口类 [#所属接口类-3] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## stopScreenCapture [#stopscreencapture] 停止屏幕采集。 ```java public abstract int stopScreenCapture(); ``` :::info[自从] 自 v3.7.0 版本新增。 ::: 如果你通过调用 [startScreenCapture](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_startscreencapture) 开始了屏幕采集,则需要调用 [stopScreenCapture](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_stopscreencapture) 停止屏幕采集。 ### 适用场景 [#适用场景-3] 适用于以下场景: - iOS:如果你通过调用 `startScreenCapture:` 开始屏幕采集,则需要调用此方法停止屏幕采集。 - macOS:如果你通过调用 `startScreenCaptureByWindowId:regionRect:captureParams:` 或 `startScreenCaptureByDisplayId:regionRect:captureParams:` 开始屏幕采集,则需要调用此方法停止屏幕采集。 ### 调用时机 [#调用时机-2] 你可以在加入频道前或后调用此方法。 ### 返回值 [#返回值-4] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-4] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) ## updateScreenCaptureParameters [#updatescreencaptureparameters] 更新屏幕采集参数。 ```java public abstract int updateScreenCaptureParameters(ScreenCaptureParameters screenCaptureParameters); ``` :::info[自从] 自 v3.7.0 版本新增。 ::: :::note 注: 请在开始屏幕共享或窗口共享后调用此方法。 ::: ### 参数 [#参数-3] 屏幕共享的编码参数,详见 [ScreenCaptureParameters](/zh-CN/api-reference/rtc/android/class-screencaptureparameters2)。 :::note 注: 屏幕共享视频流的视频属性仅需通过此参数设置,与 [setVideoEncoderConfiguration](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。 ::: ### 返回值 [#返回值-5] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:参数无效。 - -8:屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,然后重新开始共享屏幕。 ### 所属接口类 [#所属接口类-5] - [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)