屏幕共享 · Pano开发者中心

简介

Pano SDK 支持将屏幕画面分享给其他用户，屏幕共享可以和视频画面同时发送/接收。

各端 SDK 相关接口，请查看下列介绍：

Windows (C++)
macOS (Objective-C)
iOS (Objective-C)
Android (Java)
Web
Electron

Windows (C++)

屏幕共享事件通知

通过继承 RtcEngine::Callback 类，重写回调接口来处理 Pano SDK 返回的通知。
和屏幕共享有关的事件通知如：

onUserScreenStart 其他用户开启屏幕共享
onUserScreenStop 其他用户关闭屏幕共享
onUserScreenMute 其他用户暂停屏幕共享
onUserScreenUnmute 其他用户恢复屏幕共享
onUserScreenSubscribe 订阅其他用户屏幕共享的结果(仅订阅失败时回调)
onFirstScreenFrameRendered 收到其他用户的第一个屏幕共享画面
onScreenStartResult 自己开启屏幕共享的结果

通过 RtcEngine::setScreenCaptureObserver 方法设置屏幕共享抓屏观察器(ScreenCaptureObserver)，相应的事件通知如：

onScreenCaptureDisplayChanged 抓取显示器发生变化的通知
onScreenCaptureWindowsChanged 抓取窗口发生变化的通知
onScreenCaptureRegionChanged 抓屏区域发生变化的通知

ScreenCaptureObserver 的事件通知仅适用于和 Electron SDK 交互，通常不需要使用。

屏幕共享源管理

通过 RtcEngine::getScreenSourceManager 方法获取屏幕共享源管理器(ScreenSourceManager)，相关方法如：

ScreenSourceManager::enumerateDisplays 枚举显示屏幕
ScreenSourceManager::enumerateApplications 枚举应用
ScreenSourceManager::enumerateWindows 枚举窗口
ScreenSourceManager::enableFilterSelfApp 设置是否过滤自己的进程（设置后当前进程的画面不会被共享出去）
ScreenSourceManager::setScreenOptimization 设置屏幕共享模式(通常无需设置，默认 forMotion 为 false，适用于大多数场景)
ScreenSourceManager::setScreenSource 设置屏幕共享源

以下为屏幕共享源管理高级接口（适用于特殊场景，通常不需要使用）：

ScreenSourceManager::beginConfiguration 开始配置，调用此接口后，才可以调用下列其他接口
ScreenSourceManager::selectSharedDisplay 选择需要共享的显示器
ScreenSourceManager::addSharedScreenSource 添加屏幕共享源
ScreenSourceManager::removeSharedScreenSource 移除指定的屏幕共享源
ScreenSourceManager::addUnsharedScreenSource 添加不希望被共享的屏幕源
ScreenSourceManager::removeUnsharedScreenSource 移除指定的不被共享的屏幕源
ScreenSourceManager::commitConfiguration 提交配置

开启屏幕共享

通过 RtcEngine::startScreen 方法开启屏幕共享。

请在加入频道成功后再调用此接口。

可以使用 updateScreenConfig(const ScreenConfig &config) 方法更新屏幕共享设置。

停止屏幕共享

通过 RtcEngine::stopScreen 方法停止屏幕共享。

暂停与恢复屏幕共享

通过 RtcEngine::muteScreen 方法暂停屏幕共享，RtcEngine::unmuteScreen 方法恢复屏幕共享。

订阅其他用户的屏幕共享

通过 RtcEngine::subscribeScreen 方法订阅其他用户的屏幕共享。
subscribeScreen 有两个重载方法，参数类型不同，一个传入数据接收槽，一个传入显示渲染窗口。

请在收到"其他用户开启屏幕共享"通知后再订阅该用户的屏幕共享。

取消订阅屏幕共享

通过 RtcEngine::unsubscribeScreen 方法取消订阅其他用户的屏幕共享。

其他用户停止屏幕共享时，Pano SDK 会自动取消订阅，这种情况不必调用取消订阅方法。

其他高级功能

以下高级接口用于接收方设置显示效果：

RtcEngine::updateScreenScalingRatio 更新整个屏幕共享的缩放比例（绝对缩放）
RtcEngine::updateScreenScalingRatioWithFocus 基于特定坐标点更新屏幕共享的缩放比例（相对缩放，例如，基于某个坐标点操作双指缩放）
RtcEngine::updateScreenMovingDistance 移动屏幕共享的显示位置

macOS (Objective-C)

