屏幕共享

在互动直播或视频通话中，主播或视频通话用户可以通过声网 SDK 中的屏幕共享特性，将自己的屏幕内容以视频的方式分享给其他用户或观众观看。

屏幕共享可以应用在以下场景中：

场景	描述
在线教育	老师将自己的屏幕、教学课件、绘图软件或编程软件共享给学生，用于课堂示范
游戏直播	主播共享自己的游戏画面给观众
互动直播	主播共享自己的屏幕和观众互动
视频会议	会议成员共享屏幕观看 PPT 或者文档
远程控制	被控端向主控端展示自己的桌面

功能介绍

声网 SDK 的屏幕共享特性可提供以下功能，适用于各种场景下的屏幕共享。

共享整个屏幕

将你的整个屏幕进行共享，包括屏幕中的所有信息，该功能支持同时采集两块屏幕的信息并共享。

共享 App 窗口

如果你不希望将整个屏幕内容分享给其他用户，可以只共享一个 App 窗口中的画面。

共享指定区域

如果你只希望共享屏幕或 App 窗口中的一部分，可以在开启屏幕共享时设置一个共享区域，只有该区域内的画面会被分享。

高级功能

除上述功能外，你还可以在开启屏幕共享时通过调整参数，实现以下高级共享功能：

• 屏蔽指定 App 窗口：在共享屏幕时，如果你不希望暴露某个 App 窗口，可以选择将该 App 窗口屏蔽，则该窗口将不会出现在共享的屏幕中。
• 描边：如果你需要勾勒出正在共享的范围，可以对指定的 App 窗口或屏幕进行描边，并自定义描边的宽度、颜色和透明度。
• 前置指定 App 窗口：如果你同时共享了多个 App 窗口，可能会出现窗口之间互相遮挡的情况，你可以指定一个 App 窗口并将其前置，即可避免它被其他窗口遮挡。
• 设置共享场景：SDK 会根据你设置的场景自动调节 QOE (Quality of Experience) 策略。
  • 在共享文档、幻灯片、表格，或者远程控制时，你可以将共享场景设置为文档场景或远程控制场景，SDK 会优先保障画质，并降低接收端看共享视频的延时。
  • 在共享游戏或电影、视频直播时，你可以将共享场景设置为游戏场景或视频场景，SDK 会优先保障流畅性。

屏幕共享功能在各平台的适用情况如下：

• 桌面端（Windows 和 macOS）：支持上述所有屏幕共享功能。
• 移动端（Android 和 iOS）：仅支持共享整个屏幕。

优势介绍

声网提供的屏幕共享特性具备以下优势：

超高清画质体验

支持超高清视频（分辨率为 4K，帧率为 60 fps），给用户带来更加流畅、高清的极致画面体验。

多 App 支持

适配 WPS Office、Microsoft Office Power Point、Visual Studio Code、Adobe Photoshop、Windows Media Player 和 Scratch 等多款主流 App，方便用户在屏幕共享时直接共享指定 App、提升了功能易用性。

多设备支持

支持多设备同时共享，兼容 Window 8 系统、无独立显卡的设备、双显卡设备、外接屏幕设备等，满足各种场景下的设备使用需求。

多平台适配

支持 iOS、Andriod、macOS、Windows、Web、Unity、Flutter、React Native、Unreal Engine 等平台。

高安全保障

支持仅共享 App 和屏幕中的部分区域内容，并支持屏蔽指定 App 窗口，有效保障用户信息安全。

技术原理

根据实际业务场景的不同，你可以选择以下任一方式调用 API 实现屏幕共享：

• 在加入频道前调用 startScreenCapture，然后调用 joinChannel [2/2] 加入频道并设置 publishScreenCaptureVideo 为 true，即可开始屏幕共享。
• 在加入频道后调用 startScreenCapture，然后调用 updateChannelMediaOptions 更新频道媒体选项并设置 publishScreenCaptureVideo 为 true，即可开始屏幕共享。

注意事项

• 在开启屏幕共享后，声网以屏幕共享视频流的分辨率作为计费标准，详见计费说明。默认分辨率为 1280 × 720，你也可以根据你的业务需求进行调整。
• 受系统限制，采集屏幕仅适用于 Android API 级别为 21 及以上，即 Android 5 及以上，否则在调用 startScreenCapture 时，SDK 会报告错误码 ERR_SCREEN_CAPTURE_PERMISSION_DENIED(16) 和 ERR_SCREEN_CAPTURE_SYSTEM_NOT_SUPPORTED(2)。
• 受系统限制，采集系统音频仅适用于 Android API 级别为 29 及以上，即 Android 10 及以上，否则在调用 startScreenCapture 时，SDK 会报告错误码 ERR_SCREEN_CAPTURE_SYSTEM_AUDIO_NOT_SUPPORTED(3)。
• 因 Android 性能限制，屏幕共享不支持 Android TV。
• 因 Android 系统限制，使用华为手机进行屏幕共享时，为避免崩溃，请不要在共享过程中调节屏幕共享流的视频编码分辨率。
• 因 Android 系统限制，部分小米手机不支持屏幕共享时采集系统音频。
• 为提高屏幕共享时采集系统音频的成功率，声网推荐你在加入频道前通过 setAudioScenario 方法设置音频场景为 AUDIO_SCENARIO_GAME_STREAMING。

前提条件

• 在 Android 平台上，请确保用户已授予 App 屏幕采集权限。
• 在实现屏幕共享前，请确保已在你的项目中实现基本的实时音视频功能。详见实现音视频互动。

