屏幕采集
getScreenCaptureSourcesWithThumbSize:iconSize:includeScreen:
获取可共享的屏幕和窗口列表。
Objective-C
- (NSArray<AgoraScreenCaptureSourceInfo*>* _Nullable)getScreenCaptureSourcesWithThumbSize:(NSSize)thumbSize iconSize:(NSSize)iconSize includeScreen:(BOOL)includeScreen NS_SWIFT_NAME(getScreenCaptureSources(withThumbSize:iconSize:includeScreen:));
你可以在共享屏幕或窗口前调用该方法，以获取可共享的屏幕和窗口列表。用户可以通过列表中的缩略图轻松选择要共享的特定屏幕或窗口。该列表还包含窗口 ID 和屏幕 ID 等信息，你可以使用这些信息调用 startScreenCaptureByWindowId 或 startScreenCaptureByDisplayId 开始共享。
参数
- thumbSize
- 屏幕或窗口缩略图的目标尺寸（宽度和高度，单位为像素）。SDK 会对原始图像进行缩放，使图像最长边的长度与目标尺寸一致，同时不扭曲原始图像。例如，若原始图像为 400 × 300，
thumbSize为 100 × 100，则缩略图的实际尺寸为 100 × 75。如果目标尺寸大于原始尺寸，则缩略图为原始图像，SDK 不进行缩放。 - iconSize
- 应用程序图标的目标尺寸（宽度和高度，单位为像素）。SDK 会对原始图像进行缩放，使图像最长边的长度与目标尺寸一致，同时不扭曲原始图像。例如，若原始图像为 400 × 300，
iconSize为 100 × 100，则图标的实际尺寸为 100 × 75。如果目标尺寸大于原始尺寸，则图标为原始图像，SDK 不进行缩放。 - includeScreen
- 是否返回屏幕信息：
- YES：返回屏幕和窗口信息。
- NO：仅返回窗口信息。
返回值
- 方法调用成功，返回 AgoraScreenCaptureSourceInfo 对象数组，详见 AgoraScreenCaptureSourceInfo。
- 方法调用失败，返回 nil。
setScreenCaptureScenario:
设置屏幕共享场景。
Objective-C
- (int)setScreenCaptureScenario:(AgoraScreenScenarioType)scenarioType NS_SWIFT_NAME(setScreenCaptureScenario(_:));
调用该方法设置屏幕共享场景。SDK 会根据设置的场景优化共享的视频质量和用户体验。
信息
声网建议你在加入频道前调用此方法。
参数
- scenarioType
- 屏幕共享场景。详见 AgoraScreenScenarioType。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
startScreenCapture:
开始屏幕采集。
Objective-C
- (int)startScreenCapture:(AgoraScreenCaptureParameters2* _Nullable)parameters NS_SWIFT_NAME(startScreenCapture(_:));
你可以调用该方法开始采集屏幕视频流。
信息
- 在 iOS 平台，屏幕共享仅支持 iOS 12.0 及以上版本。
- 如果你使用自定义音频源而非 SDK 采集音频，声网建议你在应用中添加保活处理逻辑，以避免应用进入后台后屏幕共享中断。
- 此功能对设备性能要求较高，声网建议在 iPhone X 及以上机型上使用。
- 此方法依赖 iOS 屏幕共享动态库
AgoraReplayKitExtension.xcframework。如果该动态库被删除，将无法正常启用屏幕共享。 - 为避免屏幕共享时系统音频采集失败，声网建议你在加入频道前通过 setAudioScenario: 方法将音频应用场景设置为
AgoraAudioScenarioGameStreaming。 - 屏幕共享流的计费基于
AgoraScreenVideoParameters中的dimensions：- 如果未传入该值，声网按 1280 × 720 计费。
- 如果传入该值，声网按传入的值计费。
适用场景
在屏幕共享场景中。
调用时机
你可以在加入频道前或加入频道后调用此方法，具体区别如下：
- 先调用此方法，再调用
joinChannelByToken加入频道，并将publishScreenCaptureVideo设置为 YES，即可开始屏幕共享。 - 加入频道后调用此方法，再调用
updateChannelWithMediaOptions并将publishScreenCaptureVideo设置为 YES，即可开始屏幕共享。
相关回调
当屏幕共享扩展进程的状态发生变化时，SDK 会触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调。当 sourceType 的类型为 AgoraVideoSourceTypeScreen 时，state 参数表示屏幕共享的状态。
参数
- parameters
- 屏幕共享的编码参数。详见
AgoraScreenCaptureParameters2。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数为 nil。
startScreenCapture:config:
开始屏幕共享。
Objective-C
- (int)startScreenCapture:(AgoraVideoSourceType)sourceType config:(AgoraScreenCaptureConfiguration * _Nullable)config NS_SWIFT_NAME(startScreenCapture(_:config:));
适用场景
适用于屏幕共享场景，支持多频道使用。
参数
- sourceType
- 屏幕来源类型，详见 AgoraVideoSourceType。
- config
- 屏幕共享的配置，详见 AgoraScreenCaptureConfiguration。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
startScreenCaptureByDisplayId:regionRect:captureParams:
通过指定屏幕 ID 采集屏幕。
Objective-C
- (int)startScreenCaptureByDisplayId:(UInt32)displayId
regionRect:(CGRect)regionRect
captureParams:(AgoraScreenCaptureParameters *_Nonnull)captureParams NS_SWIFT_NAME(startScreenCapture(byDisplayId:regionRect:captureParams:));
采集整个屏幕或部分屏幕区域的视频流。
适用场景
在屏幕共享场景中，你需要调用此方法开始采集屏幕视频流。
调用时机
你可以在加入频道前或加入频道后调用此方法，具体区别如下：
- 在加入频道前调用此方法，然后调用
joinChannelByToken加入频道，并将publishScreenTrack或publishSecondaryScreenTrack设置为 YES，以开始屏幕共享。 - 在加入频道后调用此方法，然后调用 updateChannelWithMediaOptions: 并将
publishScreenTrack或publishSecondaryScreenTrack设置为 YES，以开始屏幕共享。
参数
- displayId
- 要共享的屏幕的屏幕 ID。
- regionRect
- （可选）相对于窗口的区域位置。如果未设置该参数，SDK 共享整个窗口。该参数包含以下字段：
x：距窗口左上角的水平偏移。y：距窗口左上角的垂直偏移。width：区域的宽度。height：区域的高度。
width或height为 0，SDK 共享整个窗口。 - captureParams
- 屏幕共享配置。默认视频分辨率为 1920 × 1080，即 2,073,600 像素。声网会根据该参数的值计算费用。屏幕共享视频流的视频属性仅需通过该参数设置，与 setVideoEncoderConfiguration: 无关。详见 AgoraScreenCaptureParameters。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数无效。
- -8：屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 stopScreenCapture 停止当前共享，然后重新开始屏幕共享。
startScreenCaptureByWindowId:regionRect:captureParams:
通过指定窗口 ID 采集整个或部分窗口的屏幕内容。
Objective-C
- (int)startScreenCaptureByWindowId:(UInt32)windowId
regionRect:(CGRect)regionRect
captureParams:(AgoraScreenCaptureParameters *_Nonnull)captureParams NS_SWIFT_NAME(startScreenCapture(byWindowId:regionRect:captureParams:));
你需要指定要采集的窗口的 ID，可以采集整个窗口或窗口的部分区域。
信息
该方法仅适用于 macOS 和 Windows 平台。
适用场景
在屏幕共享场景中，你需要调用该方法开始采集屏幕视频流。
调用时机
你可以在加入频道前或加入频道后调用该方法，具体如下：
- 在加入频道前调用该方法，然后调用
joinChannelByToken加入频道，并将publishScreenTrack或publishSecondaryScreenTrack设置为 YES，以开始屏幕共享。 - 在加入频道后调用该方法，然后调用 updateChannelWithMediaOptions: 并将
publishScreenTrack或publishSecondaryScreenTrack设置为 YES，以开始屏幕共享。
参数
- windowId
- 要共享的窗口的 ID。
- regionRect
- （可选）相对于窗口的区域位置。如果未设置该参数，SDK 会共享整个窗口。该参数包含以下字段：
- x：距窗口左上角的水平偏移。
- y：距窗口左上角的垂直偏移。
- width：区域的宽度。
- height：区域的高度。
- captureParams
- 屏幕共享配置。默认视频分辨率为 1920 × 1080，即 2,073,600 像素。声网会根据该参数的值计算费用。详见 AgoraScreenCaptureParameters。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数无效。
- -8：屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 stopScreenCapture 停止当前共享，然后重新开始共享屏幕。
stopScreenCapture
停止屏幕采集。
Objective-C
- (int)stopScreenCapture NS_SWIFT_NAME(stopScreenCapture());
适用场景
适用于以下场景：
- iOS：如果你通过调用
startScreenCapture:开始屏幕采集，则需要调用此方法停止屏幕采集。 - macOS：如果你通过调用
startScreenCaptureByWindowId:regionRect:captureParams:或startScreenCaptureByDisplayId:regionRect:captureParams:开始屏幕采集，则需要调用此方法停止屏幕采集。
调用时机
你可以在加入频道前或后调用此方法。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
stopScreenCapture:
停止来自指定视频源的屏幕采集。
Objective-C
- (int)stopScreenCapture:(AgoraVideoSourceType)sourceType NS_SWIFT_NAME(stopScreenCapture(_:));
调用 startScreenCapture:config: 开始从一个或多个屏幕采集屏幕后，需调用此方法停止屏幕采集。你需要通过 sourceType 参数指定要停止的屏幕。
调用时机
你可以在加入频道前或后调用此方法。
参数
- sourceType
- 视频源的类型，详见 AgoraVideoSourceType。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
updateScreenCaptureParameters:
更新屏幕采集参数。
Objective-C
- (int)updateScreenCaptureParameters:(AgoraScreenCaptureParameters * _Nonnull)captureParams NS_SWIFT_NAME(updateScreenCaptureParameters(_:));
信息
请在开始屏幕共享或窗口共享后调用此方法。
参数
- captureParams
- 屏幕共享的编码参数。屏幕共享流的视频属性只需通过该参数设置，与 setVideoEncoderConfiguration: 无关。详见 AgoraScreenCaptureParameters。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -2：参数无效。
- -8：屏幕共享状态无效。可能是因为你已共享了其他屏幕或窗口。请尝试调用 stopScreenCapture 停止当前共享，然后重新开始共享屏幕。