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