注意：在版本 10.15 之后的 macOS 上，需要用户在「系统偏好设置 - 安全性与隐私 - 隐私 - 屏幕录制」中添加允许 App 录制屏幕，否则进行屏幕共享时，只能获取桌面背景，无法获取整个屏幕上的内容。开发者需要自行处理权限检测以及弹出窗口提示。

屏幕共享事件通知

通过实现 PanoRtcEngineDelegate 协议的回调方法来处理 Pano SDK 返回的通知。
和屏幕共享有关的事件通知如：

- onUserScreenStart: 其他用户开启屏幕共享
- onUserScreenStop: 其他用户关闭屏幕共享
- onUserScreenMute: 其他用户暂停屏幕共享
- onUserScreenUnmute: 其他用户恢复屏幕共享
- onUserScreenSubscribe:withResult: 订阅其他用户屏幕共享的结果(仅订阅失败时回调)
- onFirstScreenFrameRendered: 收到其他用户的第一个屏幕共享画面
- onScreenSendStats: 开启屏幕共享的统计
- onScreenRecvStats: 接收屏幕共享的统计

屏幕共享源管理

PanoRtcEngineKit 的屏幕共享源管理相关方法如：

- enumerateScreenSources: 枚举屏幕共享源（通过 PanoScreenSourceType 参数指定屏幕共享源类型：屏幕、应用、窗口）
- enableSreenFilterSelfApp: 设置是否过滤自己的进程（设置后当前进程的画面不会被共享出去）
- setScreenOptimization: 设置屏幕共享模式(通常无需设置，默认 forMotion 为 false，适用于大多数场景)
- setScreenSource:withType: 设置屏幕共享源

以下为屏幕共享源管理高级接口（适用于特殊场景，通常不需要使用）：

- beginScreenConfiguration: 开始配置，调用此接口后，才可以调用下列其他接口
- selectSharedScreen: 选择需要共享的屏幕
- addSharedScreenSource:withType: 添加屏幕共享源
- removeSharedScreenSource:withType: 移除指定的屏幕共享源
- addUnsharedScreenSource:withType: 添加不希望被共享的屏幕源
- removeUnsharedScreenSource:withType: 移除指定的不被共享的屏幕源
- commitScreenConfiguration 提交配置

开启屏幕共享

通过 PanoRtcEngineKit 的 - startScreen 方法开启屏幕共享。

请在加入频道成功后再调用此接口。

停止屏幕共享

通过 PanoRtcEngineKit 的 - stopScreen 方法停止屏幕共享。

暂停与恢复屏幕共享

通过 PanoRtcEngineKit 的 - muteScreen 方法暂停屏幕共享，- unmuteScreen 方法恢复屏幕共享。

订阅其他用户的屏幕共享

通过 PanoRtcEngineKit 的 - subscribeScreen:withView: 或 - subscribeScreen:withDelegate: 方法订阅其他用户的屏幕共享。
前者附带渲染视图，后者附带外置渲染器。

请在收到"其他用户开启屏幕共享"通知后再订阅该用户的屏幕共享。

取消订阅屏幕共享

通过 PanoRtcEngineKit 的 - unsubscribeScreen: 方法取消订阅其他用户的屏幕共享。

其他用户停止屏幕共享时，Pano SDK 会自动取消订阅，这种情况不必调用取消订阅方法。

其他高级功能

PanoRtcEngineKit 的以下高级接口用于接收方设置显示效果：

- updateScreenScaling:withRatio: 更新整个屏幕共享的缩放比例（绝对缩放）
- updateScreenScaling:withRatio:focus: 基于特定坐标点更新屏幕共享的缩放比例（相对缩放，例如，基于某个坐标点操作双指缩放）
- updateScreenMoving:withDistance: 移动屏幕共享的显示位置

iOS (Objective-C)

iOS 屏幕共享的相关介绍，请点此查看。

Android (Java)

前提条件

使用屏幕共享功能：

需要 Android 5.0 及以上版本。

需要在 AndroidManifest.xml 中添加以下 Activity 及相应 Theme：

<activity
    android:name="video.pano.rtc.impl.screen.PanoScreenCaptureAssistantActivity"
    android:theme="@android:style/Theme.Translucent"/>

屏幕共享事件通知

通过实现 RtcEngineCallback 接口的回调方法来处理 Pano SDK 返回的通知。和屏幕共享有关的事件通知如：

