# 屏幕共享 (/zh-CN/realtime-media/rtc/build/video/screen-share/harmonyos)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
在互动直播或视频通话中,主播或视频通话用户可以通过声网 SDK 中的屏幕共享特性,将自己的屏幕内容以视频的方式分享给其他用户或观众观看。
屏幕共享可以应用在以下场景中:
| 场景 | 描述 |
| :------- | :----------------------------------------------------------- |
| 在线教育 | 老师将自己的屏幕、教学课件、绘图软件或编程软件共享给学生,用于课堂示范 |
| 游戏直播 | 主播共享自己的游戏画面给观众 |
| 互动直播 | 主播共享自己的屏幕和观众互动 |
| 视频会议 | 会议成员共享屏幕观看 PPT 或者文档 |
| 远程控制 | 被控端向主控端展示自己的桌面 |
## 技术原理 [#技术原理-2]
根据实际业务场景的不同,你可以选择以下任一方式调用 API 实现屏幕共享:
- 在加入频道前调用 `startScreenCapture`,然后调用 `joinChannel`[2/2] 加入频道并设置 `publishScreenCaptureVideo` 为 `true`,即可开始屏幕共享。
- 在加入频道后调用 `startScreenCapture`,然后调用 `updateChannelMediaOptions` 更新频道媒体选项并设置 `publishScreenCaptureVideo` 为 `true`,即可开始屏幕共享。
## 注意事项 [#注意事项-4]
在开启屏幕共享后,声网以屏幕共享视频流的分辨率作为计费标准。默认分辨率为 1280 × 720,你也可以根据你的业务需求进行调整。详见[如何确定屏幕共享视频流的分辨率?](/zh-CN/realtime-media/rtc/reference/billing-faq#screencapture)
## 前提条件 [#前提条件-4]
在实现屏幕共享前,请确保已在你的项目中实现基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现屏幕共享 [#实现屏幕共享-4]
本节介绍如何使用 HarmonyOS SDK 实现屏幕共享,API 调用时序如下图所示。
开启屏幕共享有如下两种方案,你可以根据实际场景进行选择:
- 在加入频道前调用 `startScreenCapture`,然后调用 `joinChannelWithOptions`,并设置 `publishScreenCaptureVideo` 为 `true`,即可开始屏幕共享。
- 在加入频道后调用 `startScreenCapture`,然后调用 `updateChannelMediaOptions`,设置 `publishScreenCaptureVideo` 为 `true`,即可开始屏幕共享。
本文中的流程图和步骤均以第一种方案为例。
### 开启屏幕采集 [#开启屏幕采集-2]
调用 `startScreenCapture` 开启屏幕采集,并根据你的应用场景进行参数设置:
- `captureVideo`:是否在屏幕共享时采集系统视频。
- `captureAudio`:是否在屏幕共享时采集系统音频。
- `captureSignalVolume`:采集的系统音量。
- `width`:视频编码分辨率中的宽 (px)。
- `height`:视频编码分辨率中的高 (px)。
- `frameRate`:视频编码帧率 (fps)。
- `bitrate`:视频编码码率 (Kbps)。
- `contentHint`:屏幕共享视频的内容类型。
```arkts
// 设置屏幕采集的参数
let captureConfig: ScreenCaptureParameters = new ScreenCaptureParameters();
captureConfig.captureVideo = true;
captureConfig.videoParams.dimensions.width = 720;
captureConfig.videoParams.dimensions.height = (720 * metrics.heightPixels) / metrics.widthPixels;
captureConfig.videoParams.frameRate = DEFAULT_SHARE_FRAME_RATE;
captureConfig.captureAudio = screenAudio.isChecked();
captureConfig.audioParams.captureSignalVolume = screenAudioVolume.getProgress();
this.rtcEngine?.startScreenCapture(captureConfig);
```
### 加入频道并发布屏幕共享视频流 [#加入频道并发布屏幕共享视频流-3]
调用 `joinChannelWithOptions` 方法加入频道,通过设置 `options` 参数,将屏幕采集到的视频流发布到频道中。
```arkts
let mediaOption: ChannelMediaOptions = new ChannelMediaOptions();
mediaOption.clientRoleType = Constants.ClientRole.BROADCASTER;
mediaOption.autoSubscribeVideo = true;
mediaOption.autoSubscribeAudio = true;
mediaOption.publishCameraTrack = false;
mediaOption.publishMicrophoneTrack = false;
mediaOption.publishScreenCaptureVideo = true;
mediaOption.publishScreenCaptureAudio = true;
let res = this.rtcEngine?.joinChannelWithOptions(accessToken, channelId, 0, mediaOption);
```
### (可选)更新屏幕共享 [#可选更新屏幕共享-2]
如果你要更新屏幕共享的参数,调用 `updateScreenCaptureParameters`,修改屏幕共享的参数。例如:视频编码分辨率、帧率、码率。
```arkts
this.rtcEngine?.updateScreenCaptureParameters(captureConfig);
```
### 停止屏幕共享 [#停止屏幕共享-4]
调用 `stopScreenCapture`,在频道内停止屏幕共享。示例代码如下:
```arkts
this.rtcEngine?.stopScreenCapture();
```
## 参考信息 [#参考信息-5]
介绍更多相关信息和参考页面的链接。
### 功能介绍 [#功能介绍-4]
声网 SDK 的屏幕共享特性可提供以下功能,适用于各种场景下的屏幕共享。

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