实现屏幕共享

本节介绍如何使用 Android SDK 实现屏幕共享。

1. 集成屏幕共享插件

声网 SDK 的屏幕共享通过插件实现，你需要集成 AgoraScreenShareExtension 动态库。 你可以根据你的集成方式，选择手动导入 aar 文件集成屏幕共享插件，或者通过 Maven Central 自动集成。

手动集成插件

1. 拷贝 SDK 中的 AgoraScreenShareExtension.aar 文件到 /app/libs/ 目录下。

2. 在 /app/build.gradle 文件的 dependencies 节点中添加如下行，以支持导入 aar 格式的文件。

   Java

   implementation fileTree(dir: "libs", include: ["*.jar","*.aar"])

自动集成插件

通过 Maven Central 集成 SDK 时，你可以修改 /Gradle Scripts/build.gradle(Module: <projectname>.app) 文件中 dependencies 的 implementation 字段添加依赖。

Java

dependencies {
// 请使用具体的 SDK 版本号替换下面代码中的 x.y.z，可通过发版说明获取最新版本号      
def agora_sdk_version = "x.y.z"
// 下述代码中包含 $，因此你必须使用 ""，不能使用 ''

// 集成方案 1
implementation "io.agora.rtc:full-rtc-basic:${agora_sdk_version}"
implementation "io.agora.rtc:full-screen-sharing:${agora_sdk_version}"
implementation "io.agora.rtc:screen-capture:${agora_sdk_version}"

// 集成方案 2
implementation "io.agora.rtc:full-sdk:${agora_sdk_version}"
implementation "io.agora.rtc:full-screen-sharing:${agora_sdk_version}"
...
}

2. （可选）添加前台服务权限

如果你的 Android 版本为 Android 9 及以上，需要在 /app/Manifests/AndroidManifest.xml 文件中添加如下前台服务权限，以避免应用退后台后被系统杀死。

Java

android.permission.FOREGROUND_SERVICE

3. 调用 API

在需要将多路视频流同时发布到频道的场景下，你需要先加入一个频道，在该频道中发布一路视频流（比如屏幕共享流）；然后加入第二个频道，在该频道中发布另一路视频流（比如摄像头采集的视频流），示例代码如下：

Java

public void onCheckedChanged(CompoundButton compoundButton, boolean b) {
    if (compoundButton.getId() == R.id.screenShare) {
        if (Build.VERSION.SDK_INT > Build.VERSION_CODES.LOLLIPOP) {
            if(b){
                if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
                    getActivity().startForegroundService(fgServiceIntent);
                }
                DisplayMetrics metrics = new DisplayMetrics();
                getActivity().getWindowManager().getDefaultDisplay().getRealMetrics(metrics);
                ScreenCaptureParameters parameters = new ScreenCaptureParameters();
                parameters.videoCaptureParameters.width = 720;
                parameters.videoCaptureParameters.height = (int) (720 * 1.0f / metrics.widthPixels * metrics.heightPixels);
                parameters.videoCaptureParameters.framerate = DEFAULT_SHARE_FRAME_RATE;
                parameters.captureAudio = true;
                // 开始屏幕共享
                engine.startScreenCapture(parameters);
                // 更新频道媒体选项，发布屏幕采集的音频和视频
                options.publishScreenCaptureVideo = true;
                options.publishScreenCaptureAudio = true;
                // 不发布摄像头采集的视频
                options.publishCameraTrack = false;
                engine.updateChannelMediaOptions(options);
                addScreenSharePreview();
            }
            else{
                // 停止屏幕共享
                engine.stopScreenCapture();
                if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
                    getActivity().stopService(fgServiceIntent);
                }
                // 更新频道媒体选项，停止发布屏幕采集的视频和音频
                options.publishScreenCaptureVideo = false;
                options.publishScreenCaptureAudio = false;
                engine.updateChannelMediaOptions(options);
            }
            screenSharePreview.setEnabled(b);
            screenSharePreview.setChecked(b);
        } else {
            showAlert(getString(R.string.lowversiontip));
        }
    } else if (compoundButton.getId() == R.id.camera) {
            if(b){
                ChannelMediaOptions mediaOptions = new ChannelMediaOptions();
                mediaOptions.autoSubscribeAudio = false;
                mediaOptions.autoSubscribeVideo = false;
                mediaOptions.publishScreenCaptureVideo = false;
                // 在多频道中发布摄像头采集的视频
                mediaOptions.publishCameraTrack = true;
                mediaOptions.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER;
                mediaOptions.channelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING;
                rtcConnection2.channelId = et_channel.getText().toString();
                rtcConnection2.localUid = new Random().nextInt(512)+512;
                // 加入多频道
                engine.joinChannelEx(null,rtcConnection2,mediaOptions,iRtcEngineEventHandler);
            }
            else{
                engine.leaveChannelEx(rtcConnection2);
                engine.startPreview(Constants.VideoSourceType.VIDEO_SOURCE_CAMERA_PRIMARY);
            }
    }else if (compoundButton.getId() == R.id.screenSharePreview) {
        if(b){
            addScreenSharePreview();
        }else{
            fl_screen.removeAllViews();
            engine.stopPreview(Constants.VideoSourceType.VIDEO_SOURCE_SCREEN_PRIMARY);
        }
    }
}

参考信息

示例项目

我们在 GitHub 上提供开源示例项目供你参考。

API 参考

• startScreenCapture
• updateScreenCaptureParameters
• stopScreenCapture