阿里云 ARTC Web SDK

Appearance

屏幕共享 ​

屏幕共享相关的 API。

startScreenShare ​

开始屏幕共享。

方法签名 ​

typescript
startScreenShare(config?: AliRtcScreenShareStartConfig): Promise<void>

参数说明 ​

参数类型描述
configAliRtcScreenShareStartConfig(可选) 屏幕共享配置

配置对象说明 ​

typescript
interface AliRtcScreenShareStartConfig {
  // 是否包含音频
  audio?: boolean;
  // 视频轨道
  videoTrack?: MediaStreamTrack;
  // 音频轨道
  audioTrack?: MediaStreamTrack;
}

说明 ​

  • 开始捕获屏幕内容并推送给远端用户
  • 需要用户授权屏幕共享权限
  • 支持共享整个屏幕或特定应用窗口
  • 可以选择是否包含系统音频

使用示例 ​

javascript
// 开始屏幕共享（基本用法）
await engine.startScreenShare();

// 开始屏幕共享并包含音频
await engine.startScreenShare({
  audio: true,
});

// 使用自定义媒体轨道
await engine.startScreenShare({
  videoTrack: customVideoTrack,
  audioTrack: customAudioTrack,
});

stopScreenShare ​

停止屏幕共享。

方法签名 ​

typescript
stopScreenShare(): Promise<void>

使用示例 ​

javascript
// 停止屏幕共享
await engine.stopScreenShare();

setScreenShareConfiguration ​

设置屏幕共享编码配置。

方法签名 ​

typescript
setScreenShareConfiguration(config: AliRtcScreenShareConfiguration): Promise<void>

参数说明 ​

参数类型描述
configAliRtcScreenShareConfiguration屏幕共享配置

配置对象说明 ​

typescript
interface AliRtcScreenShareConfiguration {
  // 视频编码帧率
  frameRate?: number;
  // 视频编码码率（kbps）
  bitrate?: number;
  // 视频分辨率宽度
  width?: number;
  // 视频分辨率高度
  height?: number;
}

说明 ​

  • 用于设置屏幕共享的视频编码属性
  • 所有参数都有相应的范围限制，SDK会自动调节超出范围的参数
  • width * height 必须小于 9437184

使用示例 ​

javascript
// 设置屏幕共享编码配置
await engine.setScreenShareConfiguration({
  frameRate: 15,
  bitrate: 1500,
  width: 1920,
  height: 1080,
});

setScreenShareContentHint ​

设置屏幕共享内容提示。

方法签名 ​

typescript
setScreenShareContentHint(contentHint: string): Promise<void>

参数说明 ​

参数类型描述
contentHintstring内容提示

说明 ​

  • 用于优化屏幕共享的编码策略
  • 根据共享内容类型选择合适的编码参数

使用示例 ​

javascript
// 设置内容提示为文本
await engine.setScreenShareContentHint('text');

// 设置内容提示为视频
await engine.setScreenShareContentHint('motion');

publishLocalScreenShareStream ​

控制屏幕共享流的发布状态。

方法签名 ​

typescript
publishLocalScreenShareStream(enabled: boolean, config?: AliRtcScreenShareStartConfig): Promise<void>

参数说明 ​

参数类型描述
enabledboolean是否发布屏幕共享流
configAliRtcScreenShareStartConfig(可选) 屏幕共享配置

说明 ​

  • 控制是否向远端推送屏幕共享流
  • 与 startScreenShare 不同，此方法主要控制发布状态
  • 可以在不停止屏幕捕获的情况下暂停推送

使用示例 ​

javascript
// 开始发布屏幕共享流
await engine.publishLocalScreenShareStream(true);

// 停止发布屏幕共享流（但不停止捕获）
await engine.publishLocalScreenShareStream(false);

// 开始发布并配置参数
await engine.publishLocalScreenShareStream(true, {
  audio: true,
});

isScreenSharePublished ​

查询是否正在发布屏幕共享。

方法签名 ​

typescript
isScreenSharePublished(): boolean

返回值 ​

  • true: 正在发布屏幕共享
  • false: 未发布屏幕共享

说明 ​

  • 查询当前是否设置了推送屏幕共享
  • SDK默认不推送屏幕共享
  • 可以通过 startScreenShare 或 publishLocalScreenShareStream 开启

使用示例 ​

javascript
const isPublished = engine.isScreenSharePublished();
console.log('是否正在发布屏幕共享:', isPublished);

if (isPublished) {
  await engine.stopScreenShare();
}

屏幕共享预览 ​

startPreviewScreen ​

开始屏幕共享预览。

方法签名 ​

typescript
startPreviewScreen(config?: AliRtcScreenShareStartConfig): Promise<void>

参数说明 ​

参数类型描述
configAliRtcScreenShareStartConfig(可选) 屏幕共享配置

说明 ​

  • 在纯音频模式下无法开始屏幕共享预览
  • 需要先有屏幕共享流才能预览

使用示例 ​

javascript
// 开始屏幕共享预览
await engine.startPreviewScreen();

// 带配置的屏幕共享预览
await engine.startPreviewScreen({
  audio: true,
});

stopPreviewScreen ​

停止屏幕共享预览。

方法签名 ​

typescript
stopPreviewScreen(): Promise<void>

使用示例 ​

javascript
await engine.stopPreviewScreen();

isScreenSharePublished(): boolean


### 返回值

- true: 正在发布屏幕共享
- false: 未发布屏幕共享

### 说明

- 查询当前是否设置了推送屏幕共享
- SDK默认不推送屏幕共享
- 可以通过 startScreenShare 或 publishLocalScreenShareStream 开启

### 使用示例

```javascript
const isPublished = engine.isScreenSharePublished();
console.log('是否正在发布屏幕共享:', isPublished);

if (isPublished) {
  await engine.stopScreenShare();
}

setAudioShareVolume ​

设置共享音频的音量大小。

方法签名 ​

typescript
setAudioShareVolume(volume: number): void

参数说明 ​

参数类型描述
volumenumber共享音频音量大小，范围[0, 100]

说明 ​

  • 参数必须是数字类型，否则会抛出错误

使用示例 ​

javascript
// 设置共享音频音量为50
engine.setAudioShareVolume(50);

Copyright © 2025 阿里云