# Agora Web SDK API Reference (/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

## Type aliases [#type-aliases]

<a id="audioencoderconfigurationpreset"></a>

### AudioEncoderConfigurationPreset [#audioencoderconfigurationpreset]

<ApiSignature>

AudioEncoderConfigurationPreset: keyof typeof AUDIO_ENCODER_CONFIG_SETTINGS

</ApiSignature>

你可以在以下方法中传入预设值来控制本地音频的编码配置：

- [AgoraRTC.createCustomAudioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createcustomaudiotrack)
- [AgoraRTC.createMicrophoneAudioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createmicrophoneaudiotrack)
- [AgoraRTC.createBufferSourceAudioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createbuffersourceaudiotrack)

下表列出了 SDK 所有内置的音频属性配置，SDK 默认使用 `"music_standard"`。

| 音频属性 | 配置 |
| --- | --- |
| `"speech_low_quality"` | 16 kHz 采样率，单声道，编码码率约 24 Kbps |
| `"speech_standard"` | 32 kHz 采样率，单声道，编码码率约 24 Kbps |
| `"music_standard"` | 48 kHz 采样率，单声道，编码码率约 32 Kbps |
| `"standard_stereo"` | 48 kHz 采样率，双声道，编码码率约 64 Kbps |
| `"high_quality"` | 48 kHz 采样率，单声道， 编码码率约 128 Kbps |
| `"high_quality_stereo"` | 48 kHz 采样率，双声道，编码码率约 192 Kbps |

<a id="audiosourcestate"></a>

### AudioSourceState [#audiosourcestate]

<ApiSignature>

AudioSourceState: "stopped"|"playing"|"paused"

</ApiSignature>

