# 屏幕共享 (/zh-CN/realtime-media/rtc/build/video/screen-share/blueprint)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在互动直播或视频通话中,主播或视频通话用户可以通过声网 SDK 中的屏幕共享特性,将自己的屏幕内容以视频的方式分享给其他用户或观众观看。
屏幕共享可以应用在以下场景中:
| 场景 | 描述 |
| :------- | :----------------------------------------------------------- |
| 在线教育 | 老师将自己的屏幕、教学课件、绘图软件或编程软件共享给学生,用于课堂示范 |
| 游戏直播 | 主播共享自己的游戏画面给观众 |
| 互动直播 | 主播共享自己的屏幕和观众互动 |
| 视频会议 | 会议成员共享屏幕观看 PPT 或者文档 |
| 远程控制 | 被控端向主控端展示自己的桌面 |
本文介绍如何使用声网 Unreal SDK 4.x 在 Android、iOS、macOS 和 Windows 平台实现屏幕共享。
## 前提条件 [#前提条件-10]
在实现屏幕共享前,请确保已在你的项目中实现基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 技术原理 [#技术原理-10]
Android & iOS
Windows & macOS
由于 Apple 不支持在 App 主进程采集屏幕,如需在 iOS 实现屏幕共享,你需要为屏幕共享流单独创建一个 Extension,并在 Extension 中使用 iOS 原生的 ReplayKit 框架实现录制屏幕,然后将屏幕共享流发送给主进程。如下图所示:

参考 [iOS ScreenShare Guide](https://github.com/AgoraIO-Extensions/Agora-Unreal-RTC-SDK/blob/main/Agora-Unreal-SDK-CPP-Example/IOS%20ScreenShare%20Guide.md) 为你的 Unreal 项目创建 Extension。
声网目前在 macOS/Windows 平台上支持以下两种屏幕共享方案:
- 通过 `displayId` 共享指定屏幕,或指定屏幕的部分区域。
- 通过 `windowId` 共享指定窗口,或指定窗口的部分区域。
API 的调用时序如下图所示:

## 实现步骤 [#实现步骤-4]
Android & iOS
Windows & macOS
本小节介绍如何在移动端调用 `StartScreenCapture` 和 `StopScreenCapture` 开始和停止屏幕采集。
### 创建 UMG [#创建-umg]
创建两个 **Button** (按钮) 控件,分别命名为 **Btn_StartScreenCapture** 和 **Btn_StopScreenCapture**,用户可以通过这两个按钮开始或停止屏幕共享。如下图所示:

### 加入频道并发布屏幕共享流 [#加入频道并发布屏幕共享流-1]
参考以下步骤加入频道并发布屏幕共享流。
1. 在 **Bind UIEvent** 中,绑定点击开始屏幕共享按钮的 UI 事件。创建 **Bind Event to On Clicked** 节点,分别连接 **Btn_StartScreenShare** 按钮控件和 **OnStartScreenShareClicked** 回调函数。当用户点击开始屏幕共享按钮时,会触发该回调。如下图所示:

2. 创建并实现 **OnStartScreenShareClicked** 回调。当点击按钮触发该回调时,会执行以下流程:
1. 调用 **Stop Screen Capture** 方法停止正在进行的屏幕共享进程。
2. 调用 **Start Screen Capture** 方法开始屏幕采集,并在 **Make ScreenCaptureParameters2** 中勾选 **Capture Audio** 和 **Capture Video** 采集系统音频和屏幕视频,其他参数详见 [`FScreenCaptureParameters2`](/zh-CN/api-reference/rtc/unreal-blueprint/class-screencaptureparameters2)。
3. 调用 **Join Channel** 加入频道,并在 **Make ChannelMediaOptions** 配置以下参数将屏幕采集的视频流发布到频道中:
- 设置 **Publish Camera Track** 为 **Agora False Value**,取消发布摄像头采集的视频流。
- 设置 **Publish Screen Capture Video** 为 **Agora True Value**,发布屏幕采集的视频流。
- 设置 **Publish Screen Capture Audio** 为 **Agora True Value**,发布屏幕采集的音频流。
- 设置 **Auto Subscribe Video** 为 **AGORA TRUE VALUE**,自动订阅所有视频流。
- 设置 **Auto Subscribe Audio** 为 **AGORA TRUE VALUE**,自动订阅所有音频流。
- 勾选 **Client Role Type Set Value** 并设置 **Client Role Type** 为 **CLIENT_ROLE_BROADCASTER** 或 **CLIENT_ROLE_AUDIENCE**,设置用户角色为主播或观众。
- 勾选 **Channel Profile Set Value** 并设置 **Channel Profile** 为 **CHANNEL_PROFILE_LIVE_BROADCASTING**,设置频道场景为直播场景。
如下图所示:

### 停止屏幕共享 [#停止屏幕共享-6]
参考以下步骤停止屏幕采集。
1. 在 **Bind UIEvent** 中,绑定点击停止屏幕共享按钮的 UI 事件。创建 **Bind Event to On Clicked** 节点,分别连接 **Btn_StopScreenShare** 按钮控件和 **OnStopScreenShareClicked** 回调函数。当用户点击停止屏幕共享按钮时,会触发该回调。如下图所示:

2. 创建并实现 **OnStopScreenShareClicked** 回调。当点击按钮触发该回调时,会调用 **Stop Screen Capture** 停止屏幕共享。如下图所示:

本小节介绍如何在桌面端调用 `StartScreenCaptureByDisplayId` 和 `StartScreenCaptureByWindowId` 采集指定屏幕或指定窗口的视频流。
### 创建 UMG [#创建-umg-1]
参考以下步骤创建 UMG。
1. 创建一个 **ComboBoxString** (下拉列表框) 控件,命名为 **CBS_DisplayID**,供用户在下拉列表中选择要共享的屏幕或窗口。
2. 创建两个 **Button** (按钮) 控件,分别命名为 **Btn_StartScreenCapture** 和 **Btn_StopScreenCapture**,用户可以通过这两个按钮开始或停止屏幕共享。如下图所示:

### 添加基础流程 [#添加基础流程]
在 **EventGraph** (事件图表) 中,基于实时音视频互动的基础流程,添加并连接屏幕共享所需的事件节点,增加屏幕共享的逻辑和交互。如下图所示:

其中主要节点如下:
| 节点 | 描述 |
|:-------|:-----------|
| **Get Screen Display Id** | 在初始化 RTC 引擎后,获取当前可共享的屏幕和窗口信息,用于设置下拉列表中的选项和索引。 |
| **Init Default Screen Capture Config** | 准备屏幕共享的参数配置,保存该配置在后续屏幕采集时使用。 |
### 获取可用的屏幕和窗口 [#获取可用的屏幕和窗口]
参考以下步骤获取并添加可用的屏幕和窗口:
1. 在 **Get Screen Display Id** 中,参照以下步骤获取当前可用的屏幕和窗口资源并添加到下拉列表的选项中:
1. 调用 **Get Screen Capture Sources** 方法,返回可共享的屏幕和窗口信息列表,并调用 **Get Count** 获取可共享的屏幕和窗口的个数。如下图所示:

2. 遍历该列表,调用 **Get Source Info** 获取指定的屏幕或窗口的信息,将屏幕或窗口的名称 (**Source Name**) 逐一添加到下拉列表的选项中,供用户在开始共享前指定要共享的屏幕或窗口。获取完成后,调用 **Release** 释放可共享的屏幕和窗口信息列表。如下图所示:

2. 在 **Bind UIEvent** 中,绑定下拉列表选项变更的 UI 事件。创建 **Bind Event to On Selection Changed** 节点,分别连接 **CBS_DisplayID** 下拉列表控件和 **OnCBDisplayIDSelectionChanged** 回调函数。当用户在下拉列表中选择指定的屏幕或窗口时,会触发该回调。如下图所示:

3. 创建并实现 **OnCBDisplayIDSelectionChanged** 回调。当选项变更触发该回调时,会查找该选项的索引并通过索引设置选项。如下图所示:

### 配置屏幕共享参数 [#配置屏幕共享参数]
在 **Init Default Screen Capture Config** 中,配置屏幕共享相关的参数,如 **Dimensions** (分辨率)、**Frame Rate** (帧率)、**Bitrate** (码率) 等,详见 [`FScreenCaptureParameters`](/zh-CN/api-reference/rtc/unreal-blueprint/class-screencaptureparameters)。其中你可以进行如下进阶配置:
- **屏幕描边**:勾选 **Enable Hight Light**,并设置 **High Light Width** 和 **High Light Color** 指定描边的宽度和颜色,SDK 会根据你的设置对共享的屏幕或窗口描边。
- **屏蔽窗口**:将 **Exclude Window List** 设置为你想要屏蔽的窗口列表,后续调用 **Start Screen Capture by Display Id** 时,会通过该参数屏蔽指定的窗口。
保存该配置供后续开始屏幕采集时使用。如下图所示:

### 加入频道并发布屏幕共享流 [#加入频道并发布屏幕共享流-2]
1. 在 **Bind UIEvent** 中,绑定点击开始屏幕共享按钮的 UI 事件。创建 **Bind Event to On Clicked** 节点,分别连接 **Btn_StartScreenShare** 按钮控件和 **OnStartScreenShareClicked** 回调函数。当用户点击开始屏幕共享按钮时,会触发该回调。如下图所示:

2. 创建并实现 **OnStartScreenShareClicked** 回调。当点击按钮触发该回调时,会执行以下流程:
1. 调用 **Stop Screen Capture** 方法停止正在进行的屏幕共享进程。
2. 根据[先前步骤](#获取可用的屏幕和窗口)中保存的可用屏幕及窗口列表,找到选项对应的元素,并通过元素中的 **Type** (共享目标的类型) 来判断选项是 **ScreenCaptureSourceType_Screen** (屏幕) 还是 **ScreenCaptureSourceType_Window** (窗口)。

3. 如果共享目标是一个屏幕,则调用 **Start Screen Capture by Display Id** 传入屏幕 ID 和[先前步骤](#配置屏幕共享参数)中保存的参数配置,开始采集指定屏幕的视频流;如果共享目标是一个窗口,则调用 **Start Screen Capture by Window Id** 传入窗口 ID 和参数配置,开始采集指定窗口的视频流。
如需**共享屏幕或窗口的指定区域**,你可以将 **Region Rect** 参数设置为你想要共享的区域相对于整个屏幕或窗口的位置。
4. 调用 **Join Channel** 加入频道,并在 **Make ChannelMediaOptions** 中配置以下参数发布采集到的屏幕共享流:
- 设置 **Publish Camera Track** 为 **Agora False Value**,取消发布摄像头采集的视频流。
- 设置 **Publish Screen Track** 为 **Agora True Value**,发布屏幕采集的视频流。
- 设置 **Auto Subscribe Video** 为 **AGORA TRUE VALUE**,自动订阅所有视频流。
- 设置 **Auto Subscribe Audio** 为 **AGORA TRUE VALUE**,自动订阅所有音频流。
- 勾选 **Client Role Type Set Value** 并设置 **Client Role Type** 为 **CLIENT_ROLE_BROADCASTER** 或 **CLIENT_ROLE_AUDIENCE**,设置用户角色为主播或观众。
- 勾选 **Channel Profile Set Value** 并设置 **Channel Profile** 为 **CHANNEL_PROFILE_LIVE_BROADCASTING**,设置频道场景为直播场景。

### 停止屏幕共享并离开频道 [#停止屏幕共享并离开频道]
1. 在 **Bind UIEvent** 中,绑定点击停止屏幕共享按钮的 UI 事件。创建 **Bind Event to On Clicked** 节点,分别连接 **Btn_StopScreenShare** 按钮控件和 **OnStopScreenShareClicked** 回调函数。当用户点击停止屏幕共享按钮时,会触发该回调。如下图所示:

2. 创建并实现 **OnStopScreenShareClicked** 回调。当点击按钮触发该回调时,会调用 **Stop Screen Capture** 停止屏幕共享。如下图所示:

## 参考信息 [#参考信息-11]
### 功能介绍 [#功能介绍-10]
声网 SDK 的屏幕共享特性可提供以下功能,适用于各种场景下的屏幕共享。

:::info[信息]
屏幕共享功能在各平台的适用情况如下:
- 桌面端(Windows 和 macOS):支持上述所有屏幕共享功能。
- 移动端(Android 和 iOS):仅支持共享整个屏幕。
:::
#### 共享整个屏幕 [#共享整个屏幕-13]
将你的整个屏幕进行共享,包括屏幕中的所有信息,该功能支持同时采集两块屏幕的信息并共享。
#### 共享 App 窗口 [#共享-app-窗口-13]
如果你不希望将整个屏幕内容分享给其他用户,可以只共享一个 App 窗口中的画面。
#### 共享指定区域 [#共享指定区域-13]
如果你只希望共享屏幕或 App 窗口中的一部分,可以在开启屏幕共享时设置一个共享区域,只有该区域内的画面会被分享。
#### 高级功能 [#高级功能-10]
除上述功能外,你还可以在开启屏幕共享时通过调整参数,实现以下高级共享功能:
- 屏蔽指定 App 窗口:在共享屏幕时,如果你不希望暴露某个 App 窗口,可以选择将该 App 窗口屏蔽,则该窗口将不会出现在共享的屏幕中。
- 描边:如果你需要勾勒出正在共享的范围,可以对指定的 App 窗口或屏幕进行描边,并自定义描边的宽度、颜色和透明度。
- 前置指定 App 窗口:如果你同时共享了多个 App 窗口,可能会出现窗口之间互相遮挡的情况,你可以指定一个 App 窗口并将其前置,即可避免它被其他窗口遮挡。
- 设置共享场景:SDK 会根据你设置的场景自动调节 QOE (Quality of Experience) 策略。
- 在共享文档、幻灯片、表格,或者远程控制时,你可以将共享场景设置为文档场景或远程控制场景,SDK 会优先保障画质,并降低接收端看共享视频的延时。
- 在共享游戏或电影、视频直播时,你可以将共享场景设置为游戏场景或视频场景,SDK 会优先保障流畅性。
### 优势介绍 [#优势介绍-10]
声网提供的屏幕共享特性具备以下优势:
**超高清画质体验**
支持分辨率为 4K、帧率为 60 fps 的超高清视频。
**多 App 支持**
适配 WPS Office、Microsoft PowerPoint、Visual Studio Code、Adobe Photoshop、Windows Media Player 和 Scratch 等多款主流 App,方便用户在屏幕共享时直接共享指定 App,提升功能易用性。
**多设备支持**
支持多设备同时共享,兼容 Windows 8 系统、无独立显卡的设备、双显卡设备、外接屏幕设备等,满足各种场景下的设备使用需求。
**多平台适配**
支持 iOS、Android、macOS、Windows、Web、Unity、Flutter、React Native、Unreal Engine 等平台。
**高安全保障**
支持仅共享 App 和屏幕中的部分区域内容,并支持屏蔽指定 App 窗口,有效保障用户信息安全。
### 示例项目 [#示例项目-11]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
### 注意事项 [#注意事项-11]
- (仅适用于 Android 和 iOS) 在开始屏幕共享前,调用 `SetAudioScenario` 方法,并设置音频场景为 `AUDIO_SCENARIO_GAME_STREAMING` (高音质场景),以提高屏幕共享时采集系统音频的成功率。
- 在开启屏幕共享后,声网以屏幕共享视频流的分辨率作为计费标准。移动端屏幕共享流默认分辨率为 1280 x 720,PC 端屏幕共享流默认分辨率为 1920 x 1080,你也可以根据你的业务需求进行调整。详见[如何确定屏幕共享视频流的分辨率?](/zh-CN/realtime-media/rtc/reference/billing-faq#screencapture)
### API 参考 [#api-参考-12]
- Android, iOS
- [`StartScreenCapture`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_startscreencapture)
- [`StopScreenCapture`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_stopscreencapture)
- [`UpdateScreenCapture`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_updatescreencapture)
- Windows, macOS
- [`GetScreenCaptureSources`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_getscreencapturesources)
- [`StartScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_startscreencapturebydisplayid)
- [`StartScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_startscreencapturebywindowid)
- [`UpdateScreenCaptureParameters`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_updatescreencaptureparameters)
- [`UpdateScreenCaptureRegion`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_updatescreencaptureregion)
- [`SetScreenCaptureContentHint`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_setscreencapturecontenthint)
- [`SetScreenCaptureScenario`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_setscreencapturescenario)
- [`StopScreenCapture`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_stopscreencapture)