# Interface IAgoraRTCClient (/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient)

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

你可以通过 [createClient](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createclient) 创建一个 `AgoraRTCClient` 对象。一个 `AgoraRTCClient` 对象代表一个本地客户端。

## Events [#events]

<a id="event_channel_media_relay_event"></a>

### channel-media-relay-event [#channel-media-relay-event]

<ApiSignature>

channel-media-relay-event(event: [ChannelMediaRelayEvent](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/channelmediarelayevent)): void

</ApiSignature>

跨频道媒体流转发事件回调。

<ParameterList title="Parameters">
<Parameter name="event" required>

<ParameterType>

[ChannelMediaRelayEvent](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/channelmediarelayevent)

</ParameterType>

事件码，详见 [ChannelMediaRelayEvent](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/channelmediarelayevent)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_channel_media_relay_state"></a>

### channel-media-relay-state [#channel-media-relay-state]

<ApiSignature>

channel-media-relay-state(state: [ChannelMediaRelayState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/channelmediarelaystate), code: [ChannelMediaRelayError](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/channelmediarelayerror)): void

</ApiSignature>

跨频道媒体流转发状态回调。

当跨频道媒体流转发状态发生改变时，SDK 会触发该回调，并报告当前的转发状态以及相关的错误信息。

回调会携带当前跨频道媒体流转发服务的状态 [ChannelMediaRelayState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/channelmediarelaystate)，如果状态异常，相应的错误码可以通过 [ChannelMediaRelayError](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/channelmediarelayerror) 获取（比如 token 过期，重连失败等）。

<ParameterList title="Parameters">
<Parameter name="state" required>

<ParameterType>

[ChannelMediaRelayState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/channelmediarelaystate)

</ParameterType>

跨频道媒体流转发服务的状态。

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

<ParameterType>

[ChannelMediaRelayError](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/channelmediarelayerror)

</ParameterType>

跨频道媒体流转发错误码。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_connection_state_change"></a>

### connection-state-change [#connection-state-change]

<ApiSignature>