音频源数据处理状态，通过 [BufferSourceAudioTrack.on("source-state-change")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ibuffersourceaudiotrack#event_source_state_change) 获取。

- `"stopped"`: 音频源数据处理停止。可能是因为数据处理完毕，也可能是手动触发了停止。
- `"playing"`: 音频源数据正在处理。
- `"paused"`: 音频源数据暂停处理。

<a id="checkvideovisibleresult"></a>

### CheckVideoVisibleResult [#checkvideovisibleresult]

<ApiSignature>

CheckVideoVisibleResult: CheckVisibleResult

</ApiSignature>

`<video>` 标签的可见状态信息。

可通过以下方法或事件获取：

- [localVideoTrack.on("video-element-visible-status")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocalvideotrack#event_video_element_visible_status)
- [localVideoTrack.getVideoElementVisibleStatus](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocalvideotrack#getvideoelementvisiblestatus)
- [remoteVideoTrack.on("video-element-visible-status")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotevideotrack#event_video_element_visible_status_2)
- [remoteVideoTrack.getVideoElementVisibleStatus](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotevideotrack#getvideoelementvisiblestatus)

包含以下字段：

- `visible`: Boolean 型，`<video>` 标签是否可见。
- `reason`: 仅当 `visible` 为 `false` 时有效，不可见原因：

  - `"SIZE"`: `<video>` 尺寸太小，导致 `<video>` 完全不可见或很难看到。
  - `"STYLE"`: `<video>` 或其祖先元素的 CSS 样式导致 `<video>` 不可见、颜色暗淡或模糊不清。
  - `"POSITION"`: `<video>` 或其祖先元素被定位到视口区域外，导致 `<video>` 只有小面积区域在视口内或全部不在视口内。
  - `"COVERED"`: `<video>` 被其他元素遮挡。

<a id="clientrole"></a>

### ClientRole [#clientrole]

<ApiSignature>

ClientRole: "audience"|"host"

</ApiSignature>

用户角色。

- `"host"`: 直播场景中的主播，可以发布和订阅音视频轨道。
- `"audience"`: 直播场景中的观众，只能订阅，不能发布音视频轨道。

<a id="connectionstate"></a>

### ConnectionState [#connectionstate]

<ApiSignature>

ConnectionState: "DISCONNECTED"|"CONNECTING"|"RECONNECTING"|"CONNECTED"|"DISCONNECTING"

</ApiSignature>

SDK 和声网服务器的连接状态，可以通过 [connectionState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#connectionstate) 获取。

SDK 和服务器有以下 5 种连接状态:

- `"DISCONNECTED"`: 连接断开。该状态表示用户处于以下任一阶段：

  - 尚未通过 [join](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#join) 加入频道。
  - 已经通过 [leave](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#leave) 离开频道。
  - 被踢出频道或者连接失败等异常情况。
- `"CONNECTING"`: 正在连接中。当调用 [join](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#join) 时为此状态。
- `"CONNECTED"`: 已连接。该状态表示用户已经加入频道，可以在频道内发布或订阅媒体流。
- `"RECONNECTING"`: 正在重连中。因网络断开或切换而导致 SDK 与服务器的连接中断，SDK 会自动重连，此时连接状态变为 `"RECONNECTING"`。
- `"DISCONNECTING"`: 正在断开连接。在调用 [leave](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#leave) 的时候为此状态。

<a id="devicestate"></a>

### DeviceState [#devicestate]

<ApiSignature>

DeviceState: "ACTIVE"|"INACTIVE"

</ApiSignature>

采集设备当前的插拔状态。

- `"ACTIVE"`: 该设备已经插入。
- `"INACTIVE"`: 该设备已经被拔出。

<a id="encryptionmode"></a>

### EncryptionMode [#encryptionmode]

<ApiSignature>

EncryptionMode: "aes-128-xts"|"aes-256-xts"|"aes-128-ecb"|"sm4-128-ecb"|"aes-128-gcm"|"aes-256-gcm"|"aes-128-gcm2"|"aes-256-gcm2"|"none"

</ApiSignature>

加密方案，在调用 [setEncryptionConfig](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setencryptionconfig) 时使用。包含以下几种：

- `"aes-128-xts"`: 128 位 AES 加密，XTS 模式。
- `"aes-256-xts"`: 256 位 AES 加密，XTS 模式。
- `"aes-128-gcm"`: 128 位 AES 加密，GCM 模式。
- `"aes-256-gcm"`: 256 位 AES 加密，GCM 模式。
- `"aes-128-gcm2"`: 128 位 AES 加密，GCM 模式，加盐。
- `"aes-256-gcm2"`: 256 位 AES 加密，GCM 模式，加盐。
- `"aes-128-ecb"`: 128 位 AES 加密，ECB 模式。
- `"sm4-128-ecb"`: 128 位 SM4 加密，ECB 模式。
- `"none"`: 不加密。

<a id="localaccesspointconfig"></a>

### LocalAccessPointConfig [#localaccesspointconfig]

<ApiSignature>

LocalAccessPointConfig: object&object

</ApiSignature>

混合云/私有化平台的配置参数。用于 [setLocalAccessPointsV2](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setlocalaccesspointsv2) 方法。

- `accessPoints`：访问节点，包含以下属性：

  - `serverList`：IP 地址列表或 hostname（主机名，用于指定 SDK 访问的 Agora SD-RTN™ 边缘节点）列表。
  - `domain`：域名。如果传入的 `serverList` 为 IP 地址列表，SDK 会拼接传入的 IP 地址和 `domain` 生成 hostname 列表。此时 `domain` 用于指定 SDK 接入 Agora SD-RTN™ 的网关。
  - `port`：（可选）端口号。如果传入，端口号会和 hostname 拼在一起。
- `log`：（可选）日志上传服务。包含可选属性 `hostname` 和 `port`。如果要设置日志上传服务，请确保你已经调用 [enableLogUpload](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#enablelogupload) 开启 SDK 的日志上传功能。
- `report`：（可选）事件上报服务。默认关闭。包含可选属性 `hostname` 和 `port`。
- `cds`：预留参数，暂不支持。

可选属性如果不填，将使用对应的默认值：

| 属性 | 默认值 |
| --- | --- |
| `log.hostname` | `accessPoints` 所包含的 hostname 列表中的第一个 |
| `log.port` | 6444 |
| `report.hostname` | `accessPoints` 所包含的 hostname 列表中的前两个 |
| `report.port` | 6443 |
| `accessPoints.port` | 443 |

```javascript
client.setLocalAccessPointsV2({
  accessPoints: {
    serverList:["192.168.1.1","192.168.2.2"],
    domain: 'test.agora.io'
  },
  // 必须先调用 enableLogUpload，下面的日志服务设置才生效
  log:{
    hostname:["abc.com"],
    port: 3000
  },
  // 开启事件上报服务并配置参数
  report:{
    hostname:["example.com"],
    port: 8080
  }
})
```

<a id="optimizationmode"></a>

### OptimizationMode [#optimizationmode]

<ApiSignature>

OptimizationMode: "motion"|"detail"

</ApiSignature>

<a id="requiredonlyoneof"></a>

### RequiredOnlyOneOf [#requiredonlyoneof]

RequiredOnlyOneOf&lt;T, K&gt;: object[K] extends infer O? object: never

<ParameterList title="Type parameters">
<Parameter name="T" />
<Parameter name="K" type="keyof T" />
</ParameterList>

<a id="sdk_codec"></a>

### SDK_CODEC [#sdk_codec]

<ApiSignature>

SDK_CODEC: keyof typeof VideoCodec

</ApiSignature>

浏览器使用的编码格式，有以下两种选择：

- `"vp8"`: 浏览器使用 VP8 编码。
- `"h264"`: 浏览器使用 H.264 编码。
- `"vp9"`: (Beta) 浏览器使用 VP9 编码。
- `"av1"`: 浏览器使用 AV1 编码。

> Safari 12.1 之前版本不支持 VP8 编码。

<a id="sdk_mode"></a>

### SDK_MODE [#sdk_mode]

<ApiSignature>

SDK_MODE: "live"|"rtc"

</ApiSignature>

频道场景。

Agora Web SDK 需知道 app 的使用场景（例如通信模式或直播模式），从而使用不同的优化手段。

声网频道支持以下场景:

- `"live"`: 直播场景，有主播和观众两种用户角色，可以通过 [setClientRole](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setclientrole) 方法设置主播和观众的角色。主播可以收发音视频流，而观众只能接收音视频流，无法发送。
- `"rtc"`: 通信场景，用于常见的一对一通话或群聊，频道中的任何用户可以自由说话。

<a id="screenencoderconfigurationpreset"></a>

### ScreenEncoderConfigurationPreset [#screenencoderconfigurationpreset]

<ApiSignature>

ScreenEncoderConfigurationPreset: keyof typeof SUPPORT_SCREEN_ENCODER_CONFIG_LIST

</ApiSignature>

SDK 预设的 [VideoEncoderConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/videoencoderconfiguration) 配置。

你可以在 [AgoraRTC.createScreenVideoTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createscreenvideotrack) 方法中传入以下预设值来控制屏幕共享视频编码配置。

下表列出了 SDK 所有预设的屏幕共享视频属性配置。

| 视频属性 | 分辨率（宽×高） | 帧率（fps） |
| --- | --- | --- |
| "480p" | 640 × 480 | 5 |
| "480p_1" | 640 × 480 | 5 |
| "480p_2" | 640 × 480 | 30 |
| "480p_3" | 640 × 480 | 15 |
| "720p" | 1280 × 720 | 5 |
| "720p_1" | 1280 × 720 | 5 |
| "720p_2" | 1280 × 720 | 30 |
| "720p_3" | 1280 × 720 | 15 |
| "720p_auto" ① | 1280 × 720 | 30 |
| "1080p" | 1920 × 1080 | 5 |
| "1080p_1" | 1920 × 1080 | 5 |
| "1080p_2" | 1920 × 1080 | 30 |
| "1080p_3" | 1920 × 1080 | 15 |

> ① `"720p_auto"` 仅推荐在 Safari 上设置，用于确保能够动态调整编码分辨率，详见[发版说明](/zh-CN/realtime-media/rtc/reference/release-notes)。

<a id="screensourcetype"></a>

### ScreenSourceType [#screensourcetype]

<ApiSignature>

ScreenSourceType: "screen"|"window"|"application"

</ApiSignature>

屏幕共享源的类型。

- `"screen"`: 共享屏幕。
- `"application"`: 共享某一个 app 的所有窗口。
- `"window"`: 共享某一个 app 的某一个窗口。

<a id="uid"></a>

### UID [#uid]

<ApiSignature>

UID: number|string

</ApiSignature>

用于标识用户的 ID。同一频道中每个用户都具有唯一的 ID，且数据类型相同。

为保证最佳的用户体验，声网强烈建议你不要使用字符串作为用户 ID。详见 [join](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#join) 方法中的说明。

<a id="videoencoderconfigurationpreset"></a>

### VideoEncoderConfigurationPreset [#videoencoderconfigurationpreset]

<ApiSignature>

VideoEncoderConfigurationPreset: keyof typeof SUPPORT_VIDEO_ENCODER_CONFIG_LIST

</ApiSignature>

SDK 预设的 [VideoEncoderConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/videoencoderconfiguration) 配置。

你可以在 [AgoraRTC.createCameraVideoTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createcameravideotrack) 方法中传入预设的视频编码配置。

下表列出了 SDK 所有内置的视频属性配置，SDK 默认使用 `"480p_1"`。

| 视频属性 | 分辨率（宽×高） | 帧率（fps） | Chrome | Firefox | Safari |
| --- | --- | --- | --- | --- | --- |
| 120p | 160 × 120 | 15 | ✓ |  |  |
| 120p_1 | 160 × 120 | 15 | ✓ |  |  |
| 120p_3 | 120 × 120 | 15 | ✓ |  |  |
| 180p | 320 × 180 | 15 | ✓ |  |  |
| 180p_1 | 320 × 180 | 15 | ✓ |  |  |
| 180p_3 | 180 × 180 | 15 | ✓ |  |  |
| 180p_4 | 240 × 180 | 15 | ✓ |  |  |
| 240p | 320 × 240 | 15 | ✓ |  |  |
| 240p_1 | 320 × 240 | 15 | ✓ |  |  |
| 240p_3 | 240 × 240 | 15 | ✓ |  |  |
| 240p_4 | 424 × 240 | 15 | ✓ |  |  |
| 360p | 640 × 360 | 15 | ✓ |  |  |
| 360p_1 | 640 × 360 | 15 | ✓ |  |  |
| 360p_3 | 360 × 360 | 15 | ✓ |  |  |
| 360p_4 | 640 × 360 | 30 | ✓ |  |  |
| 360p_6 | 360 × 360 | 30 | ✓ |  |  |
| 360p_7 | 480 × 360 | 15 | ✓ |  |  |
| 360p_8 | 480 × 360 | 30 | ✓ |  |  |
| 360p_9 | 640 × 360 | 15 | ✓ |  |  |
| 360p_10 | 640 × 360 | 24 | ✓ |  |  |
| 360p_11 | 640 × 360 | 24 | ✓ |  |  |
| 480p | 640 × 480 | 15 | ✓ | ✓ | ✓ |
| 480p_1 | 640 × 480 | 15 | ✓ | ✓ | ✓ |
| 480p_2 | 640 × 480 | 30 | ✓ | ✓ | ✓ |
| 480p_3 | 480 × 480 | 15 | ✓ | ✓ | ✓ |
| 480p_4 | 640 × 480 | 30 | ✓ | ✓ | ✓ |
| 480p_6 | 480 × 480 | 30 | ✓ | ✓ | ✓ |
| 480p_8 | 848 × 480 | 15 | ✓ | ✓ | ✓ |
| 480p_9 | 848 × 480 | 30 | ✓ | ✓ | ✓ |
| 480p_10 | 640 × 480 | 10 | ✓ | ✓ | ✓ |
| 720p | 1280 × 720 | 15 | ✓ | ✓ | ✓ |
| 720p_1 | 1280 × 720 | 15 | ✓ | ✓ | ✓ |
| 720p_2 | 1280 × 720 | 30 | ✓ | ✓ | ✓ |
| 720p_3 | 1280 × 720 | 30 | ✓ | ✓ | ✓ |
| 720p_auto ① | 1280 × 720 | 30 | ✓ | ✓ | ✓ |
| 720p_5 | 960 × 720 | 15 | ✓ | ✓ | ✓ |
| 720p_6 | 960 × 720 | 30 | ✓ | ✓ | ✓ |
| 1080p | 1920 × 1080 | 15 | ✓ |  | ✓ |
| 1080p_1 | 1920 × 1080 | 15 | ✓ |  | ✓ |
| 1080p_2 | 1920 × 1080 | 30 | ✓ |  | ✓ |
| 1080p_3 | 1920 × 1080 | 30 | ✓ |  | ✓ |
| 1080p_5 | 1920 × 1080 | 60 | ✓ |  | ✓ |

> ① `"720p_auto"` 仅推荐在 Safari 上设置，用于确保能够动态调整编码分辨率，详见[发版说明](/zh-CN/realtime-media/rtc/reference/release-notes)。

## Events [#events]

<a id="event_track_updated"></a>

### track-updated [#track-updated]

<ApiSignature>

track-updated(track: MediaStreamTrack): void

</ApiSignature>

媒体轨道有更新时触发。

<ParameterList title="Parameters">
<Parameter name="track" type="MediaStreamTrack" required>

媒体轨道。详见 [MediaStreamTrack](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

## Variables [#variables]

<a id="audio_encoder_config_settings"></a>

### Const AUDIO_ENCODER_CONFIG_SETTINGS [#const-audio_encoder_config_settings]

AUDIO_ENCODER_CONFIG_SETTINGS: object

#### Type declaration [#type-declaration]

<ParameterList title="Type declaration">
<Parameter name="high_quality" required>

<ParameterType>

[AudioEncoderConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/audioencoderconfiguration)

</ParameterType>

</Parameter>
<Parameter name="high_quality_stereo" required>

<ParameterType>

[AudioEncoderConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/audioencoderconfiguration)

</ParameterType>

</Parameter>
<Parameter name="music_standard" required>

<ParameterType>

[AudioEncoderConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/audioencoderconfiguration)

</ParameterType>

</Parameter>
<Parameter name="speech_low_quality" required>

<ParameterType>

[AudioEncoderConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/audioencoderconfiguration)

</ParameterType>

</Parameter>
<Parameter name="speech_standard" required>

<ParameterType>

[AudioEncoderConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/audioencoderconfiguration)

</ParameterType>

</Parameter>
<Parameter name="standard_stereo" required>

<ParameterType>

[AudioEncoderConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/audioencoderconfiguration)

</ParameterType>

</Parameter>
</ParameterList>

<a id="agorartc"></a>

### Const AgoraRTC [#const-agorartc]

AgoraRTC: [IAgoraRTC](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc)

<a id="support_screen_encoder_config_list"></a>

### Const SUPPORT_SCREEN_ENCODER_CONFIG_LIST [#const-support_screen_encoder_config_list]

SUPPORT_SCREEN_ENCODER_CONFIG_LIST: Record&lt;string,[VideoEncoderConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/videoencoderconfiguration)&gt;

<a id="support_svc_config_list"></a>

### Const SUPPORT_SVC_CONFIG_LIST [#const-support_svc_config_list]

SUPPORT_SVC_CONFIG_LIST: Record&lt;string,SVCConfiguration&gt;

<a id="support_video_encoder_config_list"></a>

### Const SUPPORT_VIDEO_ENCODER_CONFIG_LIST [#const-support_video_encoder_config_list]

SUPPORT_VIDEO_ENCODER_CONFIG_LIST: Record&lt;string,[VideoEncoderConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/videoencoderconfiguration)&gt;