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

屏幕采集

  • Electron

更新时间不可用

getScreenCaptureSources

获取可共享的屏幕和窗口对象列表。

TypeScript
abstract getScreenCaptureSources(
    thumbSize: Size,
    iconSize: Size,
    includeScreen: boolean
  ): ScreenCaptureSourceInfo[];

屏幕共享或窗口共享前，你可以调用该方法获取可共享的屏幕和窗口的对象列表，方便用户通过列表中的缩略图选择共享某个显示器的屏幕或某个窗口。列表中包含窗口 ID 和屏幕 ID 等重要信息，你可以获取到 ID 后再调用 startScreenCaptureByWindowId 或 startScreenCaptureByDisplayId 开启共享。

参数

参数名描述
thumbSize

屏幕或窗口的缩略图的目标尺寸（宽高单位为像素）。SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，thumbSize 为 100 x 100，缩略图实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，缩略图即为原图，SDK 不进行缩放操作。

iconSize

程序所对应的图标的目标尺寸（宽高单位为像素）。SDK 会在保证原图不变形的前提下，缩放原图，使图片最长边和目标尺寸的最长边的长度一致。例如，原图宽高为 400 × 300，iconSize 为 100 × 100，图标实际尺寸为 100 × 75。如果目标尺寸大于原图尺寸，图标即为原图，SDK 不进行缩放操作。

includeScreen

除了窗口信息外，SDK 是否返回屏幕信息：

  • true：SDK 返回屏幕和窗口信息。
  • false：SDK 仅返回窗口信息。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

ScreenCaptureSourceInfo 数组。

所属接口类

setScreenCaptureContentHint

设置屏幕共享内容类型。

TypeScript
abstract setScreenCaptureContentHint(contentHint: VideoContentHint): number;

SDK 会根据不同的内容类型，使用不同的算法对共享效果进行优化。如果不调用该方法，SDK 会将屏幕共享的内容默认为 ContentHintNone，即无指定的内容类型。

注： 该方法在开始屏幕共享前后都能调用。

参数

参数名描述
contentHint

屏幕共享的内容类型。详见 VideoContentHint。

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

返回值

  • 0: 方法调用成功。

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

    • -2：传入的参数无效。
    • -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture 停止当前共享，再重新开始共享屏幕。

所属接口类

setScreenCaptureScenario

设置屏幕共享的场景。

TypeScript
abstract setScreenCaptureScenario(screenScenario: ScreenScenarioType): number;

开启屏幕共享或窗口共享时，你可以调用该方法设置屏幕共享的场景，SDK 会根据你设置的场景调整共享画面的画质。

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

参数

参数名描述
screenScenario

屏幕共享的场景，详见 ScreenScenarioType。

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

返回值

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

所属接口类

startScreenCaptureBySourceType

开始屏幕采集并指定视频源。

TypeScript
abstract startScreenCaptureBySourceType(
    sourceType: VideoSourceType,
    config: ScreenCaptureConfiguration
  ): number;

注： 该方法仅适用于 macOS 和 Windows 平台。

  • 如果调用该方法开始屏幕采集，则停止屏幕采集时需要调用 stopScreenCaptureBySourceType。
  • 在 Windows 平台上，最多支持 4 路屏幕采集的视频流。
  • 在 macOS 平台上，最多支持 1 路屏幕采集的视频流。

适用场景

在屏幕共享场景下，你需要调用该方法开始采集屏幕视频流。 SDK 支持一系列开启屏幕采集的方法，它们之间存在以下区别，请根据实际场景选用：

  • startScreenCaptureByDisplayId/startScreenCaptureByWindowId：仅支持采集单个屏幕或窗口，适合仅共享单个屏幕的场景。
  • startScreenCaptureBySourceType：支持指定多个视频源，以采集多路屏幕共享流，用于本地合图或者多频道发布场景。

调用时机

该方法在加入频道前后均可调用，区别如下：

  • 如果在加入频道前调用该方法，然后调用 joinChannel 加入频道，并设置 publishScreenCaptureVideo 为 true，即可开始屏幕共享。
  • 如果在加入频道后调用该方法，然后调用 updateChannelMediaOptions 更新频道媒体选项，并设置 publishScreenCaptureVideo 为 true，即可开始屏幕共享。