connection-state-change(curState: [ConnectionState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#connectionstate), revState: [ConnectionState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#connectionstate), reason?: [ConnectionDisconnectedReason](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/connectiondisconnectedreason)): void

</ApiSignature>

SDK 与服务器的连接状态发生改变回调。

<ParameterList title="Parameters">
<Parameter name="curState" required>

<ParameterType>

[ConnectionState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#connectionstate)

</ParameterType>

当前的连接状态。

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

<ParameterType>

[ConnectionState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#connectionstate)

</ParameterType>

之前的连接状态。

</Parameter>
<Parameter name="reason" optional>

<ParameterType>

[ConnectionDisconnectedReason](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/connectiondisconnectedreason)

</ParameterType>

如果 `curState` 为 `"DISCONNECTED"`，这里表示断开连接的原因。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_content_inspect_connection_state_change"></a>

### content-inspect-connection-state-change [#content-inspect-connection-state-change]

<ApiSignature>

content-inspect-connection-state-change(preState: [InspectState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/inspectstate), newState: [InspectState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/inspectstate)): void

</ApiSignature>

视频截图上传服务的连接状态发生改变回调。

```javascript
client.on("content-inspect-connection-state-change", (preState, state) => {
  console.error(`Content Inspect Connection State Change: ${preState} -> ${state}` )
})
```

<ParameterList title="Parameters">
<Parameter name="preState" required>

<ParameterType>

[InspectState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/inspectstate)

</ParameterType>

之前的连接状态。

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

<ParameterType>

[InspectState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/inspectstate)

</ParameterType>

新的连接状态。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_content_inspect_error"></a>

### content-inspect-error [#content-inspect-error]

<ApiSignature>

content-inspect-error(error?: AgoraRTCError): void

</ApiSignature>

开启视频截图上传服务出错回调。

```javascript
client.on("content-inspect-error", error => {
   console.error("Content Inspect Error:", error)
   error.code === "OPERATION_ABORTED" && client.disableContentInspect()
})
```

<ParameterList title="Parameters">
<Parameter name="error" type="AgoraRTCError" optional>

抛出的错误对象 `AgoraRTCError`，该对象包含以下属性：

- code: 错误码。
- message: 错误消息。
- data:（可选）与错误相关的其它信息。

当前可能返回的错误码如下：

| 错误码 | 错误消息 | 原因 |
| --- | --- | --- |
| OPERATION_ABORTED | Content inspect was cancelled because it left the channel | 本地用户已经离开频道 |

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_crypt_error"></a>

### crypt-error [#crypt-error]

<ApiSignature>

crypt-error(): void

</ApiSignature>

解密失败回调。

该回调表示用户在订阅过程中出现了解密失败，通常是由于和发布端设置的加密参数不一致导致的。详见 [setEncryptionConfig](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setencryptionconfig)。

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_exception"></a>

### exception [#exception]

<ApiSignature>

exception(event: object): void

</ApiSignature>

SDK 监测到异常事件回调。

该回调报告频道内 SDK 监测出的异常事件。

异常事件不是错误，但是一般会引起通话质量问题。发生异常事件后，如果恢复正常，也会收到该回调。

每个异常事件都有对应的恢复事件。

**异常事件**见下表：

| 事件码 | 提示消息 | 异常 |
| --- | --- | --- |
| 1001 | FRAMERATE_INPUT_TOO_LOW | 视频采集帧率过低 |
| 1002 | FRAMERATE_SENT_TOO_LOW | 视频发送帧率过低 |
| 1003 | SEND_VIDEO_BITRATE_TOO_LOW | 视频发送码率过低 |
| 1005 | RECV_VIDEO_DECODE_FAILED | 接收视频解码失败 |
| 2001 | AUDIO_INPUT_LEVEL_TOO_LOW | 发送音量过低 |
| 2002 | AUDIO_OUTPUT_LEVEL_TOO_LOW | 接收音量过低 |
| 2003 | SEND_AUDIO_BITRATE_TOO_LOW | 音频发送码率过低 |
| 2005 | RECV_AUDIO_DECODE_FAILED | 接收音频解码失败 |

**恢复事件**详见下表：

| 事件码 | 提示消息 | 恢复 |
| --- | --- | --- |
| 3001 | FRAMERATE_INPUT_TOO_LOW_RECOVER | 视频采集帧率恢复正常 |
| 3002 | FRAMERATE_SENT_TOO_LOW_RECOVER | 视频发送帧率恢复正常 |
| 3003 | SEND_VIDEO_BITRATE_TOO_LOW_RECOVER | 视频发送码率恢复正常 |
| 3005 | RECV_VIDEO_DECODE_FAILED_RECOVER | 接收视频解码恢复正常 |
| 4001 | AUDIO_INPUT_LEVEL_TOO_LOW_RECOVER | 发送音量恢复正常 |
| 4002 | AUDIO_OUTPUT_LEVEL_TOO_LOW_RECOVER | 接收音量恢复正常 |
| 4003 | SEND_AUDIO_BITRATE_TOO_LOW_RECOVER | 音频发送码率恢复正常 |
| 4005 | RECV_AUDIO_DECODE_FAILED_RECOVER | 接收音频解码恢复正常 |

<ParameterList title="Parameters">
<Parameter name="event" type="object" required>

<ParameterList>
<Parameter name="code" type="number" required>

事件码，详细见上表。

</Parameter>
<Parameter name="msg" type="string" required>

提示消息。

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

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

发生异常或者恢复异常的用户 ID。

</Parameter>
</ParameterList>

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_image_moderation_connection_state_change"></a>

### image-moderation-connection-state-change [#image-moderation-connection-state-change]

<ApiSignature>

image-moderation-connection-state-change(newState: [ImageModerationConnectionState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/imagemoderationconnectionstate), preState: [ImageModerationConnectionState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/imagemoderationconnectionstate)): void

</ApiSignature>

第三方视频审核服务连接状态发生改变回调。

```javascript
client.on("image-moderation-connection-state-change", (curState, preState) => {
   // image-moderation-connection-state-change: CONNECTING to CONNECTED
   console.info(`image-moderation-connection-state-change: ${preState} to ${curState}`);
});
```

<ParameterList title="Parameters">
<Parameter name="newState" required>

<ParameterType>

[ImageModerationConnectionState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/imagemoderationconnectionstate)

</ParameterType>

新的连接状态。

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

<ParameterType>

[ImageModerationConnectionState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/imagemoderationconnectionstate)

</ParameterType>

之前的连接状态。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_is_using_cloud_proxy"></a>

### is-using-cloud-proxy [#is-using-cloud-proxy]

<ApiSignature>

is-using-cloud-proxy(isUsingProxy: boolean): void

</ApiSignature>

:::info[自从]
*4.4.0*

SDK 通过这个回调通知当前媒体流是否经云代理服务转发。触发时机如下：

- v4.10.0 之前：成功调用 [publish](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#publish) 后。
- v4.10.0 及之后：成功调用 [join](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#join) 后。
:::

<ParameterList title="Parameters">
<Parameter name="isUsingProxy" type="boolean" required>

当前媒体流是否经云代理服务转发：

- `true`: 经云代理服务转发。
- `false`: 没有经云代理服务转发。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_join_fallback_to_proxy"></a>

### join-fallback-to-proxy [#join-fallback-to-proxy]

<ApiSignature>

join-fallback-to-proxy(proxyServer: string): void

</ApiSignature>

#### deprecated [#deprecated]

自 4.19.0 起废弃。SDK 不再使用代理保障连通性，因此不会再触发该回调。

SDK 自动切换至 TCP/TLS 443 回调。

自 v4.11.0 起，如果调用 [join](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#join) 后 SDK 直接连接 SD-RTN™ 失败，SDK 会自动切换到 TCP/TLS 443 通道，从而保障 SDK 的连通性。

<ParameterList title="Parameters">
<Parameter name="proxyServer" type="string" required>

切换后使用的服务器地址。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_live_streaming_error"></a>

### live-streaming-error [#live-streaming-error]

<ApiSignature>

live-streaming-error(url: string, err: AgoraRTCError): void

</ApiSignature>

推流发生错误回调。

在调用 [startLiveStreaming](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#startlivestreaming) 成功开始推流后，推流中途发生错误时，会通过这个事件抛出。

你可以访问 `err.code` 来获取错误码字符串，下面列出可能出现的错误：

- `LIVE_STREAMING_INVALID_ARGUMENT`: 推流参数错误。
- `LIVE_STREAMING_INTERNAL_SERVER_ERROR`: 推流服务器内部错误。
- `LIVE_STREAMING_PUBLISH_STREAM_NOT_AUTHORIZED`: 推流 URL 被占用。
- `LIVE_STREAMING_TRANSCODING_NOT_SUPPORTED`: 在非转码推流中调用了转码参数。
- `LIVE_STREAMING_CDN_ERROR`: 推流的目标 CDN 出现错误导致推流失败。
- `LIVE_STREAMING_INVALID_RAW_STREAM`: 推流超时，请确认目标流是否存在。

<ParameterList title="Parameters">
<Parameter name="url" type="string" required>

发生错误的直播推流地址。

</Parameter>
<Parameter name="err" type="AgoraRTCError" required>

详细的错误信息。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_live_streaming_warning"></a>

### live-streaming-warning [#live-streaming-warning]

<ApiSignature>

live-streaming-warning(url: string, warning: AgoraRTCError): void

</ApiSignature>

推流发生警告回调。

在调用 [startLiveStreaming](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#startlivestreaming) 成功开始推流后，推流中途发生警告时，会通过这个事件抛出。

你可以访问 `err.code` 来获取警告码字符串，下面列举可能出现的警告：

- `LIVE_STREAMING_WARN_STREAM_NUM_REACH_LIMIT`: 推流超过 10 路流。
- `LIVE_STREAMING_WARN_FAILED_LOAD_IMAGE`: 推流中的背景图片或者水印地址无法拉取。
- `LIVE_STREAMING_WARN_FREQUENT_REQUEST`: 推流请求太频繁。

<ParameterList title="Parameters">
<Parameter name="url" type="string" required>

发生警告的直播推流地址。

</Parameter>
<Parameter name="warning" type="AgoraRTCError" required>

详细的警告信息。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_media_reconnect_end"></a>

### media-reconnect-end [#media-reconnect-end]

<ApiSignature>

media-reconnect-end(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)): void

</ApiSignature>

SDK 重新建立媒体连接（用于发布和订阅）结束的回调。

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

重新建立的媒体连接所对应的用户 ID。如果是本地 `uid` 说明是重新发布，如果是远端 `uid` 说明是重新订阅。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_media_reconnect_start"></a>

### media-reconnect-start [#media-reconnect-start]

<ApiSignature>

media-reconnect-start(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)): void

</ApiSignature>

SDK 开始尝试重新建立媒体连接（用于发布和订阅）的回调。

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

重新建立的媒体连接所对应的用户 ID。如果是本地 `uid` 说明是重新发布，如果是远端 `uid` 说明是重新订阅。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_network_quality"></a>

### network-quality [#network-quality]

<ApiSignature>

network-quality(stats: [NetworkQuality](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/networkquality)): void

</ApiSignature>

网络上下行质量报告回调。

用户加入频道后，SDK 会每 2 秒触发一次该回调，报告本地用户当前的上行和下行网络质量。

> 我们推荐使用此回调来展示你的网络状态。

<ParameterList title="Parameters">
<Parameter name="stats" required>

<ParameterType>

[NetworkQuality](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/networkquality)

</ParameterType>

网络质量。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_published_user_list"></a>

### published-user-list [#published-user-list]

<ApiSignature>

published-user-list(users: [IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)[]): void

</ApiSignature>

:::info[自从]
*4.11.0*

如果开启了单频道支持 128 位主播的功能，该回调会在调用 [join](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#join) 时触发，返回当前频道内发布音频和视频轨道的用户。

**注意事项：**

- 频道内所有用户必须都使用整数型用户 ID（`uid`），`published-user-list` 才会触发。
- `published-user-list` 对 [AgoraRTCClient.on("user-joined")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_joined) 和 [AgoraRTCClient.on("user-published")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_published) 有以下影响：

  - 如果监听了 `published-user-list`，已经在 `published-user-list` 中返回的用户不会再通过 `user-joined` 和 `user-published` 重复返回。
  - 如果没有监听 `published-user-list`，`user-joined` 和 `user-published` 会正常触发。
:::

<ParameterList title="Parameters">
<Parameter name="users" required>

<ParameterType>

[IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)[]

</ParameterType>

远端用户对象。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_stream_fallback"></a>

### stream-fallback [#stream-fallback]

<ApiSignature>

stream-fallback(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), isFallbackOrRecover: "fallback" | "recover"): void

</ApiSignature>

订阅的音视频流回退为音频流或恢复为音视频流回调。

如果在 [setStreamFallbackOption](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setstreamfallbackoption) 中将 `fallbackType` 设为 2，当下行网络环境不理想、仅接收远端音频流时，或当下行网络改善、恢复订阅音视频流时，会触发该回调。

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

远端流对应的用户 ID。

</Parameter>
<Parameter name="isFallbackOrRecover" type="&quot;fallback&quot; | &quot;recover&quot;" required>

订阅流是回退还是恢复：

- `"fallback"`: 从音视频流回退为纯音频流。
- `"recover"`: 从音频流恢复为音视频。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_stream_message"></a>

### stream-message [#stream-message]

<ApiSignature>

stream-message(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), payload: Uint8Array): void

</ApiSignature>

收到数据流消息的回调。

```javascript
client.on("stream-message", (uid, payload) => {
   console.info(`received data stream message from ${uid}: `, payload);
});
```

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

消息发送者的 ID。

</Parameter>
<Parameter name="payload" type="Uint8Array" required>

消息内容。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_stream_type_changed"></a>

### stream-type-changed [#stream-type-changed]

<ApiSignature>

stream-type-changed(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), streamType: [RemoteStreamType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamtype)): void

</ApiSignature>

订阅的视频流类型发生改变回调。

视频流类型改变指视频大流（高码率、高分辨率）变为视频小流（低码率、低分辨率），或视频小流变为视频大流。

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

远端流对应的用户 ID。

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

<ParameterType>

[RemoteStreamType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamtype)

</ParameterType>

改变后的视频流类型:

- 0: 视频大流，即高码率、高分辨率的视频流。
- 1: 视频小流，即低码率、低分辨率的视频流。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_token_privilege_did_expire"></a>

### token-privilege-did-expire [#token-privilege-did-expire]

<ApiSignature>

token-privilege-did-expire(): void

</ApiSignature>

Token 已过期回调。

在 token 过期后，会收到该回调。

一般情况下，在收到该消息之后，应向服务端重新申请 token，并调用 [join](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#join) 方法传入新的 token 重新加入频道。

```javascript
client.on("token-privilege-did-expire", async () => {
  // 重新申请 token 后
  await client.join(<APPID>, <CHANNEL NAME>, <NEW TOKEN>);
});
```

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_token_privilege_will_expire"></a>

### token-privilege-will-expire [#token-privilege-will-expire]

<ApiSignature>

token-privilege-will-expire(): void

</ApiSignature>

Token 即将过期回调。

在 token 过期前 30 秒，会收到该回调。

在收到该回调之后，应向服务端重新申请 token，并调用 [renewToken](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#renewtoken) 方法传入新的 token。

```javascript
client.on("token-privilege-will-expire", async function(){
  // 重新申请 token 后
  await client.renewToken(token);
});
```

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_user_info_updated"></a>

### user-info-updated [#user-info-updated]

<ApiSignature>

user-info-updated(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), msg: "mute-audio" | "mute-video" | "enable-local-video" | "unmute-audio" | "unmute-video" | "disable-local-video"): void

</ApiSignature>

该回调用于提示用户状态变化。

在大部分情况下，你只需要监听 [user-published](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_published) 和 [user-unpublished](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_unpublished) 就可以完成订阅、取消订阅、展示远端用户是否打开了摄像头和麦克风等工作，无需特别关注实际用户状态的变化，SDK 会自动处理用户状态变化。

> 即使用户状态表示该用户的音视频流是活跃的，不一定意味着该用户可订阅。是否可订阅的唯一标志是收到 [user-published](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_published) 事件。

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

发生状态变化的用户 ID。

</Parameter>
<Parameter name="msg" type="&quot;mute-audio&quot; | &quot;mute-video&quot; | &quot;enable-local-video&quot; | &quot;unmute-audio&quot; | &quot;unmute-video&quot; | &quot;disable-local-video&quot;" required>

当前用户状态。其中，`"enable-local-video"` 和 `"disable-local-video"` 仅当和 Agora RTC Native SDK 互通时会触发。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_user_joined"></a>

### user-joined [#user-joined]

<ApiSignature>

user-joined(user: [IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)): void

</ApiSignature>

远端用户或主播加入频道回调。

- 通信场景下，该回调提示有远端用户加入了频道，并返回新加入用户的 ID；如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调。
- 直播场景下，该回调提示有主播加入了频道，并返回该主播的 ID。如果在加入之前，已经有主播在频道中了，新加入的用户也会收到已有主播加入频道的回调。声网建议连麦主播不超过 17 人。

该回调在以下情况下会被触发：

- 通信场景的远端用户/直播场景的远端主播调用 [join](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#join) 方法加入频道。
- 直播场景的远端观众加入频道后调用 [setClientRole](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setclientrole) 将用户角色改变为主播。
- 通信场景的远端用户/直播场景的远端主播网络中断后重新加入频道。

<ParameterList title="Parameters">
<Parameter name="user" required>

<ParameterType>

[IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)

</ParameterType>

加入频道的用户信息。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_user_left"></a>

### user-left [#user-left]

<ApiSignature>

user-left(user: [IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser), reason: string): void

</ApiSignature>

远端用户离线回调。

该回调通知 app 有远端用户离线，离线包括以下情况：

- 正常离开：用户会收到类似“再见”的消息，接收此消息后，判断对方离开频道。
- 超时掉线：在 20 秒内，用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。
- 用户角色从主播变为观众。

> 在直播场景中，只有角色为主播的用户会触发该回调。

<ParameterList title="Parameters">
<Parameter name="user" required>

<ParameterType>

[IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)

</ParameterType>

离线的用户信息。

</Parameter>
<Parameter name="reason" type="string" required>

用户离线的原因。

- `"Quit"`: 用户调用了 [leave](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#leave) 主动离开频道。
- `"ServerTimeOut"`: 因过长时间收不到对方数据包，超时掉线。注意：由于 SDK 使用的是不可靠通道，也有可能对方主动离开本方没收到对方离开消息而误判为超时掉线。
- `"BecomeAudience"`: 用户角色从主播切换为观众。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_user_published"></a>

### user-published [#user-published]

<ApiSignature>

user-published(user: [IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser), mediaType: "audio" | "video" | "datachannel", config?: IDataChannelConfig): void

</ApiSignature>

该回调通知远端用户发布了新的音频轨道或者视频轨道。

你可以在该回调中订阅并播放远端用户的音视频轨道。详见 [subscribe](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#subscribe) 和 [RemoteTrack.play](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotetrack#play)。

> 如果用户加入频道时频道内已经有其他用户的音视频轨道，也会收到该回调报告已经存在的远端轨道。

```javascript
client.on("user-published", async (user, mediaType) => {
  await client.subscribe(user, mediaType);
  if (mediaType === "video") {
    console.log("subscribe video success");
    user.videoTrack.play("xxx");
  }
  if (mediaType === "audio") {
    console.log("subscribe audio success");
    user.audioTrack.play();
  }
})
```

<ParameterList title="Parameters">
<Parameter name="user" required>

<ParameterType>

[IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)

</ParameterType>

远端用户信息。

</Parameter>
<Parameter name="mediaType" type="&quot;audio&quot; | &quot;video&quot; | &quot;datachannel&quot;" required>

远端用户发布的媒体类型。

- `"audio"`: 远端用户发布了音频轨道。
- `"video"`: 远端用户发布了视频轨道。
- `"datachannel"`: 预留参数。

</Parameter>
<Parameter name="config" type="IDataChannelConfig" optional>

预留参数。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_user_unpublished"></a>

### user-unpublished [#user-unpublished]

<ApiSignature>

user-unpublished(user: [IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser), mediaType: "audio" | "video" | "datachannel", config?: IDataChannelConfig): void

</ApiSignature>

该回调通知远端用户取消发布了音频或视频轨道。

<ParameterList title="Parameters">
<Parameter name="user" required>

<ParameterType>

[IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)

</ParameterType>

远端用户信息。

</Parameter>
<Parameter name="mediaType" type="&quot;audio&quot; | &quot;video&quot; | &quot;datachannel&quot;" required>

远端用户取消发布的媒体类型。

- `"audio"`: 远端用户取消发布了音频轨道。
- `"video"`: 远端用户取消发布了视频轨道。
- `"datachannel"`: 预留参数。

</Parameter>
<Parameter name="config" type="IDataChannelConfig" optional>

预留参数。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="event_volume_indicator"></a>

### volume-indicator [#volume-indicator]

<ApiSignature>

volume-indicator(result: object[]): void

</ApiSignature>

报告频道内正在说话的本地和远端用户及其音量的回调。

默认禁用。可以通过 [enableAudioVolumeIndicator](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#enableaudiovolumeindicator) 方法开启；开启后，无论频道内是否有人说话，都会每两秒返回提示音量。

音量范围为 0 到 100 之间。通常在列表中音量大于 60 的用户为持续说话的人。

```javascript
client.on("volume-indicator", function(result){
    result.forEach(function(volume, index){
    console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
  });
});
```

<ParameterList title="Parameters">
<Parameter name="result" type="object[]" required>

包含以下属性：

- level：音量，范围是 0 到 100。
- uid：说话者的用户 ID。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

## Properties [#properties]

<a id="channelname"></a>

<a id="optional-readonly-channelname"></a>

### channelName [#channelname]

<ApiSignature labels="Optional Readonly">

channelName: string

</ApiSignature>

当前加入的频道名称

如果本地用户没有加入频道，该属性值为 `undefined`。

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

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

### connectionState [#connectionstate]

<ApiSignature labels="Readonly">

connectionState: [ConnectionState](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#connectionstate)

</ApiSignature>

SDK 和声网服务器的连接状态。

<a id="localtracks"></a>

<a id="readonly-localtracks"></a>

### localTracks [#localtracks]

<ApiSignature labels="Readonly">

localTracks: [ILocalTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack)[]

</ApiSignature>

:::info[自从]
*4.0.0*

保存当前正在发布的本地轨道对象列表。

- 调用 [publish](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#publish) 成功后，发布的轨道对象会自动添加到这个列表中。
- 调用 [unpublish](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#unpublish) 成功后，取消发布的轨道对象会自动从这个列表中移除。
:::

<a id="remoteusers"></a>

<a id="readonly-remoteusers"></a>

### remoteUsers [#remoteusers]

<ApiSignature labels="Readonly">

remoteUsers: [IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)[]

</ApiSignature>

远端用户信息列表，包含频道中各个远端用户的用户 ID 和轨道信息。

如果本地用户没有加入频道，该列表为空。

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

<a id="optional-readonly-uid"></a>

### uid [#uid]

<ApiSignature labels="Optional Readonly">

uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ApiSignature>

本地用户的用户 ID。

如果本地用户没有加入频道，该属性值为 `undefined`。

## Agora Core Methods [#agora-core-methods]

<a id="join"></a>

### join [#join]

<ApiSignature>

join(appid: string, channel: string, token: string | null, uid?: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid) | null): Promise&lt;[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)&gt;

</ApiSignature>

加入频道。

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话。

调用该方法加入频道时，本地会触发 [AgoraRTCClient.on("connection-state-change")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_connection_state_change) 回调。

通信场景下的用户和直播场景下的主播加入频道后，远端会触发 [AgoraRTCClient.on("user-joined")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_joined) 回调。

<ParameterList title="Parameters">
<Parameter name="appid" type="string" required>

你的声网项目的 [App ID](/zh-CN/introduction/glossary)。

</Parameter>
<Parameter name="channel" type="string" required>

标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

- 26 个小写字母 a-z。
- 26 个大写字母 A-Z。
- 10 个数字 0-9。
- 空格。
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "&lt;", "=", ".", "&gt;", "?", "@", "[", "]", "^", "_", "\{", "\}", "|", "~", ","。

</Parameter>
<Parameter name="token" type="string | null" required>

用于鉴权的 token。

- 如果你的项目没有开启 token 鉴权，这里填 `null`。
- 安全要求不高: 你可以使用控制台生成的临时 token，详见[获取 RTC 临时 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)。
- 安全要求高：传入从你的服务端获得的正式 token，详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。

</Parameter>
<Parameter name="uid" optional>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid) | null

</ParameterType>

标识用户的 ID。整数或字符串，ASCII 字符，需保证唯一性。如果不指定或设为 `null`，服务器会自动分配一个整数型 uid 并在 Promise 中返回。

- 如果使用整数作为用户 ID，需为 32 位无符号整数。建议设置范围：0 到 (2³² - 1)。
- 如果使用字符串作为用户 ID，长度不超过 255 个字符。

:::caution
为保证最佳的用户体验，声网强烈建议你不要使用字符串作为用户 ID。
:::

:::note[注意事项]
- 一个频道内的所有用户必须使用同样类型的 `uid`，即必须都为整数或都为字符串。
- 使用字符串作为用户 ID 支持与 Native SDK 2.8 及以上版本互通，请确保 Native SDK 使用 User Account 加入频道。详见[使用 String 型的用户名](/zh-CN/reference/faq/integration/string_uid)。
- 为保证水晶球数据的准确性，建议自行指定 `uid` 并保证唯一性。
:::

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)&gt;

</ApiReturnType>

Promise 对象，包含本地用户的 ID：

- 如果你使用整数型 uid 加入频道，则返回整数型 uid。
- 如果你使用字符串型 uid 加入频道，则返回字符串型 uid。
- 如果你不指定或设为 `null`，声网服务器自动分配一个整数型 uid 并返回。

</ApiReturns>

<a id="leave"></a>

### leave [#leave]

<ApiSignature>

leave(): Promise&lt;void&gt;

</ApiSignature>

离开频道。

离开频道即挂断或退出通话。

调用该方法离开频道时，本地会触发 [AgoraRTCClient.on("connection-state-change")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_connection_state_change) 回调。

通信场景下的用户和直播场景下的主播离开频道后，远端会触发 [AgoraRTCClient.on("user-left")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_left) 回调。

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="publish"></a>

### publish [#publish]

<ApiSignature>

publish(tracks: [ILocalTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack) | [ILocalTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack)[]): Promise&lt;void&gt;

</ApiSignature>

发布本地音视频轨道。

该方法将本地音视频轨道发布至频道中。

发布音视频轨道之后，远端会触发 [AgoraRTCClient.on("user-published")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_published) 回调。

:::note[注意事项]
- 直播场景中，调用该方法前，必须先调用 [setClientRole](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setclientrole) 将用户角色设为主播。
- 你可以多次调用该方法添加要发布的轨道。
- 一个 `AgoraRTCClient` 对象可以发布多个音频轨道，SDK 会自动混音，将多个音频轨道合并为一个音频轨道。Safari 12 之前的版本不支持发布多个音频轨道。
- 一个 `AgoraRTCClient` 对象**只能发布一个视频轨道**。如果你想要更换视频轨道，例如已经发布了一个摄像头视频轨道，想要切换为屏幕共享视频轨道，你必须先取消发布。
:::

<ParameterList title="Parameters">
<Parameter name="tracks" required>

<ParameterType>

[ILocalTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack) | [ILocalTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack)[]

</ParameterType>

通过 [AgoraRTC.createMicrophoneAudioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createmicrophoneaudiotrack) / [AgoraRTC.createCameraTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartc#createcameravideotrack) 或其他方法创建的本地 Track 对象。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="subscribe"></a>

### subscribe [#subscribe]

#### subscribe [1/3] [#subscribe-13]

<ApiSignature>

subscribe(user: [IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser) | [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), mediaType: "video"): Promise&lt;[IRemoteVideoTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotevideotrack)&gt;

</ApiSignature>

订阅远端用户的音视频轨道。

```javascript
await client.subscribe(user，"audio");
user.audioTrack.play();
```

<ParameterList title="Parameters">
<Parameter name="user" required>

<ParameterType>

[IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser) | [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

远端用户对象。

</Parameter>
<Parameter name="mediaType" type="&quot;video&quot;" required>

订阅的轨道媒体类型。

- `"video"`: 订阅指定用户发布的视频轨道。
- `"audio"`: 订阅指定用户发布的音频轨道。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[IRemoteVideoTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotevideotrack)&gt;

</ApiReturnType>

订阅的异步操作完成后，返回远端轨道对象，该对象也会在 [user.audioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser#audiotrack) 和 [user.videoTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser#videotrack) 上更新，
 之后直接调用 [audioTrack.play](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremoteaudiotrack#play) 或 [videoTrack.play](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotevideotrack#play) 就可以播放了。

> 如果指定要订阅的音视频轨道不存在会抛出 `TRACK_IS_NOT_PUBLISHED` 错误。

</ApiReturns>

#### subscribe [2/3] [#subscribe-23]

<ApiSignature>

subscribe(user: [IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser) | [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), mediaType: "audio"): Promise&lt;[IRemoteAudioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremoteaudiotrack)&gt;

</ApiSignature>

订阅远端用户的音视频轨道。

```javascript
await client.subscribe(user，"audio");
user.audioTrack.play();
```

#### category [#category]

Agora Core

<ParameterList title="Parameters">
<Parameter name="user" required>

<ParameterType>

[IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser) | [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

远端用户对象。

</Parameter>
<Parameter name="mediaType" type="&quot;audio&quot;" required>

订阅的轨道媒体类型。

- `"video"`: 订阅指定用户发布的视频轨道。
- `"audio"`: 订阅指定用户发布的音频轨道。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[IRemoteAudioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremoteaudiotrack)&gt;

</ApiReturnType>

订阅的异步操作完成后，返回远端轨道对象，该对象也会在 [user.audioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser#audiotrack) 和 [user.videoTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser#videotrack) 上更新，
 之后直接调用 [audioTrack.play](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremoteaudiotrack#play) 或 [videoTrack.play](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotevideotrack#play) 就可以播放了。

> 如果指定要订阅的音视频轨道不存在会抛出 `TRACK_IS_NOT_PUBLISHED` 错误。

</ApiReturns>

#### subscribe [3/3] [#subscribe-33]

<ApiSignature>

subscribe(user: [IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser) | [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), mediaType: "video" | "audio" | "datachannel", channelId?: number): Promise&lt;[IRemoteTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotetrack) | IRemoteDataChannel&gt;

</ApiSignature>

订阅远端用户的音视频轨道。

```javascript
await client.subscribe(user，"audio");
user.audioTrack.play();
```

#### category [#category-1]

Agora Core

<ParameterList title="Parameters">
<Parameter name="user" required>

<ParameterType>

[IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser) | [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

远端用户对象。

</Parameter>
<Parameter name="mediaType" type="&quot;video&quot; | &quot;audio&quot; | &quot;datachannel&quot;" required>

订阅的轨道媒体类型。

- `"video"`: 订阅指定用户发布的视频轨道。
- `"audio"`: 订阅指定用户发布的音频轨道。
- `"datachannel"`: 预留参数。

</Parameter>
<Parameter name="channelId" type="number" optional />
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[IRemoteTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotetrack) | IRemoteDataChannel&gt;

</ApiReturnType>

订阅的异步操作完成后，返回远端轨道对象，该对象也会在 [user.audioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser#audiotrack) 和 [user.videoTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser#videotrack) 上更新，
 之后直接调用 [audioTrack.play](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremoteaudiotrack#play) 或 [videoTrack.play](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotevideotrack#play) 就可以播放了。

> 如果指定要订阅的音视频轨道不存在会抛出 `TRACK_IS_NOT_PUBLISHED` 错误。

</ApiReturns>

<a id="unpublish"></a>

### unpublish [#unpublish]

<ApiSignature>

unpublish(tracks?: [ILocalTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack) | [ILocalTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack)[]): Promise&lt;void&gt;

</ApiSignature>

取消发布本地音视频轨道。

取消发布音视频轨道之后，远端会触发 [AgoraRTCClient.on("user-unpublished")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_unpublished) 回调。

:::note[注意事项]
直播场景中，主播调用 [unpublish](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#unpublish) 取消发布轨道之后，用户角色不会自动切换为观众。如需将用户角色切换为观众，必须调用 [setClientRole](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setclientrole)。
:::

<ParameterList title="Parameters">
<Parameter name="tracks" optional>

<ParameterType>

[ILocalTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack) | [ILocalTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ilocaltrack)[]

</ParameterType>

要取消发布的轨道。如果留空，会将所有发布过的音视频轨道取消发布。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="unsubscribe"></a>

### unsubscribe [#unsubscribe]

<ApiSignature>

unsubscribe(user: [IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser) | [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), mediaType?: "video" | "audio" | "datachannel", channelId?: number): Promise&lt;void&gt;

</ApiSignature>

取消订阅远端用户的音视频轨道。

<ParameterList title="Parameters">
<Parameter name="user" required>

<ParameterType>

[IAgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser) | [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

远端用户对象。

</Parameter>
<Parameter name="mediaType" type="&quot;video&quot; | &quot;audio&quot; | &quot;datachannel&quot;" optional>

取消订阅的轨道媒体类型。

- `"video"`: 仅取消订阅指定用户的视频轨道。
- `“audio”`: 仅取消订阅指定用户的音频轨道。
- 如不填，取消订阅该用户发布的所有轨道。
- `"datachannel"`: 预留参数。

</Parameter>
<Parameter name="channelId" type="number" optional>

预留参数。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

如果指定的音视频轨道不存在会抛出 `TRACK_IS_NOT_SUBSCRIBED` 错误。

</ApiReturns>

## Channel Media Relay Methods [#channel-media-relay-methods]

<a id="startchannelmediarelay"></a>

### startChannelMediaRelay [#startchannelmediarelay]

<ApiSignature>

startChannelMediaRelay(config: [IChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ichannelmediarelayconfiguration)): Promise&lt;void&gt;

</ApiSignature>

开始跨频道媒体流转发。

调用该方法后，SDK 会触发以下回调：

- [AgoraRTCClient.on("channel-media-relay-state")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_channel_media_relay_state)，报告当前的跨频道媒体流转发状态和错误码。

  - 如果转发中途出现异常，该回调中 `state` 为 3，`code` 为错误码。你可以尝试再次调用本方法。
- [AgoraRTCClient.on("channel-media-relay-event")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_channel_media_relay_event)，报告跨频道媒体流转发相关的事件。

  - 如果跨频道服务开始向目标频道发送数据包，会触发回调，`code` 为 4.

:::note[注意事项]
- 跨频道媒体流转发功能需要联系 [sales@shengwang.cn](mailto:sales@shengwang.cn) 开通。
- 该功能不支持 String 型 UID。
- 请在成功加入频道后调用该方法。
- 直播场景下，只有主播可以调用该方法。
- 成功调用该方法后，若你想再次调用该方法，必须先调用 [stopChannelMediaRelay](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#stopchannelmediarelay) 方法退出当前的转发状态。
:::

```javascript
client.startChannelMediaRelay(config).then(() => {
  console.log("startChannelMediaRelay success");
}).catch(e => {
  console.log("startChannelMediaRelay failed", e);
})
```

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[IChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ichannelmediarelayconfiguration)

</ParameterType>

跨频道媒体流转发参数配置，详见 [ChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ichannelmediarelayconfiguration)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

Promise 对象。当 Promise resolve 后，表示成功开启了跨频道服务。

</ApiReturns>

<a id="stopchannelmediarelay"></a>

### stopChannelMediaRelay [#stopchannelmediarelay]

<ApiSignature>

stopChannelMediaRelay(): Promise&lt;void&gt;

</ApiSignature>

停止跨频道媒体流转发。

一旦停止转发，用户会退出所有的目标频道。

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

Promise 对象。当 Promise resolve 后，表示成功停止了跨频道服务。

</ApiReturns>

<a id="updatechannelmediarelay"></a>

### updateChannelMediaRelay [#updatechannelmediarelay]

<ApiSignature>

updateChannelMediaRelay(config: [IChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ichannelmediarelayconfiguration)): Promise&lt;void&gt;

</ApiSignature>

更新媒体流转发的目标频道。

成功开始跨频道转发媒体流后，如果你希望添加或删除媒体流转发的目标频道，可以调用该方法。

:::note[注意事项]
- 请在 [startChannelMediaRelay](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#startchannelmediarelay) 后调用该方法，更新媒体流转发的频道。
- 跨频道媒体流转发最多支持 4 个目标频道。
:::

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[IChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ichannelmediarelayconfiguration)

</ParameterType>

跨频道媒体流转发参数配置，详见 [ChannelMediaRelayConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/ichannelmediarelayconfiguration)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

Promise 对象。当 Promise resolve 后，表示更新成功，否则更新失败。出错后跨频道媒体流转发状态会被重置，你需要调用 [startChannelMediaRelay](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#startchannelmediarelay) 重新开始跨频道媒体流转发。

</ApiReturns>

## Dual Stream Methods [#dual-stream-methods]

<a id="disabledualstream"></a>

### disableDualStream [#disabledualstream]

<ApiSignature>

disableDualStream(): Promise&lt;void&gt;

</ApiSignature>

关闭双流模式。

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="enabledualstream"></a>

### enableDualStream [#enabledualstream]

<ApiSignature>

enableDualStream(): Promise&lt;void&gt;

</ApiSignature>

开启双流模式。

该方法为本地流开启双流模式。双流为视频大流和视频小流：

- 视频大流指高分辨率、高码率的视频流。
- 视频小流指低分辨率、低码率的视频流。小流的视频属性默认值固定为分辨率（宽 × 高） 160 × 120，码率 50 Kbps，帧率 15 fps。如果你不想要使用默认的小流视频属性，可以调用 [setLowStreamParameter](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setlowstreamparameter) 自定义小流参数，防止因小流码率过高而造成带宽压力。

:::note[注意事项]
- 在部分 Android 设备的浏览器上调用 `enableDualStream` 方法开启双流，会出现对端无法切换小流的问题。
- Android Chrome 上无法使用 H.264 编码发送大小流。
- 在部分使用 Intel 芯片的 Mac 设备的 Safari 浏览器 上，调用 `enableDualStream` 开启 H.264 编码的视频双流模式时，小流与大流分辨率比率低于 1/4 可能会导致系统卡顿。
:::

```javascript
client.enableDualStream().then(() => {
  console.log("Enable Dual stream success!");
}).catch(err => {
  console.log(err);
})
```

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="setlowstreamparameter"></a>

### setLowStreamParameter [#setlowstreamparameter]

<ApiSignature>

setLowStreamParameter(streamParameter: [LowStreamParameter](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/lowstreamparameter)): void

</ApiSignature>

设置小流视频属性。

如果你调用 [enableDualStream](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#enabledualstream) 开启了双流模式，该方法设置小流的视频属性。

如果你不设置小流的视频属性，SDK 会根据你的视频流属性自动适配小流的视频属性。

:::note[注意事项]
- 由于不同的设备和浏览器对于视频参数设置有不同的限制，`setLowStreamParameter` 设置的视频参数可能不会生效：

  - Firefox 上帧率设置不生效，浏览器会把帧率固定在 30 fps。此外，在 Mac Firefox 73+ 上设置帧率实际生效值偏小，且存在分辨率不准确的问题。
  - Safari 14 至 17.2 上的帧率设置不生效，浏览器会把帧率固定在 15 fps 左右，且小流的分辨率必须与大流的分辨率成比例。此外，在 iOS Safari 上设置 `LowStreamParameter.bitrate`不生效。
  - 部分浏览器上设置视频分辨率可能不会生效，这种情况下浏览器会自动调整分辨率，计费也将按照实际分辨率计算。
:::

<ParameterList title="Parameters">
<Parameter name="streamParameter" required>

<ParameterType>

[LowStreamParameter](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/lowstreamparameter)

</ParameterType>

小流的视频属性。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="setremotedefaultvideostreamtype"></a>

### setRemoteDefaultVideoStreamType [#setremotedefaultvideostreamtype]

<ApiSignature>

setRemoteDefaultVideoStreamType(streamType: [RemoteStreamType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamtype)): Promise&lt;void&gt;

</ApiSignature>

设置订阅所有远端用户的视频类型。

如果远端用户开启了双流模式，本地用户调用 `subscribe` 后会直接订阅本方法中 `streamType` 参数所指定的流类型。如不设置，默认订阅大流。

> - 建议在加入频道前调用 `setRemoteDefaultVideoStreamType`。
> - 如果你调用了 [setRemoteVideoStreamType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setremotevideostreamtype) 指定某个用户的流类型，则以该调用为准。

<ParameterList title="Parameters">
<Parameter name="streamType" required>

<ParameterType>

[RemoteStreamType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamtype)

</ParameterType>

订阅的视频流类型，0 代表大流，1 代表小流，详见 [RemoteStreamType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamtype)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="setremotevideostreamtype"></a>

### setRemoteVideoStreamType [#setremotevideostreamtype]

<ApiSignature>

setRemoteVideoStreamType(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), streamType: [RemoteStreamType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamtype)): Promise&lt;void&gt;

</ApiSignature>

设置订阅特定远端用户的视频类型。

如果远端用户开启了双流模式，该用户会发送两路视频流（一路大流和一路小流）。你可以通过 `setRemoteVideoStreamType` 在接收端选择订阅该用户的大流还是小流。如不设置，默认订阅大流。

> - 该方法只可在发送端通过 [enableDualStream](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#enabledualstream) 开启双流模式的情况下使用。
> - 若该方法和 [setStreamFallbackOption](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setstreamfallbackoption) 同时被调用，用户实际订阅的视频流取决于不同的设置。主要包括以下两种情况：
>
>   - [setStreamFallbackOption](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setstreamfallbackoption) 的参数设置为 `0` (DISABLE)时，订阅的视频流类型将由 `setRemoteVideoStreamType` 的设置决定。
>   - [setStreamFallbackOption](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setstreamfallbackoption) 的参数设置为 `1` (VIDEO_STREAM_LOW) 或 `2` (VIDEO_STREAM_HIGH)，则订阅的视频流类型会先按照 `setRemoteVideoStreamType`设置，但会根据网络状况进行动态调整。 例如，将 `setRemoteVideoStreamType` 参数设置为 `0`（订阅大流），但网络状况较差，SDK 将按照 `setStreamFallbackOption` 的设置进行弱网回退操作。

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

远端用户的 ID。

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

<ParameterType>

[RemoteStreamType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamtype)

</ParameterType>

订阅的视频流类型，0 代表大流，1 代表小流，详见 [RemoteStreamType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamtype)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="setstreamfallbackoption"></a>

### setStreamFallbackOption [#setstreamfallbackoption]

<ApiSignature>

setStreamFallbackOption(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), fallbackType: [RemoteStreamFallbackType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamfallbacktype)): Promise&lt;void&gt;

</ApiSignature>

设置媒体流回退策略。

该方法用于设置接收远端音视频流的回退策略。在弱网环境下，SDK 支持订阅视频小流（低分辨率、低码率视频流）或者仅订阅音频流。

当订阅流从视频大流回退为视频小流或从视频小流恢复为视频大流时，本地会触发
 [AgoraRTCClient.on("stream-type-changed")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_stream_type_changed) 回调。当订阅流回退为音频流或从音频流恢复为音视频流时，本地会触发 [AgoraRTCClient.on("stream-fallback")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_stream_fallback) 回调。

> - 该方法仅在远端用户调用 [enableDualStream](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#enabledualstream) 开启双流模式后生效。
> - 远端用户开启双流模式后，如果本地没有调用过 `setStreamFallbackOption`，默认的回退策略将生效，即在弱网环境下 SDK 会自动订阅远端用户的视频小流（[RemoteStreamFallbackType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamfallbacktype) 为 `1`）。

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

远端用户的 UID

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

<ParameterType>

[RemoteStreamFallbackType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamfallbacktype)

</ParameterType>

回退策略选项，详见 [RemoteStreamFallbackType](/zh-CN/api-reference/rtc/react-sdk/web-sdk/enums/remotestreamfallbacktype)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

## Live Streaming Methods [#live-streaming-methods]

<a id="setlivetranscoding"></a>

### setLiveTranscoding [#setlivetranscoding]

<ApiSignature>

setLiveTranscoding(config: [LiveStreamingTranscodingConfig](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/livestreamingtranscodingconfig)): Promise&lt;void&gt;

</ApiSignature>

设置直播推流转码的配置。

该方法用于旁路推流的视图布局及音频设置等。

> 使用前请确保已[开通旁路推流](/zh-CN/realtime-media/media-push)。

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[LiveStreamingTranscodingConfig](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/livestreamingtranscodingconfig)

</ParameterType>

直播转码的设置，详见 [LiveStreamingTranscodingConfig](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/livestreamingtranscodingconfig)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="startlivestreaming"></a>

### startLiveStreaming [#startlivestreaming]

<ApiSignature>

startLiveStreaming(url: string, transcodingEnabled?: boolean): Promise&lt;void&gt;

</ApiSignature>

将本地流发布到 CDN。

详见推流到 CDN。

:::note[注意事项]
- 该方法每次只能增加一路旁路推流地址。
:::

```javascript
await client.setLiveTranscoding(config);
await client.startLiveStreaming("rtmp://xxxx", true);
```

<ParameterList title="Parameters">
<Parameter name="url" type="string" required>

直播推流的地址，ASCII 字符。支持 RTMP 协议。

</Parameter>
<Parameter name="transcodingEnabled" type="boolean" optional>

(可选) 是否启用直播转码。转码是指在旁路推流时对音视频流进行转码处理后，再推送到其他 RTMP 服务器，适用于频道内有多个主播，需要进行混流、合图的场景。如果设为 `true`，需要在调用该方法前先调用 [setLiveTranscoding](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setlivetranscoding)。

- `true`: 启用转码，需要在调用该方法前先调用 [setLiveTranscoding](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#setlivetranscoding)。
- `false`: （默认）不启用转码，这种情况下需要保证当前用户正在发布。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="stoplivestreaming"></a>

### stopLiveStreaming [#stoplivestreaming]

<ApiSignature>

stopLiveStreaming(url: string): Promise&lt;void&gt;

</ApiSignature>

删除旁路推流地址。

该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。

<ParameterList title="Parameters">
<Parameter name="url" type="string" required>

待删除的推流地址。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

## Other Methods [#other-methods]

<a id="disablecontentinspect"></a>

### disableContentInspect [#disablecontentinspect]

<ApiSignature>

disableContentInspect(): Promise&lt;void&gt;

</ApiSignature>

关闭视频截图上传。

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="enableaudiovolumeindicator"></a>

### enableAudioVolumeIndicator [#enableaudiovolumeindicator]

<ApiSignature>

enableAudioVolumeIndicator(): void

</ApiSignature>

启用说话者音量提示。

该方法允许 SDK 定期报告正在说话的本地和远端用户及其音量。

启用音量提示后，无论频道中有没有人说话，SDK 都会每两秒触发 [AgoraRTCClient.on("volume-indicator")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_volume_indicator) 回调。

> 如果本地用户离开频道后再加入频道，你需要重新调用 `enableAudioVolumeIndicator`。

```javascript
client.enableAudioVolumeIndicator();
client.on("volume-indicator", volumes => {
  volumes.forEach((volume, index) => {
    console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
  });
})
```

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="enablecontentinspect"></a>

### enableContentInspect [#enablecontentinspect]

<ApiSignature>

enableContentInspect(inspectConfig: [InspectConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/inspectconfiguration)): Promise&lt;void&gt;

</ApiSignature>

开启视频截图上传。

开启视频截图上传后，SDK 会根据你在 [InspectConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/inspectconfiguration) 中设置的类型和频率，对本地用户发送的视频进行截图并上传。
 截图完成后，声网服务器会以 HTTPS 请求的形式，向你的服务器发送回调通知，并将所有截图发送至你指定的第三方云存储。具体步骤详见[视频截图上传](/zh-CN/realtime-media/rtc/build/video/content-inspect)。

> SDK 目前支持的最高截图频率为 1000 毫秒/次。

```javascript
client.enableContentInspect({
  // 设置每 5000ms 对本地视频轨道截一次图
  interval:5000,
  // 设置第三方云存储地址的前缀
  ossFilePrefix:`${channelName}/${uid}`,
  // 设置附加信息，附加信息随截图一起发送给你的服务器
  extraInfo:"fromAgora",
})
```

<ParameterList title="Parameters">
<Parameter name="inspectConfig" required>

<ParameterType>

[InspectConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/inspectconfiguration)

</ParameterType>

视频截图上传配置。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="getlisteners"></a>

### getListeners [#getlisteners]

<ApiSignature>

getListeners(event: string): Function[]

</ApiSignature>

Inherited from EventEmitter.getListeners

指定一个事件名，获取当前所有监听这个事件的回调函数。

<ParameterList title="Parameters">
<Parameter name="event" type="string" required>

事件名称。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Function[]

</ApiReturnType>

</ApiReturns>

<a id="getlocalaudiostats"></a>

### getLocalAudioStats [#getlocalaudiostats]

<ApiSignature>

getLocalAudioStats(): [LocalAudioTrackStats](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/localaudiotrackstats)

</ApiSignature>

:::info[自从]
*4.1.0*

获取本地音频相关信息。
:::

<ApiReturns>

<ApiReturnType>

[LocalAudioTrackStats](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/localaudiotrackstats)

</ApiReturnType>

</ApiReturns>

<a id="getlocalvideostats"></a>

### getLocalVideoStats [#getlocalvideostats]

<ApiSignature>

getLocalVideoStats(): [LocalVideoTrackStats](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/localvideotrackstats)

</ApiSignature>

获取本地视频相关信息。

:::note[注意事项]
iOS 14.4 及更早版本上无法获取到 `encodeDelay` 字段。
:::

<ApiReturns>

<ApiReturnType>

[LocalVideoTrackStats](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/localvideotrackstats)

</ApiReturnType>

</ApiReturns>

<a id="getrtcstats"></a>

### getRTCStats [#getrtcstats]

<ApiSignature>

getRTCStats(): [AgoraRTCStats](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/agorartcstats)

</ApiSignature>

获取当前通话的统计信息。

<ApiReturns>

<ApiReturnType>

[AgoraRTCStats](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/agorartcstats)

</ApiReturnType>

通话相关的统计信息。

</ApiReturns>

<a id="getremoteaudiostats"></a>

### getRemoteAudioStats [#getremoteaudiostats]

<ApiSignature>

getRemoteAudioStats(): object

</ApiSignature>

:::info[自从]
*4.1.0*

获取远端用户的音频相关信息。

**Note:**

统计信息需要在订阅远端流后进行计算，可能耗费 0-3 秒时间。你可以循环调用该方法。
:::

<ApiReturns>

<ApiReturnType>

object

</ApiReturnType>

<ParameterList title="Returns object">
<Parameter name="[uid" required>

<ParameterType>

string]:[RemoteAudioTrackStats](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/remoteaudiotrackstats)

</ParameterType>

</Parameter>
</ParameterList>

</ApiReturns>

<a id="getremotenetworkquality"></a>

### getRemoteNetworkQuality [#getremotenetworkquality]

<ApiSignature>

getRemoteNetworkQuality(): object

</ApiSignature>

:::info[自从]
*4.2.0*

获取本地订阅的所有远端用户的上下行网络质量。
:::

<ApiReturns>

<ApiReturnType>

object

</ApiReturnType>

<ParameterList title="Returns object">
<Parameter name="[uid" required>

<ParameterType>

string]:[NetworkQuality](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/networkquality)

</ParameterType>

</Parameter>
</ParameterList>

</ApiReturns>

<a id="getremotevideostats"></a>

### getRemoteVideoStats [#getremotevideostats]

<ApiSignature>

getRemoteVideoStats(): object

</ApiSignature>

:::info[自从]
*4.1.0*

获取远端用户的视频统计信息。

**Note:**

统计信息需要在订阅远端流后进行计算，可能耗费 0-3 秒时间。你可以循环调用该方法。
:::

<ApiReturns>

<ApiReturnType>

object

</ApiReturnType>

<ParameterList title="Returns object">
<Parameter name="[uid" required>

<ParameterType>

string]:[RemoteVideoTrackStats](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/remotevideotrackstats)

</ParameterType>

</Parameter>
</ParameterList>

</ApiReturns>

<a id="masssubscribe"></a>

### massSubscribe [#masssubscribe]

<ApiSignature>

massSubscribe(subscribeList: object[]): Promise&lt;object[]&gt;

</ApiSignature>

:::info[自从]
*4.11.0*

批量订阅远端用户的音视频轨道。

```javascript
const result = await client.massSubscribe([{user:userA, mediaType:'audio'}, {user: userB, mediaType:'audio'}]);

for(const {track, mediaType, error} of result) {
  if(error) {
    console.error(error);
    continue;
  }

  if(track) {
    if(mediaType === 'audio') {
      track.play();
    }else{
      track.play(document.querySelector('.video-container'));
    }
  }
}
```
:::

<ParameterList title="Parameters">
<Parameter name="subscribeList" type="object[]" required>

订阅的远端用户列表。列表中的每一条都包含以下信息：

- `user`：远端用户对象，详见 [AgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)。
- `mediaType`：订阅的轨道媒体类型。

  - `"video"`: 订阅指定用户的视频轨道。
  - `"audio"`: 订阅指定用户的音频轨道。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;object[]&gt;

</ApiReturnType>

正常情况下，返回列表的长度与顺序和 `subscribeList` 一致。列表中的每一条都包含以下信息：

- `user`：远端用户对象，详见 [AgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)。
- `mediaType`：已订阅的轨道媒体类型。

  - `"video"`: 已订阅指定用户发布的视频轨道。
  - `"audio"`: 已订阅指定用户发布的音频轨道。
- `track`：远端轨道对象，详见 [RemoteTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotetrack)。
- `error`：错误信息。如果对单个用户的音视频轨道订阅失败，会通过这个参数返回错误。

</ApiReturns>

<a id="massunsubscribe"></a>

### massUnsubscribe [#massunsubscribe]

<ApiSignature>

massUnsubscribe(unsubscribeList: object[]): Promise&lt;void&gt;

</ApiSignature>

:::info[自从]
*4.11.0*

批量取消订阅远端用户的音视频轨道。

```javascript
client.massUnsubscribe([{user:userA}, {user: userB}]);
```
:::

<ParameterList title="Parameters">
<Parameter name="unsubscribeList" type="object[]" required>

取消订阅的远端用户列表。列表中的每一条都包含以下信息：

- `user`：远端用户对象，详见 [AgoraRTCRemoteUser](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcremoteuser)。
- `mediaType`：取消订阅的轨道媒体类型。

  - `"video"`: 取消订阅指定用户的视频轨道。
  - `"audio"`: 取消订阅指定用户的音频轨道。
  - 如不填，取消订阅该用户发布的所有轨道。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="off"></a>

### off [#off]

<ApiSignature>

off(event: string, listener: Function): void

</ApiSignature>

Inherited from EventEmitter.off

取消一个指定事件的监听。

<ParameterList title="Parameters">
<Parameter name="event" type="string" required>

指定事件的名称。

</Parameter>
<Parameter name="listener" type="Function" required>

监听事件时传入的回调函数。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="on"></a>

### on [#on]

#### on [1/28] [#on-128]

<ApiSignature>

on(event: "connection-state-change", listener: typeof event_connection_state_change): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;connection-state-change&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_connection_state_change" required>

详见 [connection-state-change](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_connection_state_change)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [2/28] [#on-228]

<ApiSignature>

on(event: "user-joined", listener: typeof event_user_joined): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;user-joined&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_user_joined" required>

详见 [user-joined](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_joined)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [3/28] [#on-328]

<ApiSignature>

on(event: "user-left", listener: typeof event_user_left): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;user-left&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_user_left" required>

详见 [user-left](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_left)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [4/28] [#on-428]

<ApiSignature>

on(event: "user-published", listener: typeof event_user_published): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;user-published&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_user_published" required>

详见 [user-published](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_published)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [5/28] [#on-528]

<ApiSignature>

on(event: "user-unpublished", listener: typeof event_user_unpublished): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;user-unpublished&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_user_unpublished" required>

详见 [user-unpublished](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_unpublished)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [6/28] [#on-628]

<ApiSignature>

on(event: "user-info-updated", listener: typeof event_user_info_updated): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;user-info-updated&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_user_info_updated" required>

详见 [user-info-updated](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_info_updated)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [7/28] [#on-728]

<ApiSignature>

on(event: "media-reconnect-start", listener: typeof event_media_reconnect_start): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;media-reconnect-start&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_media_reconnect_start" required>

详见 [media-reconnect-start](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_media_reconnect_start)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [8/28] [#on-828]

<ApiSignature>

on(event: "media-reconnect-end", listener: typeof event_media_reconnect_end): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;media-reconnect-end&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_media_reconnect_end" required>

详见 [media-reconnect-end](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_media_reconnect_end)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [9/28] [#on-928]

<ApiSignature>

on(event: "stream-type-changed", listener: typeof event_stream_type_changed): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;stream-type-changed&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_stream_type_changed" required>

详见 [stream-type-changed](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_stream_type_changed)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [10/28] [#on-1028]

<ApiSignature>

on(event: "stream-fallback", listener: typeof event_stream_fallback): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;stream-fallback&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_stream_fallback" required>

详见 [stream-fallback](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_stream_fallback)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [11/28] [#on-1128]

<ApiSignature>

on(event: "channel-media-relay-state", listener: typeof event_channel_media_relay_state): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;channel-media-relay-state&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_channel_media_relay_state" required>

详见 [channel-media-relay-state](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_channel_media_relay_state)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [12/28] [#on-1228]

<ApiSignature>

on(event: "channel-media-relay-event", listener: typeof event_channel_media_relay_event): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;channel-media-relay-event&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_channel_media_relay_event" required>

详见 [channel-media-relay-event](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_channel_media_relay_event)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [13/28] [#on-1328]

<ApiSignature>

on(event: "volume-indicator", listener: typeof event_volume_indicator): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;volume-indicator&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_volume_indicator" required>

详见 [volume-indicator](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_volume_indicator)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [14/28] [#on-1428]

<ApiSignature>

on(event: "crypt-error", listener: typeof event_crypt_error): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;crypt-error&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_crypt_error" required>

详见 [crypt-error](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_crypt_error)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [15/28] [#on-1528]

<ApiSignature>

on(event: "token-privilege-will-expire", listener: typeof event_token_privilege_will_expire): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;token-privilege-will-expire&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_token_privilege_will_expire" required>

详见 [token-privilege-will-expire](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_token_privilege_will_expire)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [16/28] [#on-1628]

<ApiSignature>

on(event: "token-privilege-did-expire", listener: typeof event_token_privilege_did_expire): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;token-privilege-did-expire&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_token_privilege_did_expire" required>

详见 [token-privilege-did-expire](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_token_privilege_did_expire)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [17/28] [#on-1728]

<ApiSignature>

on(event: "network-quality", listener: typeof event_network_quality): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;network-quality&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_network_quality" required>

详见 [network-quality](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_network_quality)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [18/28] [#on-1828]

<ApiSignature>

on(event: "live-streaming-error", listener: typeof event_live_streaming_error): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;live-streaming-error&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_live_streaming_error" required>

详见 [live-streaming-error](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_live_streaming_error)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [19/28] [#on-1928]

<ApiSignature>

on(event: "live-streaming-warning", listener: typeof event_live_streaming_warning): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;live-streaming-warning&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_live_streaming_warning" required>

详见 [live-streaming-warning](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_live_streaming_warning)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [20/28] [#on-2028]

<ApiSignature>

on(event: "exception", listener: typeof event_exception): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;exception&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_exception" required>

详见 [exception](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_exception)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [21/28] [#on-2128]

<ApiSignature>

on(event: "is-using-cloud-proxy", listener: typeof event_is_using_cloud_proxy): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;is-using-cloud-proxy&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_is_using_cloud_proxy" required>

详见 [is-using-cloud-proxy](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_is_using_cloud_proxy)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [22/28] [#on-2228]

<ApiSignature>

on(event: "join-fallback-to-proxy", listener: typeof event_join_fallback_to_proxy): void

</ApiSignature>

Overrides EventEmitter.on

#### deprecated [#deprecated-1]

自 4.19.0 起废弃。

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;join-fallback-to-proxy&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_join_fallback_to_proxy" required>

详见 [join-fallback-to-proxy](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_join_fallback_to_proxy)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [23/28] [#on-2328]

<ApiSignature>

on(event: "published-user-list", listener: typeof event_published_user_list): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;published-user-list&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_published_user_list" required>

详见 [published-user-list](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_published_user_list)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [24/28] [#on-2428]

<ApiSignature>

on(event: "content-inspect-connection-state-change", listener: typeof event_content_inspect_connection_state_change): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;content-inspect-connection-state-change&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_content_inspect_connection_state_change" required>

详见 [content-inspect-connection-state-change](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_content_inspect_connection_state_change)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [25/28] [#on-2528]

<ApiSignature>

on(event: "content-inspect-error", listener: typeof event_content_inspect_error): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;content-inspect-error&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_content_inspect_error" required>

详见 [content-inspect-error](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_content_inspect_error)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [26/28] [#on-2628]

<ApiSignature>

on(event: "image-moderation-connection-state-change", listener: typeof event_image_moderation_connection_state_change): void

</ApiSignature>

Overrides EventEmitter.on

当指定的事件触发时，会调用传入的回调函数。

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;image-moderation-connection-state-change&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_image_moderation_connection_state_change" required>

详见 [image-moderation-connection-state-change](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_image_moderation_connection_state_change)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [27/28] [#on-2728]

<ApiSignature>

on(event: "stream-message", listener: typeof event_stream_message): void

</ApiSignature>

Overrides EventEmitter.on

<ParameterList title="Parameters">
<Parameter name="event" type="&quot;stream-message&quot;" required>

事件名称。

</Parameter>
<Parameter name="listener" type="typeof event_stream_message" required>

详见 [stream-message](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_stream_message)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

#### on [28/28] [#on-2828]

<ApiSignature>

on(event: string, listener: Function): void

</ApiSignature>

Overrides EventEmitter.on

当指定的事件触发时，会调用传入的回调函数。

<ParameterList title="Parameters">
<Parameter name="event" type="string" required>

事件名称。

</Parameter>
<Parameter name="listener" type="Function" required>

回调函数。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="once"></a>

### once [#once]

<ApiSignature>

once(event: string, listener: Function): void

</ApiSignature>

Inherited from EventEmitter.once

监听一个指定的事件，当事件触发时会调用传入的回调函数。

当监听后事件第一次触发时，该监听和回调函数就会被立刻移除，也就是只监听一次指定事件。

<ParameterList title="Parameters">
<Parameter name="event" type="string" required>

指定事件的名称。

</Parameter>
<Parameter name="listener" type="Function" required>

传入的回调函数。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="presubscribe"></a>

### presubscribe [#presubscribe]

#### presubscribe [1/3] [#presubscribe-13]

<ApiSignature>

presubscribe(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), mediaType: "audio"): Promise&lt;[IRemoteAudioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremoteaudiotrack)&gt;

</ApiSignature>

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

</Parameter>
<Parameter name="mediaType" type="&quot;audio&quot;" required />
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[IRemoteAudioTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremoteaudiotrack)&gt;

</ApiReturnType>

</ApiReturns>

#### presubscribe [2/3] [#presubscribe-23]

<ApiSignature>

presubscribe(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), mediaType: "video"): Promise&lt;[IRemoteVideoTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotevideotrack)&gt;

</ApiSignature>

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

</Parameter>
<Parameter name="mediaType" type="&quot;video&quot;" required />
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[IRemoteVideoTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotevideotrack)&gt;

</ApiReturnType>

</ApiReturns>

#### presubscribe [3/3] [#presubscribe-33]

<ApiSignature>

presubscribe(uid: [UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid), mediaType: "video" | "audio"): Promise&lt;[IRemoteTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotetrack)&gt;

</ApiSignature>

<ParameterList title="Parameters">
<Parameter name="uid" required>

<ParameterType>

[UID](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#uid)

</ParameterType>

</Parameter>
<Parameter name="mediaType" type="&quot;video&quot; | &quot;audio&quot;" required />
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;[IRemoteTrack](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iremotetrack)&gt;

</ApiReturnType>

</ApiReturns>

<a id="removealllisteners"></a>

### removeAllListeners [#removealllisteners]

<ApiSignature>

removeAllListeners(event?: string): void

</ApiSignature>

Inherited from EventEmitter.removeAllListeners

指定一个事件，取消其所有的监听。

<ParameterList title="Parameters">
<Parameter name="event" type="string" optional>

指定事件的名称，如果没有指定事件，则取消所有事件的所有监听。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="renewtoken"></a>

### renewToken [#renewtoken]

<ApiSignature>

renewToken(token: string): Promise&lt;void&gt;

</ApiSignature>

更新 token。

如果启用了 token 机制，过一段时间后 token 会失效。当收到 [AgoraRTCClient.on("token-privilege-will-expire")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_token_privilege_will_expire) 回调时, 调用该方法传入新的 token，否则 SDK 会无法和服务器建立连接。

<ParameterList title="Parameters">
<Parameter name="token" type="string" required>

新的 token。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="sendcustomreportmessage"></a>

### sendCustomReportMessage [#sendcustomreportmessage]

<ApiSignature>

sendCustomReportMessage(reports: [EventCustomReportParams](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/eventcustomreportparams)[] | [EventCustomReportParams](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/eventcustomreportparams)): Promise&lt;void&gt;

</ApiSignature>

自定义事件上报，用于将自定义的数据格式上报到声网的数据中心。

> - 目前支持 5s 内最多上报 20 条事件。

<ParameterList title="Parameters">
<Parameter name="reports" required>

<ParameterType>

[EventCustomReportParams](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/eventcustomreportparams)[] | [EventCustomReportParams](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/eventcustomreportparams)

</ParameterType>

上报的事件，允许一次上传多条事件。

```javascript
client.sendCustomReportMessage({
  reportId: "id1", category: "category1", event: "custom", label: "label1", value: 0,
}).then(() => {
  console.log("send custom report success");
}).catch(e => {
  console.error("send custom report error");
});
```

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="setclientrole"></a>

### setClientRole [#setclientrole]

<ApiSignature>

setClientRole(role: [ClientRole](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#clientrole), options?: [ClientRoleOptions](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/clientroleoptions)): Promise&lt;void&gt;

</ApiSignature>

设置直播场景中（[mode](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/clientconfig#mode) 设为 `"live"`）的用户角色。

- 用户角色 (role) 确定用户在 SDK 层的权限，包含是否可以发送流、是否可以接收流、是否可以推流到 CDN 等。用户角色有 `"host"`（主播）和 `"audience"`（观众）。主播既可发布轨道，也可订阅轨道；观众不能进行 [publish](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#publish) 操作。直播场景中的用户角色默认为观众。如需发布音视频，必须先调用本方法切换角色为主播。
- 用户角色具体设置包含用户级别 (level)。用户级别确定用户在其权限范围内可以操作和享受到的服务级别。例如对于观众，选择接收低延时还是超低延时的视频流。不同的级别会影响计费。

:::note[注意事项]
- 通信场景（[mode](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/clientconfig#mode) 设为 `"rtc"`）无法使用本方法，默认所有用户都是 `"host"` 角色。
- 如果在加入频道后调用该方法切换用户角色，远端会触发 [AgoraRTCClient.on("user-joined")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_joined) 或者 [AgoraRTCClient.on("user-left")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_user_left) 回调。
- 如果已经调用了 [publish](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#publish)，想要将用户角色切换为 `"audience"` 时，必须先调用 [unpublish](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#unpublish) 取消发布后再调用本方法，否则会设置失败并抛出异常。
:::

<ParameterList title="Parameters">
<Parameter name="role" required>

<ParameterType>

[ClientRole](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#clientrole)

</ParameterType>

用户角色。

</Parameter>
<Parameter name="options" optional>

<ParameterType>

[ClientRoleOptions](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/clientroleoptions)

</ParameterType>

用户具体设置，包含观众延时级别。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="setencryptionconfig"></a>

### setEncryptionConfig [#setencryptionconfig]

<ApiSignature>

setEncryptionConfig(encryptionMode: [EncryptionMode](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#encryptionmode), secret: string, salt?: Uint8Array, encryptDataStream?: boolean): void

</ApiSignature>

设置加密方案。

该方法用于设置 SDK 内置的加密算法和密钥，开启内置加密功能。

如果该方法设置错误，在发布或者订阅时会触发 [AgoraRTCClient.on("crypt-error")](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_crypt_error) 回调。

:::note[注意事项]
- 同一频道内的所有用户必须设置相同的加密模式、密钥和盐值才能进行互通。
- 该方法必须在加入频道前调用，否则加密不生效。
- 自 v4.7.0 起，用户离开频道后，SDK 会自动关闭加密。如需重新开启加密，你需要在用户再次加入频道前调用该方法。
- 请勿在 CDN 推流场景中使用内置加密功能。
:::

<ParameterList title="Parameters">
<Parameter name="encryptionMode" required>

<ParameterType>

[EncryptionMode](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#encryptionmode)

</ParameterType>

加密模式。

</Parameter>
<Parameter name="secret" type="string" required>

ASCII 字符。当用户设置的密码为弱密码时，SDK 会在控制台打印警告信息，提醒用户设置强密码，即密码必须包含大写字母、小写字母、数字和特殊字符，以及长度至少 8 个字符。由于浏览器加密算法限制，密钥长度不能超过 62 个字符。声网推荐你在服务端使用 OpenSSL 生成密钥，详见媒体流加密。

</Parameter>
<Parameter name="salt" type="Uint8Array" optional>

盐值，仅当加密模式为 `"aes-128-gcm2"` 或 `"aes-256-gcm2"` 时有效。声网推荐你在服务端使用 OpenSSL 生成盐值，详见媒体流加密。

</Parameter>
<Parameter name="encryptDataStream" type="boolean" optional>

是否加密数据流。数据流加密模式需与媒体流一致。数据流加密目前仅支持 `"aes-128-gcm2"` 和 `"aes-256-gcm2"` 模式，使用其他加密模式会出现报错。

- `true`: 启用数据流加密。
- `false`: 不启用数据流加密。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="setimagemoderation"></a>

### setImageModeration [#setimagemoderation]

#### setImageModeration [1/2] [#setimagemoderation-12]

<ApiSignature>

setImageModeration(enabled: false): Promise&lt;void&gt;

</ApiSignature>

关闭第三方视频审核服务。

<ParameterList title="Parameters">
<Parameter name="enabled" type="false" required>

默认为 `false` 且只能设为 `false`。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

#### setImageModeration [2/2] [#setimagemoderation-22]

<ApiSignature>

setImageModeration(enabled: true, config: [ImageModerationConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/imagemoderationconfiguration)): Promise&lt;void&gt;

</ApiSignature>

开启和配置第三方视频审核服务。

调用该方法后，SDK 会触发 [image-moderation-connection-state-change](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#event_image_moderation_connection_state_change) 回调，并且对本地用户发送的视频进行截图、发送给第三方服务商进行审核。

> - 调用该方法前，请确保满足以下要求：
>
>   - 已经开通第三方视频审核服务。
>   - 本地用户已加入频道，本地视频轨道已经发布并且处于启用状态。

<ParameterList title="Parameters">
<Parameter name="enabled" type="true" required>

默认为 `true` 且只能设为 `true`。

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

<ParameterType>

[ImageModerationConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/imagemoderationconfiguration)

</ParameterType>

视频审核服务的配置。详见 [ImageModerationConfiguration](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/imagemoderationconfiguration)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

Promise&lt;void&gt;

</ApiReturnType>

</ApiReturns>

<a id="setlocalaccesspointsv2"></a>

### setLocalAccessPointsV2 [#setlocalaccesspointsv2]

<ApiSignature>

setLocalAccessPointsV2(config: [LocalAccessPointConfig](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#localaccesspointconfig)): void

</ApiSignature>

:::info[自从]
*4.16.0*

配置声网混合云或私有化平台的相关服务。

成功部署声网混合云或私有化平台并在内网终端集成 Agora Web SDK 后，你可以调用该方法设置访问节点和相关服务。
 联系 [sales@shengwang.cn](mailto:sales@shengwang.cn) 了解和部署声网混合云或声网私有化平台。

**Note:**

- 使用混合云或私有化平台时，不支持开启云代理服务，因此该方法不能与 [startProxyServer](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#startproxyserver) 一起调用。
- 成功配置混合云或私有化平台后，SDK 如果直接连接 SD-RTN™ 失败，将不会自动切换到 TCP/TLS 443 通道，即不会再触发 `join-fallback-to-proxy` 回调。
- 由于 [Chrome 已知问题](https://bugs.chromium.org/p/chromium/issues/detail?id=1290390)，使用该接口过程中 Chrome 控制台可能会误报错误信息提示，开发者可以忽略。

```javascript
client.setLocalAccessPointsV2({
  accessPoints: {
    serverList:["192.168.1.1","192.168.2.2"],
    domain: 'test.agora.io'
  },
  log:{
     hostname:["abc.com"],
     port: 3000
  },
  report:{
    hostname:["example.com"],
    port: 8080
  }
})
```
:::

<ParameterList title="Parameters">
<Parameter name="config" required>

<ParameterType>

[LocalAccessPointConfig](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#localaccesspointconfig)

</ParameterType>

混合云或私有化平台的配置参数。详见 [LocalAccessPointConfig](/zh-CN/api-reference/rtc/react-sdk/web-sdk/globals#localaccesspointconfig)。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

## Proxy Methods [#proxy-methods]

<a id="setproxyserver"></a>

### setProxyServer [#setproxyserver]

<ApiSignature>

setProxyServer(proxyServer: string): void

</ApiSignature>

:::info[自从]
*4.18.0*

部署你的代理服务器。

该方法不能与 [startProxyServer](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#startproxyserver) 同时调用，二者区别如下：

- `setProxyServer`：自定义代理，可以用于信令传输、日志上传、事件上报等，但不能用于媒体传输。
- `startProxyServer`：声网提供的云代理服务，可以传输媒体流、信令等，只需简单设置即可使用。详见[使用云代理服务](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)。

**注意事项：**

- 该方法必须在 [join](/zh-CN/api-reference/rtc/react-sdk/web-sdk/interfaces/iagorartcclient#join) 之前调用。
- 在使用 Firefox 浏览器时，跨运营商代理速度会比较慢。声网建议使用同运营商进行代理。如果必须使用跨运营商代理，则避免使用 Firefox 浏览器。
:::

<ParameterList title="Parameters">
<Parameter name="proxyServer" type="string" required>

你的代理服务器域名，ASCII 字符。

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="startproxyserver"></a>

### startProxyServer [#startproxyserver]

<ApiSignature>

startProxyServer(mode?: number): void

</ApiSignature>

开启云代理服务。

该方法必须在加入频道前或离开频道后调用。

使用云代理服务还需要一些额外设置，详见[使用云代理服务](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)。

<ParameterList title="Parameters">
<Parameter name="mode" type="number" optional>

云代理模式：

- `3`: UDP 协议的云代理，即 Force UDP 云代理模式。在该模式下，SDK 始终通过 UDP 协议传输数据。
- `5`: TCP（加密）协议的云代理，即 Force TCP 云代理模式。在该模式下，SDK 始终通过 TLS 443 传输数据。

:::note[注意事项]
自 v4.15.0 起，`mode` 的默认值为 `3`。
:::

</Parameter>
</ParameterList>

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>

<a id="stopproxyserver"></a>

### stopProxyServer [#stopproxyserver]

<ApiSignature>

stopProxyServer(): void

</ApiSignature>

关闭云代理服务。

该方法必须在加入频道前或离开频道后调用。

<ApiReturns>

<ApiReturnType>

void

</ApiReturnType>

</ApiReturns>