onUserScreenStart 其他用户开启屏幕共享
onUserScreenStop 其他用户关闭屏幕共享
onUserScreenMute 其他用户暂停屏幕共享
onUserScreenUnmute 其他用户恢复屏幕共享
onUserScreenSubscribe 订阅其他用户屏幕共享的结果(仅订阅失败时回调)
onFirstScreenFrameRendered 收到其他用户的第一个屏幕共享画面
onScreenStartResult 自己开启屏幕共享的结果

开启屏幕共享

通过 RtcEngine 实例的 startScreen 方法开启屏幕共享。

请在加入频道成功后再调用此接口。

注意：targetSdkVersion >= 29 时，由于 Android 系统限制，录制屏幕需要先启动前台 Service (此 Service 需要开发者自定义并在 AndroidManifest.xml 中注册)；启动 Service 后，再调用 startScreen 方法。

<!-- 在 `manifest` 根元素内添加权限 -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

<!-- 自定义并注册 Service 到 application 中：
     # service 的 name 可以由开发者自定义
     # enabled 和 foregroundServiceType 属性需要按照下列配置 -->
<application
    <service
        android:name=".ScreenCaptureService"
        android:enabled="true"
        android:foregroundServiceType="mediaProjection" />
    ...
</application>

开启屏幕共享的示例代码：

// targetSdkVersion >= 29 时，需要使用前台 Service
mScreenCaptureIntent = new Intent(this, ScreenCaptureService.class);
startForegroundService(mScreenCaptureIntent);
rtcEngine().startScreen();

停止屏幕共享

通过 RtcEngine 实例的 stopScreen 方法停止屏幕共享。

rtcEngine().stopScreen();
// 如果使用了前台 Service，请在停止屏幕共享时将前台 Service 一并停止
stopService(mScreenCaptureIntent);

订阅其他用户的屏幕共享

通过 RtcEngine 实例的 subscribeScreen 方法订阅其他用户的屏幕共享，通过 setRemoteScreenRender(long userId, IVideoRender render) 方法设置显示该用户屏幕共享的画布。

请在收到"其他用户开启屏幕共享"通知后再订阅该用户的屏幕共享。

画布的设置方法，和 setLocalVideoRender 时类似，具体请点此查看。

取消订阅屏幕共享

通过 RtcEngine 实例的 unsubscribeScreen 方法取消订阅其他用户的屏幕共享。

其他用户停止屏幕共享时，Pano SDK 会自动取消订阅，这种情况不必调用取消订阅方法。

Web

集成 Web 屏幕共享前，请参考浏览器兼容性。

屏幕共享事件通知

通过 RtcEngine 实例的 on 方法注册回调通知。和屏幕共享有关的事件通知如：

getLocalScreen 获取本地屏幕共享成功，会返回 videoTag 用于 UI 展示
getScreenMediaFailed 获取本地屏幕共享失败（未授权或取消了共享）
startScreenTimeout 开启屏幕共享超时
localScreenEnded SDK已停止本地屏幕共享（例如用户关闭了共享的应用程序）
userScreenStart 其他用户开启屏幕共享
userScreenStop 其他用户关闭屏幕共享
userScreenMute 其他用户暂停屏幕共享
userScreenUnmute 其他用户恢复屏幕共享
userScreenReceived 收到其他用户的屏幕共享数据，会返回 videoTag 用于 UI 展示
failedToSubscribeScreen 订阅其他用户的共享屏幕失败

开启屏幕共享

通过 RtcEngine 的 startScreen 方法开启屏幕共享。

请在加入频道成功后再调用此接口。

开启屏幕共享可能失败，请注意处理 getScreenMediaFailed、startScreenTimeout 通知。

如需在本地显示屏幕共享，请处理 getLocalScreen 通知。

停止屏幕共享

通过 RtcEngine 的 stopScreen 方法停止屏幕共享。

暂停与恢复屏幕共享

通过 RtcEngine 的 muteScreen 方法暂停屏幕共享，unmuteScreen 方法恢复屏幕共享。

订阅其他用户的屏幕共享

通过 RtcEngine 的 subscribeScreen 方法订阅其他用户的屏幕共享。

请在收到"其他用户开启屏幕共享"通知后再订阅该用户的屏幕共享。

取消订阅屏幕共享

通过 RtcEngine 的 unsubscribeScreen 方法取消订阅其他用户的屏幕共享。

其他用户停止屏幕共享时，Pano SDK 会自动取消订阅，这种情况不必调用取消订阅方法。

Electron

屏幕共享事件通知

通过 RtcEngine 实例的 on 方法注册事件通知。和屏幕共享有关的事件通知如：

