# 屏幕采集 (/zh-CN/api-reference/rtc/macos/video/screencapture) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## getScreenCaptureSourcesWithThumbSize\:iconSize\:includeScreen: [#getscreencapturesourceswiththumbsizeiconsizeincludescreen] 获取可共享的屏幕和窗口列表。 ```objc - (NSArray* _Nullable)getScreenCaptureSourcesWithThumbSize:(NSSize)thumbSize iconSize:(NSSize)iconSize includeScreen:(BOOL)includeScreen NS_SWIFT_NAME(getScreenCaptureSources(withThumbSize:iconSize:includeScreen:)); ``` 你可以在共享屏幕或窗口前调用该方法,以获取可共享的屏幕和窗口列表。用户可以通过列表中的缩略图轻松选择要共享的特定屏幕或窗口。该列表还包含窗口 ID 和屏幕 ID 等信息,你可以使用这些信息调用 `startScreenCaptureByWindowId` 或 `startScreenCaptureByDisplayId` 开始共享。 ### 参数 [#参数] 屏幕或窗口缩略图的目标尺寸(宽度和高度,单位为像素)。SDK 会对原始图像进行缩放,使图像最长边的长度与目标尺寸一致,同时不扭曲原始图像。例如,若原始图像为 400 × 300,`thumbSize` 为 100 × 100,则缩略图的实际尺寸为 100 × 75。如果目标尺寸大于原始尺寸,则缩略图为原始图像,SDK 不进行缩放。 应用程序图标的目标尺寸(宽度和高度,单位为像素)。SDK 会对原始图像进行缩放,使图像最长边的长度与目标尺寸一致,同时不扭曲原始图像。例如,若原始图像为 400 × 300,`iconSize` 为 100 × 100,则图标的实际尺寸为 100 × 75。如果目标尺寸大于原始尺寸,则图标为原始图像,SDK 不进行缩放。 是否返回屏幕信息: - YES:返回屏幕和窗口信息。 - NO:仅返回窗口信息。 ### 返回值 [#返回值] - 方法调用成功,返回 [AgoraScreenCaptureSourceInfo](/zh-CN/api-reference/rtc/macos/class-screencapturesourceinfo) 对象数组,详见 [AgoraScreenCaptureSourceInfo](/zh-CN/api-reference/rtc/macos/class-screencapturesourceinfo)。 - 方法调用失败,返回 nil。 ### 所属接口类 [#所属接口类] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## setScreenCaptureScenario: [#setscreencapturescenario] 设置屏幕共享场景。 ```objc - (int)setScreenCaptureScenario:(AgoraScreenScenarioType)scenarioType NS_SWIFT_NAME(setScreenCaptureScenario(_:)); ``` 调用该方法设置屏幕共享场景。SDK 会根据设置的场景优化共享的视频质量和用户体验。 :::note 注: 声网建议你在加入频道前调用此方法。 ::: ### 参数 [#参数-1] 屏幕共享场景。详见 [AgoraScreenScenarioType](/zh-CN/api-reference/rtc/macos/enum-screenscenariotype)。 ### 返回值 [#返回值-1] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-1] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## startScreenCapture\:config: [#startscreencaptureconfig] 开始屏幕共享。 ```objc - (int)startScreenCapture:(AgoraVideoSourceType)sourceType config:(AgoraScreenCaptureConfiguration * _Nullable)config NS_SWIFT_NAME(startScreenCapture(_:config:)); ``` ### 适用场景 [#适用场景] 适用于屏幕共享场景,支持多频道使用。 ### 参数 [#参数-2] 屏幕来源类型,详见 [AgoraVideoSourceType](/zh-CN/api-reference/rtc/macos/enum-videosourcetype)。 屏幕共享的配置,详见 [AgoraScreenCaptureConfiguration](/zh-CN/api-reference/rtc/macos/class-screencaptureconfiguration)。 ### 返回值 [#返回值-2] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-2] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## startScreenCaptureByDisplayId\:regionRect\:captureParams: [#startscreencapturebydisplayidregionrectcaptureparams] 通过指定屏幕 ID 采集屏幕。 ```objc - (int)startScreenCaptureByDisplayId:(UInt32)displayId regionRect:(CGRect)regionRect captureParams:(AgoraScreenCaptureParameters *_Nonnull)captureParams NS_SWIFT_NAME(startScreenCapture(byDisplayId:regionRect:captureParams:)); ``` 采集整个屏幕或部分屏幕区域的视频流。该方法仅创建主屏幕视频轨道。 ### 适用场景 [#适用场景-1] 在屏幕共享场景中,你需要调用此方法开始采集屏幕视频流。 ### 调用时机 [#调用时机] 你可以在加入频道前或加入频道后调用此方法,具体区别如下: - 在加入频道前调用此方法,然后调用 `joinChannelByToken` 加入频道,并将 `publishScreenTrack` 设置为 YES,以开始屏幕共享。 - 在加入频道后调用此方法,然后调用 [updateChannelWithMediaOptions:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatechannelmediaoptions) 并将 `publishScreenTrack` 设置为 YES,以开始屏幕共享。 ### 参数 [#参数-3] 要共享的屏幕的屏幕 ID。 (可选)相对于窗口的区域位置。如果未设置该参数,SDK 共享整个窗口。该参数包含以下字段: - `x`:距窗口左上角的水平偏移。 - `y`:距窗口左上角的垂直偏移。 - `width`:区域的宽度。 - `height`:区域的高度。 如果指定的区域超出窗口范围,SDK 仅共享窗口内的区域;如果设置 `width` 或 `height` 为 0,SDK 共享整个窗口。 屏幕共享配置。默认视频分辨率为 1920 × 1080,即 2,073,600 像素。声网会根据该参数的值计算费用。屏幕共享视频流的视频属性仅需通过该参数设置,与 [setVideoEncoderConfiguration:](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。详见 [AgoraScreenCaptureParameters](/zh-CN/api-reference/rtc/macos/class-screencaptureparameters)。 ### 返回值 [#返回值-3] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:参数无效。 - -8:屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,然后重新开始屏幕共享。 ### 所属接口类 [#所属接口类-3] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## startScreenCaptureByWindowId\:regionRect\:captureParams: [#startscreencapturebywindowidregionrectcaptureparams] 通过指定窗口 ID 采集整个或部分窗口的屏幕内容。 ```objc - (int)startScreenCaptureByWindowId:(UInt32)windowId regionRect:(CGRect)regionRect captureParams:(AgoraScreenCaptureParameters *_Nonnull)captureParams NS_SWIFT_NAME(startScreenCapture(byWindowId:regionRect:captureParams:)); ``` 你需要指定要采集的窗口的 ID,可以采集整个窗口或窗口的部分区域。 :::note 注: 该方法仅适用于 macOS 和 Windows 平台。 该方法仅创建主屏幕视频轨道。 ::: ### 适用场景 [#适用场景-2] 在屏幕共享场景中,你需要调用该方法开始采集屏幕视频流。 ### 调用时机 [#调用时机-1] 你可以在加入频道前或加入频道后调用该方法,具体如下: - 在加入频道前调用该方法,然后调用 `joinChannelByToken` 加入频道,并将 `publishScreenTrack` 设置为 YES,以开始屏幕共享。 - 在加入频道后调用该方法,然后调用 [updateChannelWithMediaOptions:](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatechannelmediaoptions) 并将 `publishScreenTrack` 设置为 YES,以开始屏幕共享。 ### 参数 [#参数-4] 要共享的窗口的 ID。 (可选)相对于窗口的区域位置。如果未设置该参数,SDK 会共享整个窗口。该参数包含以下字段: - x:距窗口左上角的水平偏移。 - y:距窗口左上角的垂直偏移。 - width:区域的宽度。 - height:区域的高度。 如果指定的区域超出窗口范围,SDK 只共享窗口内的区域;如果设置 width 或 height 为 0,SDK 会共享整个窗口。 屏幕共享配置。默认视频分辨率为 1920 × 1080,即 2,073,600 像素。声网会根据该参数的值计算费用。详见 [AgoraScreenCaptureParameters](/zh-CN/api-reference/rtc/macos/class-screencaptureparameters)。 ### 返回值 [#返回值-4] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:参数无效。 - -8:屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,然后重新开始共享屏幕。 ### 所属接口类 [#所属接口类-4] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## stopScreenCapture [#stopscreencapture] 停止屏幕采集。 ```objc - (int)stopScreenCapture NS_SWIFT_NAME(stopScreenCapture()); ``` ### 适用场景 [#适用场景-3] 适用于以下场景: - iOS:如果你通过调用 `startScreenCapture:` 开始屏幕采集,则需要调用此方法停止屏幕采集。 - macOS:如果你通过调用 `startScreenCaptureByWindowId:regionRect:captureParams:` 或 `startScreenCaptureByDisplayId:regionRect:captureParams:` 开始屏幕采集,则需要调用此方法停止屏幕采集。 ### 调用时机 [#调用时机-2] 你可以在加入频道前或后调用此方法。 ### 返回值 [#返回值-5] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-5] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## stopScreenCapture: [#stopscreencapture-1] 停止来自指定视频源的屏幕采集。 ```objc - (int)stopScreenCapture:(AgoraVideoSourceType)sourceType NS_SWIFT_NAME(stopScreenCapture(_:)); ``` 调用 [startScreenCapture\:config:](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_startscreencapture2) 开始从一个或多个屏幕采集屏幕后,需调用此方法停止屏幕采集。你需要通过 `sourceType` 参数指定要停止的屏幕。 ### 调用时机 [#调用时机-3] 你可以在加入频道前或后调用此方法。 ### 参数 [#参数-5] 视频源的类型,详见 [AgoraVideoSourceType](/zh-CN/api-reference/rtc/macos/enum-videosourcetype)。 ### 返回值 [#返回值-6] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-6] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## updateScreenCaptureParameters: [#updatescreencaptureparameters] 更新屏幕采集参数。 ```objc - (int)updateScreenCaptureParameters:(AgoraScreenCaptureParameters * _Nonnull)captureParams NS_SWIFT_NAME(updateScreenCaptureParameters(_:)); ``` :::note 注: 请在开始屏幕共享或窗口共享后调用此方法。 ::: ### 参数 [#参数-6] 屏幕共享的编码参数。屏幕共享流的视频属性只需通过该参数设置,与 [setVideoEncoderConfiguration:](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 无关。详见 [AgoraScreenCaptureParameters](/zh-CN/api-reference/rtc/macos/class-screencaptureparameters)。 ### 返回值 [#返回值-7] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -2:参数无效。 - -8:屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 [stopScreenCapture](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_stopscreencapture) 停止当前共享,然后重新开始共享屏幕。 ### 所属接口类 [#所属接口类-7] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## updateScreenCaptureRegion: [#updatescreencaptureregion] 更新屏幕采集区域。 ```objc - (int)updateScreenCaptureRegion:(CGRect)rect NS_SWIFT_NAME(updateScreenCaptureRegion(_:)); ``` 你可以通过该方法更新屏幕或窗口的采集区域。 ### 参数 [#参数-7] 相对于屏幕或窗口的区域位置。 - 如果不设置该参数,SDK 会共享整个屏幕。 - 如果指定的区域超出屏幕或窗口范围,SDK 仅共享其中的区域。 - 如果设置的宽度或高度为 0,SDK 会共享整个屏幕或窗口。 ### 返回值 [#返回值-8] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-8] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)