参数

参数名描述
sourceType

视频源的类型，详见 VideoSourceType。

注： 在 macOS 平台上，仅支持将该参数设置为 VideoSourceScreen (2)。

config

屏幕采集配置。详见 ScreenCaptureConfiguration。

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

返回值

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

所属接口类

startScreenCaptureByDisplayId

开始采集指定屏幕的视频流。

TypeScript
abstract startScreenCaptureByDisplayId(
    displayId: number,
    regionRect: Rectangle,
    captureParams: ScreenCaptureParameters
  ): number;

采集一个屏幕或该屏幕部分区域的视频流。

适用场景

在屏幕共享场景下，你需要调用该方法开始采集屏幕视频流。有关屏幕共享的实现方法，详见屏幕共享。

调用时机

该方法在加入频道前后均可调用，区别如下：

  • 如果在加入频道前调用该方法，然后调用 joinChannel 加入频道，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。
  • 如果在加入频道后调用该方法，然后调用 updateChannelMediaOptions 更新频道媒体选项，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。

参数

参数名描述
displayId

指定待共享的屏幕 ID。

注： 对于 Windows 平台，如果你需要同时共享两个屏幕（主屏 + 副屏），可以在调用该方法时，将 displayId 设置为 -1。

regionRect

（可选）指定待共享区域相对于整个屏幕的位置。如需共享整个屏幕，则填 nil。

captureParams

屏幕共享的参数配置。默认的视频编码分辨率为 1920 × 1080，即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。

注： 屏幕共享流的视频属性只需通过该参数设置，与 setVideoEncoderConfiguration 无关。

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

返回值

  • 0: 方法调用成功。

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

    • -2：传入的参数无效。
    • -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture 停止当前共享，再重新开始共享屏幕。

所属接口类

startScreenCaptureByScreenRect

开始采集指定屏幕区域的视频流。

TypeScript
abstract startScreenCaptureByScreenRect(
    screenRect: Rectangle,
    regionRect: Rectangle,
    captureParams: ScreenCaptureParameters
  ): number;

废弃

弃用： 该方法已废弃。请改用 startScreenCaptureByDisplayId。如果你需要在设备外接其他显示屏的情况下开启屏幕共享，强烈建议你使用 startScreenCaptureByDisplayId。

共享一个屏幕或该屏幕的部分区域。你需要在该方法中指定想要共享的屏幕区域。 该方法在加入频道前后均可调用，区别如下：

  • 如果在加入频道前调用该方法，然后调用 joinChannel 加入频道，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。
  • 如果在加入频道后调用该方法，然后调用 updateChannelMediaOptions 更新频道媒体选项，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。

注： 该方法仅适用于 Windows 平台。

参数

参数名描述
screenRect

指定待共享的屏幕相对于虚拟屏的位置。

regionRect

指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕。

captureParams

屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。

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

返回值

  • 0: 方法调用成功。

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

    • -2：传入的参数无效。
    • -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture 停止当前共享，再重新开始共享屏幕。

所属接口类

startScreenCaptureByWindowId

开始采集指定窗口的视频流。

TypeScript
abstract startScreenCaptureByWindowId(
    windowId: any,
    regionRect: Rectangle,
    captureParams: ScreenCaptureParameters
  ): number;

共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。 该方法支持共享通用 Windows 平台（UWP）应用窗口。声网使用最新版 SDK 对主流的 UWP 应用进行了测试，结果如下：

系统版本软件名称兼容版本是否支持
Windows 10Chrome76.0.3809.100否
Office Word18.1903.1152.0是
Office Excel18.1903.1152.0否
Office PPT18.1903.1152.0是
WPS Word11.1.0.9145是
WPS Excel11.1.0.9145是
WPS PPT11.1.0.9145是
系统自带的 Media Player所有版本是
Windows 8Chrome所有版本是
Office Word所有版本是
Office Excel所有版本是
Office PPT所有版本是
WPS Word11.1.0.9098是
WPS Excel11.1.0.9098是
WPS PPT11.1.0.9098是
系统自带的 Media Player所有版本是
Windows 7Chrome73.0.3683.103否
Office Word所有版本是
Office Excel所有版本是
Office PPT所有版本是
WPS Word11.1.0.9098否
WPS Excel11.1.0.9098否
WPS PPT11.1.0.9098是
系统自带的 Media Player所有版本否
表格内容超出当前宽度，可横向滚动查看更多列。

