屏幕共享
简介
Pano SDK 支持将屏幕画面分享给其他用户,屏幕共享可以和视频画面同时发送/接收。
各端 SDK 相关接口,请查看下列介绍:
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 会自动取消订阅,这种情况不必调用取消订阅方法。