需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

屏幕采集

  • macOS

更新时间不可用

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：仅返回窗口信息。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

所属接口类

setScreenCaptureScenario:

设置屏幕共享场景。

Objective-C
- (int)setScreenCaptureScenario:(AgoraScreenScenarioType)scenarioType  NS_SWIFT_NAME(setScreenCaptureScenario(_:));

调用该方法设置屏幕共享场景。SDK 会根据设置的场景优化共享的视频质量和用户体验。

注： 声网建议你在加入频道前调用此方法。

参数

参数名描述
scenarioType

屏幕共享场景。详见 AgoraScreenScenarioType。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

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：区域的高度。

如果指定的区域超出窗口范围，SDK 仅共享窗口内的区域；如果设置 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：区域的高度。

如果指定的区域超出窗口范围，SDK 只共享窗口内的区域；如果设置 width 或 height 为 0，SDK 会共享整个窗口。

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 停止当前共享，然后重新开始共享屏幕。

所属接口类

updateScreenCaptureRegion:

更新屏幕采集区域。

Objective-C
- (int)updateScreenCaptureRegion:(CGRect)rect  NS_SWIFT_NAME(updateScreenCaptureRegion(_:));

你可以通过该方法更新屏幕或窗口的采集区域。

参数

参数名描述
rect

相对于屏幕或窗口的区域位置。

  • 如果不设置该参数，SDK 会共享整个屏幕。
  • 如果指定的区域超出屏幕或窗口范围，SDK 仅共享其中的区域。
  • 如果设置的宽度或高度为 0，SDK 会共享整个屏幕或窗口。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利