注： 该方法仅适用于 macOS 和 Windows 平台。 SDK 的窗口共享功能依赖于 WGC（Windows Graphics Capture）或 GDI（Graphics Device Interface）采集，WGC 在早于 Windows 10 2004 的系统上无法设置关闭鼠标采集，因此，当你在搭载早于 Windows 10 2004 系统的设备上进行窗口共享时，可能出现 captureMouseCursor(false) 不生效的现象。详见 ScreenCaptureParameters。

适用场景

在屏幕共享场景下，你需要调用该方法开始采集屏幕视频流。有关屏幕共享的实现方法，详见屏幕共享。

调用时机

该方法在加入频道前后均可调用，区别如下：

  • 如果在加入频道前调用该方法，然后调用 joinChannel 加入频道，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。
  • 如果在加入频道后调用该方法，然后调用 updateChannelMediaOptions 更新频道媒体选项，并设置 publishScreenTrack 或 publishSecondaryScreenTrack 为 true，即可开始屏幕共享。

参数

参数名描述
windowId

指定待共享的窗口 ID。

regionRect

（可选）指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容；如果宽或高为 0，则共享整个窗口。

注： Electron for 统信 OS SDK 暂不支持该参数。

captureParams

屏幕共享的参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。

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

返回值

  • 0: 方法调用成功。

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

    • -2：传入的参数无效。
    • -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture 停止当前共享，再重新开始共享屏幕。

所属接口类

stopScreenCapture

停止屏幕采集。

TypeScript
abstract stopScreenCapture(): number;

适用场景

如果你调用了 startScreenCaptureBySourceType、startScreenCaptureByWindowId 或 startScreenCaptureByDisplayId 开启屏幕采集，则停止屏幕采集时需要调用该方法。

调用时机

该方法在加入频道前后均可调用。

返回值

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

所属接口类

stopScreenCaptureBySourceType

停止对指定的视频源进行屏幕采集。

TypeScript
abstract stopScreenCaptureBySourceType(sourceType: VideoSourceType): number;

适用场景

如果你调用了 startScreenCaptureBySourceType 开启一路或多路屏幕采集，则停止屏幕采集时需要调用该方法，并通过 sourceType 参数指定屏幕。

调用时机

该方法在加入频道前后均可调用。

参数

参数名描述
sourceType

视频源的类型，详见 VideoSourceType。

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

返回值

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

所属接口类

updateScreenCaptureParameters

更新屏幕采集的参数配置。

TypeScript
abstract updateScreenCaptureParameters(
    captureParams: ScreenCaptureParameters
  ): number;

注：

  • 请在开启屏幕共享或窗口共享后调用该方法。

参数

参数名描述
captureParams

屏幕共享的编码参数配置。详见 ScreenCaptureParameters。

注： 屏幕共享流的视频属性只需通过该参数设置，与 setVideoEncoderConfiguration 无关。

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

返回值

  • 0: 方法调用成功。

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

    • -2：传入的参数无效。
    • -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture 停止当前共享，再重新开始共享屏幕。

所属接口类

updateScreenCaptureRegion

更新屏幕采集的区域。

TypeScript
abstract updateScreenCaptureRegion(regionRect: Rectangle): number;

注： 请在开启屏幕共享或窗口共享后调用该方法。

参数

参数名描述
regionRect

待共享区域相对于整个屏幕或窗口的位置，如不填，则表示共享整个屏幕或窗口。详见 Rectangle。如果设置的共享区域超出了屏幕或窗口的边界，则只共享屏幕或窗口内的内容；如果将 width 或 height 设为 0，则共享整个屏幕或窗口。

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

返回值

  • 0: 方法调用成功。

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

    • -2：传入的参数无效。
    • -8：屏幕共享状态无效。可能因为你已经共享了其他屏幕或窗口。尝试调用 stopScreenCapture 停止当前共享，再重新开始共享屏幕。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利