# 屏幕共享 (/zh-CN/realtime-media/rtc/build/video/screen-share/windows)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在互动直播或视频通话中,主播或视频通话用户可以通过声网 SDK 中的屏幕共享特性,将自己的屏幕内容以视频的方式分享给其他用户或观众观看。
屏幕共享可以应用在以下场景中:
| 场景 | 描述 |
| :------- | :----------------------------------------------------------- |
| 在线教育 | 老师将自己的屏幕、教学课件、绘图软件或编程软件共享给学生,用于课堂示范 |
| 游戏直播 | 主播共享自己的游戏画面给观众 |
| 互动直播 | 主播共享自己的屏幕和观众互动 |
| 视频会议 | 会议成员共享屏幕观看 PPT 或者文档 |
| 远程控制 | 被控端向主控端展示自己的桌面 |
## 注意事项 [#注意事项-3]
- 在开启屏幕共享后,声网以屏幕共享视频流的分辨率作为计费标准。默认分辨率为 1920 × 1080,你也可以根据你的业务需求进行调整。详见[如何确定屏幕共享视频流的分辨率?](/zh-CN/realtime-media/rtc/reference/billing-faq#screencapture)
- 如果要在屏幕共享时共享 4K 分辨率的超高清视频,你的设备需要满足一定要求,声网推荐的最低设备规格为:Intel(R) Core(TM) i7-9750H CPU @ 2.60 GHz。
## 前提条件 [#前提条件-3]
- 在实现屏幕共享前,请确保已在你的项目中实现基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)或开始互动直播。
- 要实现屏幕共享,请确保在集成 SDK 时不要手动删除屏幕共享动态库(`libagora_screen_capture_extension.dll`),否则会导致该功能无法正常使用。
## 实现屏幕共享 [#实现屏幕共享-3]
本节介绍如何在你的项目中实现屏幕共享,API 调用时序如下图所示。
开启屏幕共享有如下两种方案,你可以根据实际场景进行选择:
- 在加入频道前调用 `startScreenCaptureByDisplayId` 或 `startScreenCaptureByWindowId`,然后调用 `joinChannel`[2/2] 加入频道并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `true`,即可开始屏幕共享。
- 在加入频道后调用 `startScreenCaptureByDisplayId` 或 `startScreenCaptureByWindowId`,然后调用 `updateChannelMediaOptions` 设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `true`,即可开始屏幕共享。
本文中的流程图和步骤均以第一种方案为例。
参考如下具体步骤,实现屏幕共享。
### 获取资源列表 [#获取资源列表-1]
调用 `getScreenCaptureSources`,获取可共享的屏幕和窗口对象列表。列表中包含窗口 ID、屏幕 ID 等重要信息,你可以通过列表中的缩略图选择要共享的显示器或窗口。示例代码如下:
```cpp
{
// 获取指定的可共享窗口或屏幕的信息
agora::rtc::IScreenCaptureSourceList* listCapture = m_rtcEngine->getScreenCaptureSources(sz, sz, true);
for (int i = 0; i < listCapture->getCount(); i++)
{
// 返回可共享窗口或屏幕的信息
agora::rtc::ScreenCaptureSourceInfo info = listCapture->getSourceInfo(i);
}
// 获取可共享的窗口和屏幕的个数
return static_cast(m_listWnd.GetCount());
}
```
### 开启屏幕共享 [#开启屏幕共享-1]
根据实际应用场景,在以下 3 种屏幕共享方式中任选一种。
#### 共享整个屏幕 [#共享整个屏幕-4]
调用 `startScreenCaptureByDisplayId` 开始共享整个屏幕,参数设置如下:
- 将 `displayId` 设置为上一步获取到的 `sourceId`(屏幕 ID)。
- 在 `captureParams` 中设置你预期的视频编码属性。
- 在文档场景或远程控制场景下,推荐将 `dimensions` 设置为 1920 × 1080;`frameRate` 设置为 10 fps。
- 在游戏场景或视频场景下,推荐将 `dimensions` 设置为 960 × 720;`frameRate` 设置为 15 fps。
```cpp
// 开始共享指定的屏幕
m_rtcEngine->startScreenCaptureByDisplayId(id, regionRect, capParam);
```
#### 共享 App 窗口 [#共享-app-窗口-4]
调用 `startScreenCaptureByWindowId` 开始共享整个 App 窗口,参数设置如下:
- 将 `windowId` 设置为上一步获取到的 `sourceId`(窗口 ID)。
- 在 `captureParams` 中设置你预期的视频编码属性。
- 在文档场景或远程控制场景下,推荐将 `dimensions` 设置为 1920 × 1080;`frameRate` 设置为 10 fps。
- 在游戏场景或视频场景下,推荐将 `dimensions` 设置为 960 × 720;`frameRate` 设置为 15 fps。
```cpp
// 开始共享指定的 App 窗口
ret = m_rtcEngine->startScreenCaptureByWindowId(hWnd, rcCapWnd, capParam);
```
#### 共享指定区域 [#共享指定区域-4]
调用 `startScreenCaptureByDisplayId` 或 `startScreenCaptureByWindowId` 方法开始共享,并将 `regionRect` 设置为你想要共享的区域相对于整个屏幕或窗口的位置。示例代码如下:
```cpp
// 设置你想要共享的区域参数
// 如果设置的共享区域超出了屏幕的边界,则只共享屏幕内的内容;如果宽或高设为 0,则共享整个屏幕
m_screenRegion = { 0,0,heightX,heightY };
agora::rtc::Rectangle rcCapWnd = { m_screenRegion.x, m_screenRegion.y, (int)(m_screenRegion.width * scale), (int)(m_screenRegion.height * scale) };
...
m_rtcEngine->startScreenCaptureByDisplayId(id, rcCapWnd, m_screenParam);
```
### (可选)设置屏幕共享场景 [#可选设置屏幕共享场景-3]
调用 `setScreenCaptureScenario` 方法设置屏幕共享场景,按照实际使用场景,将 `screenScenario` 设置为以下任意一种:
- `SCREEN_SCENARIO_DOCUMENT`(1):文档场景
- `SCREEN_SCENARIO_GAMING`(2):游戏场景
- `SCREEN_SCENARIO_VIDEO`(3):视频场景
- `SCREEN_SCENARIO_RDC`(4):远程控制场景
示例代码如下:
```cpp
m_rtcEngine->setScreenCaptureScenario(type);
```
### (可选)采集系统音频 [#可选采集系统音频-1]
如果你想要同时采集并发布共享屏幕或窗口中播放的音频,可以调用 `enableLoopbackRecording` 方法开启声卡采集,系统播放的音频会被合入到本地音频流中。
:::warning[注意]
调用该方法后,系统其他进程播放的音频也会被发布到远端,如果这并非你的预期,请再次调用该方法,关闭声卡采集。
:::
### 加入频道并发布屏幕共享视频流 [#加入频道并发布屏幕共享视频流-2]
调用 `joinChannel`[2/2] 加入频道并设置频道媒体选项。示例代码如下:
```cpp
// 设置频道媒体选项
ChannelMediaOptions option;
option.channelProfile = CHANNEL_PROFILE_LIVE_BROADCASTING;
option.clientRoleType = CLIENT_ROLE_BROADCASTER;
option.publishMicrophoneTrack = true;
// 在频道中发布屏幕采集的视频
// 如果要在频道中发布第二个屏幕采集的视频,则将下一行代码替换为 option.publishSecondaryScreenTrack = true;
option.publishScreenTrack = true;
// 加入频道
m_rtcEngine->joinChannel("Your Token", "Your ChannelId", 0, option)
```
:::warning[注意]
本文以直接在频道中发布屏幕共享流、不发布摄像头采集的流为例,实际应用场景中的发流方式可能跟本文的描述不同,请结合实际应用场景调整你的代码逻辑。如果你需要同时发布摄像头采集的流和屏幕共享流,可参考以下步骤:
1. 调用 `joinChannel`[2/2] 加入第一个频道,在该频道中发布摄像头采集的视频流。
1. 调用 `joinChannelEx` 加入第二个频道,在该频道中发布屏幕共享流。
:::
### (可选)更新屏幕共享区域或参数 [#可选更新屏幕共享区域或参数-1]
在频道中,你可以调用如下方法动态更新屏幕共享区域或参数:
- 如果你要更新屏幕共享的区域,调用 `updateScreenCaptureRegion` 方法,重新设置 `regionRect` 参数、划定新的共享区域。
- 如果你要更新屏幕共享的参数(例如:视频编码分辨率、帧率、码率;对屏幕或 App 窗口描边;是否屏蔽指定窗口等),调用 `updateScreenCaptureParameters` 方法,更新 `captureParams` 参数的配置。
示例代码如下:
```cpp
// 更新屏幕共享区域
agora::rtc::Rectangle rect;
rect.width = m_screenRegion.width * scale;
rect.height = m_screenRegion.height * scale;
int ret = m_rtcEngine->updateScreenCaptureRegion(rect);
// 更新屏幕共享帧率
m_screenParam.frameRate = fps;
int ret = m_rtcEngine->updateScreenCaptureParameters(m_screenParam);
```
### (可选)对屏幕描边 [#可选对屏幕描边-1]
根据实际使用场景,你可以通过以下两种方式对屏幕或窗口进行描边。
- 在开启屏幕共享时描边:调用 `startScreenCaptureByDisplayId`、`startScreenCaptureByWindowId`,将 `captureParams` 中的 `enableHighLight` 设置为 `true`,并同时设置 `highLightColor` 和 `highLightWidth` 来指定描边的颜色和宽度。
- 在开启屏幕共享后描边:调用 `updateScreenCaptureParameters`,将 `captureParams` 中的 `enableHighLight` 设置为 `true`,并同时设置 `highLightColor` 和 `highLightWidth` 来指定描边的颜色和宽度。
```cpp
bool highLigne = m_chkHighLight.GetCheck();
m_screenParam.enableHighLight = highLigne;
// 设置屏幕的描边颜色
m_screenParam.highLightColor = 0xFFFF0000;
// 设置屏幕的描边宽度
m_screenParam.highLightWidth = 5;
// 开启屏幕描边
int ret = m_rtcEngine->updateScreenCaptureParameters(m_screenParam);
```
### (可选)屏蔽窗口 [#可选屏蔽窗口-1]
根据实际使用场景,你可以通过以下两种方式屏蔽指定的窗口。
- 在开启屏幕共享时屏蔽窗口:调用 `startScreenCaptureByDisplayId`,将 `captureParams` 中的 `excludeWindowList` 设置为你想要屏蔽的窗口列表。
- 在开启屏幕共享后屏蔽窗口:调用 `updateScreenCaptureParameters`,将 `captureParams` 中的 `excludeWindowList` 设置为你想要屏蔽的窗口列表。
```cpp
m_screenParam.excludeWindowList = excludeViews;
m_screenParam.excludeWindowCount = count;
int ret = m_rtcEngine->updateScreenCaptureParameters(m_screenParam);
```
:::info[信息]
在 Windows 平台上,你最多可以屏蔽 24 个窗口。
:::
### 停止屏幕共享 [#停止屏幕共享-3]
调用 `stopScreenCapture`,在频道内停止屏幕共享。示例代码如下:
```cpp
// 停止屏幕共享
ret = m_rtcEngine->stopScreenCapture();
```
## 参考信息 [#参考信息-4]
### 功能介绍 [#功能介绍-3]
声网 SDK 的屏幕共享特性可提供以下功能,适用于各种场景下的屏幕共享。