userScreenStart 其他用户开启屏幕共享
userScreenStop 其他用户关闭屏幕共享
userScreenMute 其他用户暂停屏幕共享
userScreenUnmute 其他用户恢复屏幕共享
userScreenSubscribe 订阅其他用户屏幕共享的结果(仅订阅失败时回调)
firstScreenFrameRendered 收到其他用户的第一个屏幕共享画面
screenStartResult 自己开启屏幕共享的结果

以下通知适用于 Electron 和 C++ SDK 交互，通常不需要使用：

screenCaptureDisplayChanged 抓取显示器发生变化的通知
screenCaptureWindowsChanged 抓取窗口发生变化的通知
screenCaptureRegionChanged 抓屏区域发生变化的通知
userScreenResolutionChanged 接收的屏幕共享分辨率发生变化的通知

示例代码：

rtcEngine.on('userScreenStart', userId => { ... });
rtcEngine.on('userScreenStop', userId => { ... });
rtcEngine.on('userScreenMute', userId => { ... });
rtcEngine.on('userScreenUnmute', userId => { ... });
rtcEngine.on('userScreenSubscribe', (userId, result) => { ... });
rtcEngine.on('firstScreenFrameRendered', userId => { ... });
rtcEngine.on('screenStartResult', result => { ... });

屏幕共享源管理

SDK 不提供获取预览的功能，请使用 Electron 自带的方法，具体内容请点此查看。

通过 RtcEngine 实例的 screenSourceMgr() 方法获取屏幕共享源管理器，相关方法如：

getDisplayList() 枚举显示屏幕
getApplicationList() 枚举应用
setScreenOptimization(forMotion) 设置屏幕共享模式
- forMotion 表示高帧率采集(用于内容变化剧烈场景)，可选值：true 或 false (默认值 false，通常无需设置，适用于大多数场景)
setScreenSource(sourceType, ssid) 设置屏幕共享源
- sourceType 可选值：ScreenSourceType.Display (桌面)、ScreenSourceType.Application (应用)、ScreenSourceType.Window (窗口)
- ssid 为字符串类型，可以通过 getDisplayList() 或 getApplicationList() 方法获取

示例代码：

const { ScreenSourceType } = require('@pano.video/panortc-electron-sdk');
let screenSourceMgr = rtcEngine.screenSourceMgr(); // 获取屏幕共享源管理器
let displayList = screenSourceMgr.getDisplayList(); // 枚举显示屏幕
console.info('displayList:', displayList);
// [{name: "1.Generic PnP Monitor", ssid: "65588"}, {name: "2.2490W1", ssid: "131073"}]
let applicationList = screenSourceMgr.getApplicationList(); // 枚举应用
console.info('applicationList:', applicationList);
screenSourceMgr.setScreenSource(ScreenSourceType.Display, '131073');

以下为屏幕共享源管理高级接口（适用于特殊场景，通常不需要使用）：

beginConfiguration(resetConfig) 开始配置，调用此接口后，才可以调用下列其他接口
resetConfig 是否重置当前配置，可选值：true 或 false
selectSharedDisplay(ssid) 选择需要共享的显示器
addSharedScreenSource(sourceType, ssid) 添加屏幕共享源
removeSharedScreenSource(sourceType, ssid) 移除指定的屏幕共享源
addUnsharedScreenSource(sourceType, ssid) 添加不希望被共享的屏幕源
removeUnsharedScreenSource(sourceType, ssid) 移除指定的不被共享的屏幕源
commitConfiguration() 提交配置

开启屏幕共享

通过 RtcEngine 实例的 startScreen(options) 方法开启屏幕共享，可以通过 updateScreenOptions(options) 方法更新屏幕共享设置。

请在加入频道成功后再调用此接口。

如果不传 option 参数，默认值为：{profile: VideoProfileType.HD1080P, fps: 5}。

停止屏幕共享

通过 RtcEngine 实例的 stopScreen() 方法停止屏幕共享。

暂停与恢复屏幕共享

通过 RtcEngine 实例的 muteScreen() 方法暂停屏幕共享，unmuteScreen() 方法恢复屏幕共享。

订阅其他用户的屏幕共享

通过 RtcEngine 实例的 subscribeScreen(userId, view) 方法订阅其他用户的屏幕共享。

请在收到"其他用户开启屏幕共享"通知后再订阅该用户的屏幕共享。

取消订阅屏幕共享

通过 RtcEngine 实例的 unsubscribeScreen(userId) 方法取消订阅其他用户的屏幕共享。

其他用户停止屏幕共享时，Pano SDK 会自动取消订阅，这种情况不必调用取消订阅方法。