:::info[信息]
屏幕共享功能在各平台的适用情况如下:
- 桌面端(Windows 和 macOS):支持上述所有屏幕共享功能。
- 移动端(Android 和 iOS):仅支持共享整个屏幕。
:::
#### 共享整个屏幕 [#共享整个屏幕-5]
将你的整个屏幕进行共享,包括屏幕中的所有信息,该功能支持同时采集两块屏幕的信息并共享。
#### 共享 App 窗口 [#共享-app-窗口-5]
如果你不希望将整个屏幕内容分享给其他用户,可以只共享一个 App 窗口中的画面。
#### 共享指定区域 [#共享指定区域-5]
如果你只希望共享屏幕或 App 窗口中的一部分,可以在开启屏幕共享时设置一个共享区域,只有该区域内的画面会被分享。
#### 高级功能 [#高级功能-3]
除上述功能外,你还可以在开启屏幕共享时通过调整参数,实现以下高级共享功能:
- 屏蔽指定 App 窗口:在共享屏幕时,如果你不希望暴露某个 App 窗口,可以选择将该 App 窗口屏蔽,则该窗口将不会出现在共享的屏幕中。
- 描边:如果你需要勾勒出正在共享的范围,可以对指定的 App 窗口或屏幕进行描边,并自定义描边的宽度、颜色和透明度。
- 前置指定 App 窗口:如果你同时共享了多个 App 窗口,可能会出现窗口之间互相遮挡的情况,你可以指定一个 App 窗口并将其前置,即可避免它被其他窗口遮挡。
- 设置共享场景:SDK 会根据你设置的场景自动调节 QOE (Quality of Experience) 策略。
- 在共享文档、幻灯片、表格,或者远程控制时,你可以将共享场景设置为文档场景或远程控制场景,SDK 会优先保障画质,并降低接收端看共享视频的延时。
- 在共享游戏或电影、视频直播时,你可以将共享场景设置为游戏场景或视频场景,SDK 会优先保障流畅性。
### 优势介绍 [#优势介绍-3]
声网提供的屏幕共享特性具备以下优势:
**超高清画质体验**
支持分辨率为 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 窗口,有效保障用户信息安全。
### 示例项目 [#示例项目-4]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
AgoraScreenCapture} href="https://gitee.com/agoraio-community/API-Examples/blob/main/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.cpp" />
AgoraScreenCapture} href="https://github.com/Shengwang-Community/API-Examples/blob/main/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.cpp" />
### API 参考 [#api-参考-3]
- [`getScreenCaptureSourcesWithThumbSize`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_getscreencapturesources)
- [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#startscreencapturebydisplayid)
- [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#startscreencapturebywindowid)
- [`setScreenCaptureScenario`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#setscreencapturescenario)
- [`updateScreenCaptureParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#updatescreencaptureparameters)
- [`updateScreenCaptureRegion`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#updatescreencaptureregion)
- [`stopScreenCapture`[1/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#stopscreencapture-12)