Interface IAgoraRTCClient

提供音视频通话的核心功能，比如加入频道、发布和订阅音视频轨道等。
你可以通过 createClient 创建一个 AgoraRTCClient 对象。一个 AgoraRTCClient 对象代表一个本地客户端。

Events

channel-media-relay-event

channel-media-relay-event(event: ChannelMediaRelayEvent): void

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

参数

参数名	描述
event: ChannelMediaRelayEvent	事件码，详见 ChannelMediaRelayEvent。

返回值

void

channel-media-relay-state

channel-media-relay-state(state: ChannelMediaRelayState, code: ChannelMediaRelayError): void

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

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

回调会携带当前跨频道媒体流转发服务的状态 ChannelMediaRelayState，如果状态异常，相应的错误码可以通过 ChannelMediaRelayError 获取（比如 token 过期，重连失败等）。

参数

参数名	描述
state: ChannelMediaRelayState	跨频道媒体流转发服务的状态。
code: ChannelMediaRelayError	跨频道媒体流转发错误码。

返回值

void

connection-state-change

connection-state-change(curState: ConnectionState, revState: ConnectionState, reason?: ConnectionDisconnectedReason): void

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

参数

参数名	描述
curState: ConnectionState	当前的连接状态。
revState: ConnectionState	之前的连接状态。
reason: ConnectionDisconnectedReason	如果 `curState` 为 `"DISCONNECTED"`，这里表示断开连接的原因。

返回值

void

content-inspect-connection-state-change

content-inspect-connection-state-change(preState: InspectState, newState: InspectState): void

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

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

参数

参数名	描述
preState: InspectState	之前的连接状态。
newState: InspectState	新的连接状态。

返回值

void

content-inspect-error

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

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

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

参数

参数名描述

error: AgoraRTCError

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

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

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

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

返回值

void

crypt-error

crypt-error(): void

解密失败回调。

该回调表示用户在订阅过程中出现了解密失败，通常是由于和发布端设置的加密参数不一致导致的。详见 setEncryptionConfig。

返回值

void

exception

exception(event: object): void

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	接收音频解码恢复正常

参数

参数名	描述
event: object	code: number 事件码，详细见上表。 msg: string 提示消息。 uid: UID 发生异常或者恢复异常的用户 ID。

返回值

void

image-moderation-connection-state-change

image-moderation-connection-state-change(newState: ImageModerationConnectionState, preState: ImageModerationConnectionState): void

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

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}`);
});

参数

参数名	描述
newState: ImageModerationConnectionState	新的连接状态。
preState: ImageModerationConnectionState	之前的连接状态。

返回值

void

is-using-cloud-proxy

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

自从

4.4.0

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

v4.10.0 之前：成功调用 publish 后。
v4.10.0 及之后：成功调用 join 后。

参数

参数名	描述
isUsingProxy: boolean	当前媒体流是否经云代理服务转发： `true`: 经云代理服务转发。 `false`: 没有经云代理服务转发。

返回值

void

join-fallback-to-proxy

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

deprecated

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

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

自 v4.11.0 起，如果调用 join 后 SDK 直接连接 SD-RTN™ 失败，SDK 会自动切换到 TCP/TLS 443 通道，从而保障 SDK 的连通性。

参数

参数名	描述
proxyServer: string	切换后使用的服务器地址。

返回值

void

live-streaming-error

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

推流发生错误回调。

在调用 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: 推流超时，请确认目标流是否存在。

参数

参数名	描述
url: string	发生错误的直播推流地址。
err: AgoraRTCError	详细的错误信息。

返回值

void

live-streaming-warning

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

推流发生警告回调。

在调用 startLiveStreaming 成功开始推流后，推流中途发生警告时，会通过这个事件抛出。

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

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

参数

参数名	描述
url: string	发生警告的直播推流地址。
warning: AgoraRTCError	详细的警告信息。

返回值

void

media-reconnect-end

media-reconnect-end(uid: UID): void

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

参数

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

返回值

void

media-reconnect-start

media-reconnect-start(uid: UID): void

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

参数

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

返回值

void

network-quality

network-quality(stats: NetworkQuality): void

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

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

注意

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

参数

参数名	描述
stats: NetworkQuality	网络质量。

返回值

void

published-user-list

published-user-list(users: IAgoraRTCRemoteUser[]): void

自从

4.11.0

如果开启了单频道支持 128 位主播的功能，该回调会在调用 join 时触发，返回当前频道内发布音频和视频轨道的用户。

注意

注意事项：

频道内所有用户必须都使用整数型用户 ID（uid），published-user-list 才会触发。
published-user-list 对 AgoraRTCClient.on("user-joined") 和 AgoraRTCClient.on("user-published") 有以下影响：
- 如果监听了 published-user-list，已经在 published-user-list 中返回的用户不会再通过 user-joined 和 user-published 重复返回。
- 如果没有监听 published-user-list，user-joined 和 user-published 会正常触发。

参数

参数名	描述
users: IAgoraRTCRemoteUser[]	远端用户对象。

返回值

void

stream-fallback

stream-fallback(uid: UID, isFallbackOrRecover: "fallback" | "recover"): void

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

如果在 setStreamFallbackOption 中将 fallbackType 设为 2，当下行网络环境不理想、仅接收远端音频流时，或当下行网络改善、恢复订阅音视频流时，会触发该回调。

参数

参数名	描述
uid: UID	远端流对应的用户 ID。
isFallbackOrRecover: "fallback" \| "recover"	订阅流是回退还是恢复： `"fallback"`: 从音视频流回退为纯音频流。 `"recover"`: 从音频流恢复为音视频。

返回值

void

stream-message

stream-message(uid: UID, payload: Uint8Array): void

收到数据流消息的回调。

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

参数

参数名	描述
uid: UID	消息发送者的 ID。
payload: Uint8Array	消息内容。

返回值

void

stream-type-changed

stream-type-changed(uid: UID, streamType: RemoteStreamType): void

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

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

参数

参数名	描述
uid: UID	远端流对应的用户 ID。
streamType: RemoteStreamType	改变后的视频流类型: 0: 视频大流，即高码率、高分辨率的视频流。 1: 视频小流，即低码率、低分辨率的视频流。

返回值

void

token-privilege-did-expire

token-privilege-did-expire(): void

Token 已过期回调。

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

一般情况下，在收到该消息之后，应向服务端重新申请 token，并调用 join 方法传入新的 token 重新加入频道。

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

返回值

void

token-privilege-will-expire

token-privilege-will-expire(): void

Token 即将过期回调。

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

在收到该回调之后，应向服务端重新申请 token，并调用 renewToken 方法传入新的 token。

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

返回值

void

user-info-updated

user-info-updated(uid: UID, msg: "mute-audio" | "mute-video" | "enable-local-video" | "unmute-audio" | "unmute-video" | "disable-local-video"): void

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

在大部分情况下，你只需要监听 user-published 和 user-unpublished 就可以完成订阅、取消订阅、展示远端用户是否打开了摄像头和麦克风等工作，无需特别关注实际用户状态的变化，SDK 会自动处理用户状态变化。

注意

即使用户状态表示该用户的音视频流是活跃的，不一定意味着该用户可订阅。是否可订阅的唯一标志是收到 user-published 事件。

参数

参数名	描述
uid: UID	发生状态变化的用户 ID。
msg: "mute-audio" \| "mute-video" \| "enable-local-video" \| "unmute-audio" \| "unmute-video" \| "disable-local-video"	当前用户状态。其中，`"enable-local-video"` 和 `"disable-local-video"` 仅当和 Agora RTC Native SDK 互通时会触发。

返回值

void

user-joined

user-joined(user: IAgoraRTCRemoteUser): void

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

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

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

通信场景的远端用户/直播场景的远端主播调用 join 方法加入频道。
直播场景的远端观众加入频道后调用 setClientRole 将用户角色改变为主播。
通信场景的远端用户/直播场景的远端主播网络中断后重新加入频道。

参数

参数名	描述
user: IAgoraRTCRemoteUser	加入频道的用户信息。

返回值

void

user-left

user-left(user: IAgoraRTCRemoteUser, reason: string): void

远端用户离线回调。

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

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

注意

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

参数

参数名	描述
user: IAgoraRTCRemoteUser	离线的用户信息。
reason: string	用户离线的原因。 `"Quit"`: 用户调用了 leave 主动离开频道。 `"ServerTimeOut"`: 因过长时间收不到对方数据包，超时掉线。注意：由于 SDK 使用的是不可靠通道，也有可能对方主动离开本方没收到对方离开消息而误判为超时掉线。 `"BecomeAudience"`: 用户角色从主播切换为观众。

返回值

void

user-published

user-published(user: IAgoraRTCRemoteUser, mediaType: "audio" | "video" | "datachannel", config?: IDataChannelConfig): void

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

你可以在该回调中订阅并播放远端用户的音视频轨道。详见 subscribe 和 RemoteTrack.play。

注意

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

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();
 }
})

参数

参数名	描述
user: IAgoraRTCRemoteUser	远端用户信息。
mediaType: "audio" \| "video" \| "datachannel"	远端用户发布的媒体类型。 `"audio"`: 远端用户发布了音频轨道。 `"video"`: 远端用户发布了视频轨道。 `"datachannel"`: 预留参数。
config: IDataChannelConfig	预留参数。

返回值

void

user-unpublished

user-unpublished(user: IAgoraRTCRemoteUser, mediaType: "audio" | "video" | "datachannel", config?: IDataChannelConfig): void

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

参数

参数名	描述
user: IAgoraRTCRemoteUser	远端用户信息。
mediaType: "audio" \| "video" \| "datachannel"	远端用户取消发布的媒体类型。 `"audio"`: 远端用户取消发布了音频轨道。 `"video"`: 远端用户取消发布了视频轨道。 `"datachannel"`: 预留参数。
config: IDataChannelConfig	预留参数。

返回值

void

volume-indicator

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

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

默认禁用。可以通过 enableAudioVolumeIndicator 方法开启；开启后，无论频道内是否有人说话，都会每两秒返回提示音量。

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

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

参数

参数名	描述
result: object[]	包含以下属性： level：音量，范围是 0 到 100。 uid：说话者的用户 ID。

返回值

void

Properties

Optional

Readonly

channelName

channelName: string

当前加入的频道名称
如果本地用户没有加入频道，该属性值为 undefined。

Readonly

connectionState

connectionState: ConnectionState

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

Readonly

localTracks

localTracks: ILocalTrack[]

自从

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

调用 publish 成功后，发布的轨道对象会自动添加到这个列表中。
调用 unpublish 成功后，取消发布的轨道对象会自动从这个列表中移除。

Readonly

remoteUsers

remoteUsers: IAgoraRTCRemoteUser[]

远端用户信息列表，包含频道中各个远端用户的用户 ID 和轨道信息。
如果本地用户没有加入频道，该列表为空。

Optional

Readonly

uid

uid: UID

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

Agora Core Methods

join

join(appid: string, channel: string, token: string | null, uid?: UID | null): Promise<UID>

加入频道。

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

调用该方法加入频道时，本地会触发 AgoraRTCClient.on("connection-state-change") 回调。

通信场景下的用户和直播场景下的主播加入频道后，远端会触发 AgoraRTCClient.on("user-joined") 回调。

参数

参数名	描述
appid: string	你的声网项目的 App ID。
channel: string	标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）: 26 个小写字母 a-z。 26 个大写字母 A-Z。 10 个数字 0-9。空格。 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "\|", "~", ","。
token: string \| null	用于鉴权的 token。如果你的项目没有开启 token 鉴权，这里填 `null`。安全要求不高: 你可以使用控制台生成的临时 token，详见获取 RTC 临时 Token。安全要求高：传入从你的服务端获得的正式 token，详见使用 Token 鉴权。
uid: UID \| null	标识用户的 ID。整数或字符串，ASCII 字符，需保证唯一性。如果不指定或设为 `null`，服务器会自动分配一个整数型 uid 并在 Promise 中返回。如果使用整数作为用户 ID，需为 32 位无符号整数。建议设置范围：0 到 (2³²-1)。如果使用字符串作为用户 ID，长度不超过 255 个字符。为保证最佳的用户体验，声网强烈建议你不要使用字符串作为用户 ID。注意事项：一个频道内的所有用户必须使用同样类型的 `uid`，即必须都为整数或都为字符串。使用字符串作为用户 ID 支持与 Native SDK 2.8 及以上版本互通，请确保 Native SDK 使用 User Account 加入频道。详见使用 String 型的用户名。为保证水晶球数据的准确性，建议自行指定 `uid` 并保证唯一性。

返回值

Promise<UID>

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

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

leave

leave(): Promise<void>

离开频道。

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

调用该方法离开频道时，本地会触发 AgoraRTCClient.on("connection-state-change") 回调。

通信场景下的用户和直播场景下的主播离开频道后，远端会触发 AgoraRTCClient.on("user-left") 回调。

返回值

Promise<void>

publish

publish(tracks: ILocalTrack | ILocalTrack[]): Promise<void>

发布本地音视频轨道。

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

发布音视频轨道之后，远端会触发 AgoraRTCClient.on("user-published") 回调。

注意

注意事项：

直播场景中，调用该方法前，必须先调用 setClientRole 将用户角色设为主播。
你可以多次调用该方法添加要发布的轨道。
一个 AgoraRTCClient 对象可以发布多个音频轨道，SDK 会自动混音，将多个音频轨道合并为一个音频轨道。Safari 12 之前的版本不支持发布多个音频轨道。
一个 AgoraRTCClient 对象只能发布一个视频轨道。如果你想要更换视频轨道，例如已经发布了一个摄像头视频轨道，想要切换为屏幕共享视频轨道，你必须先取消发布。

参数

参数名	描述
tracks: ILocalTrack \| ILocalTrack[]	通过 AgoraRTC.createMicrophoneAudioTrack / AgoraRTC.createCameraTrack 或其他方法创建的本地 Track 对象。

返回值

Promise<void>

subscribe(user: IAgoraRTCRemoteUser | UID, mediaType: "video"): Promise<IRemoteVideoTrack>

subscribe(user: IAgoraRTCRemoteUser | UID, mediaType: "video"): Promise<IRemoteVideoTrack>

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

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

参数

参数名	描述
user: IAgoraRTCRemoteUser \| UID	远端用户对象。
mediaType: "video"	订阅的轨道媒体类型。 `"video"`: 订阅指定用户发布的视频轨道。 `"audio"`: 订阅指定用户发布的音频轨道。

返回值

Promise<IRemoteVideoTrack>

订阅的异步操作完成后，返回远端轨道对象，该对象也会在 user.audioTrack 和 user.videoTrack 上更新，之后直接调用 audioTrack.play 或 videoTrack.play 就可以播放了。

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

subscribe(user: IAgoraRTCRemoteUser | UID, mediaType: "audio"): Promise<IRemoteAudioTrack>

subscribe(user: IAgoraRTCRemoteUser | UID, mediaType: "audio"): Promise<IRemoteAudioTrack>

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

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

category: Agora Core

参数

参数名	描述
user: IAgoraRTCRemoteUser \| UID	远端用户对象。
mediaType: "audio"	订阅的轨道媒体类型。 `"video"`: 订阅指定用户发布的视频轨道。 `"audio"`: 订阅指定用户发布的音频轨道。

返回值

Promise<IRemoteAudioTrack>

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

subscribe(user: IAgoraRTCRemoteUser | UID, mediaType: "video" | "audio" | "datachannel", channelId?: number): Promise<IRemoteTrack | IRemoteDataChannel>

subscribe(user: IAgoraRTCRemoteUser | UID, mediaType: "video" | "audio" | "datachannel", channelId?: number): Promise<IRemoteTrack | IRemoteDataChannel>

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

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

category: Agora Core

参数

参数名	描述
user: IAgoraRTCRemoteUser \| UID	远端用户对象。
mediaType: "video" \| "audio" \| "datachannel"	订阅的轨道媒体类型。 `"video"`: 订阅指定用户发布的视频轨道。 `"audio"`: 订阅指定用户发布的音频轨道。 `"datachannel"`: 预留参数。
channelId: number

返回值

Promise<IRemoteTrack | IRemoteDataChannel>

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

unpublish

unpublish(tracks?: ILocalTrack | ILocalTrack[]): Promise<void>

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

取消发布音视频轨道之后，远端会触发 AgoraRTCClient.on("user-unpublished") 回调。

注意

注意事项：直播场景中，主播调用 unpublish 取消发布轨道之后，用户角色不会自动切换为观众。如需将用户角色切换为观众，必须调用 setClientRole。

参数

参数名	描述
tracks: ILocalTrack \| ILocalTrack[]	要取消发布的轨道。如果留空，会将所有发布过的音视频轨道取消发布。

返回值

Promise<void>

unsubscribe

unsubscribe(user: IAgoraRTCRemoteUser | UID, mediaType?: "video" | "audio" | "datachannel", channelId?: number): Promise<void>

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

参数

参数名	描述
user: IAgoraRTCRemoteUser \| UID	远端用户对象。
mediaType: "video" \| "audio" \| "datachannel"	取消订阅的轨道媒体类型。 `"video"`: 仅取消订阅指定用户的视频轨道。 `“audio”`: 仅取消订阅指定用户的音频轨道。如不填，取消订阅该用户发布的所有轨道。 `"datachannel"`: 预留参数。
channelId: number	预留参数。

返回值

Promise<void>

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

Channel Media Relay Methods

startChannelMediaRelay

startChannelMediaRelay(config: IChannelMediaRelayConfiguration): Promise<void>

开始跨频道媒体流转发。

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

AgoraRTCClient.on("channel-media-relay-state")，报告当前的跨频道媒体流转发状态和错误码。
- 如果转发中途出现异常，该回调中 state 为 3，code 为错误码。你可以尝试再次调用本方法。
AgoraRTCClient.on("channel-media-relay-event")，报告跨频道媒体流转发相关的事件。
- 如果跨频道服务开始向目标频道发送数据包，会触发回调，code 为 4.

注意

注意事项：

跨频道媒体流转发功能需要联系 sales@shengwang.cn 开通。
该功能不支持 String 型 UID。
请在成功加入频道后调用该方法。
直播场景下，只有主播可以调用该方法。
成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。

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

参数

参数名	描述
config: IChannelMediaRelayConfiguration	跨频道媒体流转发参数配置，详见 ChannelMediaRelayConfiguration。

返回值

Promise<void>

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

stopChannelMediaRelay

stopChannelMediaRelay(): Promise<void>

停止跨频道媒体流转发。

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

返回值

Promise<void>

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

updateChannelMediaRelay

updateChannelMediaRelay(config: IChannelMediaRelayConfiguration): Promise<void>

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

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

注意

注意事项：

请在 startChannelMediaRelay 后调用该方法，更新媒体流转发的频道。
跨频道媒体流转发最多支持 4 个目标频道。

参数

参数名	描述
config: IChannelMediaRelayConfiguration	跨频道媒体流转发参数配置，详见 ChannelMediaRelayConfiguration。

返回值

Promise<void>

Promise 对象。当 Promise resolve 后，表示更新成功，否则更新失败。出错后跨频道媒体流转发状态会被重置，你需要调用 startChannelMediaRelay 重新开始跨频道媒体流转发。

Dual Stream Methods

disableDualStream

disableDualStream(): Promise<void>

关闭双流模式。

返回值

Promise<void>

enableDualStream

enableDualStream(): Promise<void>

开启双流模式。

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

视频大流指高分辨率、高码率的视频流。
视频小流指低分辨率、低码率的视频流。小流的视频属性默认值固定为分辨率（宽 × 高） 160 × 120，码率 50 Kbps，帧率 15 fps。如果你不想要使用默认的小流视频属性，可以调用 setLowStreamParameter 自定义小流参数，防止因小流码率过高而造成带宽压力。

注意

注意事项：

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

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

返回值

Promise<void>

setLowStreamParameter

setLowStreamParameter(streamParameter: LowStreamParameter): void

设置小流视频属性。

如果你调用 enableDualStream 开启了双流模式，该方法设置小流的视频属性。

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

注意

注意事项：

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

参数

参数名	描述
streamParameter: LowStreamParameter	小流的视频属性。

返回值

void

setRemoteDefaultVideoStreamType

setRemoteDefaultVideoStreamType(streamType: RemoteStreamType): Promise<void>

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

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

注意

建议在加入频道前调用 setRemoteDefaultVideoStreamType。
如果你调用了 setRemoteVideoStreamType 指定某个用户的流类型，则以该调用为准。

参数

参数名	描述
streamType: RemoteStreamType	订阅的视频流类型，0 代表大流，1 代表小流，详见 RemoteStreamType。

返回值

Promise<void>

setRemoteVideoStreamType

setRemoteVideoStreamType(uid: UID, streamType: RemoteStreamType): Promise<void>

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

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

注意

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

参数

参数名	描述
uid: UID	远端用户的 ID。
streamType: RemoteStreamType	订阅的视频流类型，0 代表大流，1 代表小流，详见 RemoteStreamType。

返回值

Promise<void>

setStreamFallbackOption

setStreamFallbackOption(uid: UID, fallbackType: RemoteStreamFallbackType): Promise<void>

设置媒体流回退策略。

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

当订阅流从视频大流回退为视频小流或从视频小流恢复为视频大流时，本地会触发 AgoraRTCClient.on("stream-type-changed") 回调。当订阅流回退为音频流或从音频流恢复为音视频流时，本地会触发 AgoraRTCClient.on("stream-fallback") 回调。

注意

该方法仅在远端用户调用 enableDualStream 开启双流模式后生效。
远端用户开启双流模式后，如果本地没有调用过 setStreamFallbackOption，默认的回退策略将生效，即在弱网环境下 SDK 会自动订阅远端用户的视频小流（RemoteStreamFallbackType 为 1）。

参数

参数名	描述
uid: UID	远端用户的 UID
fallbackType: RemoteStreamFallbackType	回退策略选项，详见 RemoteStreamFallbackType。

返回值

Promise<void>

Live Streaming Methods

setLiveTranscoding

setLiveTranscoding(config: LiveStreamingTranscodingConfig): Promise<void>

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

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

注意

使用前请确保已开通旁路推流。

参数

参数名	描述
config: LiveStreamingTranscodingConfig	直播转码的设置，详见 LiveStreamingTranscodingConfig。

返回值

Promise<void>

startLiveStreaming

startLiveStreaming(url: string, transcodingEnabled?: boolean): Promise<void>

将本地流发布到 CDN。

详见推流到 CDN。

注意

注意事项：

该方法每次只能增加一路旁路推流地址。

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

参数

参数名描述

参数名	描述
url: string	直播推流的地址，ASCII 字符。支持 RTMP 协议。
transcodingEnabled: boolean	(可选) 是否启用直播转码。转码是指在旁路推流时对音视频流进行转码处理后，再推送到其他 RTMP 服务器，适用于频道内有多个主播，需要进行混流、合图的场景。如果设为 `true`，需要在调用该方法前先调用 setLiveTranscoding。 `true`: 启用转码，需要在调用该方法前先调用 setLiveTranscoding。 `false`: （默认）不启用转码，这种情况下需要保证当前用户正在发布。

url: string

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

transcodingEnabled: boolean

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

true: 启用转码，需要在调用该方法前先调用 setLiveTranscoding。
false: （默认）不启用转码，这种情况下需要保证当前用户正在发布。

返回值

Promise<void>

stopLiveStreaming

stopLiveStreaming(url: string): Promise<void>

删除旁路推流地址。

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

参数

参数名	描述
url: string	待删除的推流地址。

返回值

Promise<void>

Other Methods

disableContentInspect

disableContentInspect(): Promise<void>

关闭视频截图上传。

返回值

Promise<void>

enableAudioVolumeIndicator

enableAudioVolumeIndicator(): void

启用说话者音量提示。

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

启用音量提示后，无论频道中有没有人说话，SDK 都会每两秒触发 AgoraRTCClient.on("volume-indicator") 回调。

注意

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

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

返回值

void

enableContentInspect

enableContentInspect(inspectConfig: InspectConfiguration): Promise<void>

开启视频截图上传。

开启视频截图上传后，SDK 会根据你在 InspectConfiguration 中设置的类型和频率，对本地用户发送的视频进行截图并上传。截图完成后，声网服务器会以 HTTPS 请求的形式，向你的服务器发送回调通知，并将所有截图发送至你指定的第三方云存储。具体步骤详见视频截图上传。

注意

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

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

参数

参数名	描述
inspectConfig: InspectConfiguration	视频截图上传配置。

返回值

Promise<void>

getListeners

getListeners(event: string): Function[]

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

参数

参数名	描述
event: string	事件名称。

返回值

Function[]

getLocalAudioStats

getLocalAudioStats(): LocalAudioTrackStats

自从

4.1.0

获取本地音频相关信息。

返回值

LocalAudioTrackStats

getLocalVideoStats

getLocalVideoStats(): LocalVideoTrackStats

获取本地视频相关信息。

注意

注意事项：iOS 14.4 及更早版本上无法获取到 encodeDelay 字段。

返回值

LocalVideoTrackStats

getRTCStats

getRTCStats(): AgoraRTCStats

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

返回值

AgoraRTCStats

通话相关的统计信息。

getRemoteAudioStats

getRemoteAudioStats(): object

自从

4.1.0

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

注意

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

返回值

object

[uid: string]: RemoteAudioTrackStats

getRemoteNetworkQuality

getRemoteNetworkQuality(): object

自从

4.2.0

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

返回值

object

[uid: string]: NetworkQuality

getRemoteVideoStats

getRemoteVideoStats(): object

自从

4.1.0

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

注意

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

返回值

object

[uid: string]: RemoteVideoTrackStats

massSubscribe

massSubscribe(subscribeList: object[]): Promise<object[]>

自从

4.11.0

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

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'));
 }
 }
}

参数

参数名	描述
subscribeList: object[]	订阅的远端用户列表。列表中的每一条都包含以下信息： `user`：远端用户对象，详见 AgoraRTCRemoteUser。 `mediaType`：订阅的轨道媒体类型。 `"video"`: 订阅指定用户的视频轨道。 `"audio"`: 订阅指定用户的音频轨道。

返回值

Promise<object[]>

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

user：远端用户对象，详见 AgoraRTCRemoteUser。
mediaType：已订阅的轨道媒体类型。
- "video": 已订阅指定用户发布的视频轨道。
- "audio": 已订阅指定用户发布的音频轨道。
track：远端轨道对象，详见 RemoteTrack。
error：错误信息。如果对单个用户的音视频轨道订阅失败，会通过这个参数返回错误。

massUnsubscribe

massUnsubscribe(unsubscribeList: object[]): Promise<void>

自从

4.11.0

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

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

参数

参数名	描述
unsubscribeList: object[]	取消订阅的远端用户列表。列表中的每一条都包含以下信息： `user`：远端用户对象，详见 AgoraRTCRemoteUser。 `mediaType`：取消订阅的轨道媒体类型。 `"video"`: 取消订阅指定用户的视频轨道。 `"audio"`: 取消订阅指定用户的音频轨道。如不填，取消订阅该用户发布的所有轨道。

返回值

Promise<void>

off

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

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

参数

参数名	描述
event: string	指定事件的名称。
listener: Function	监听事件时传入的回调函数。

返回值

void

on

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

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

参数

参数名	描述
event: "connection-state-change"	事件名称。
listener: typeof event_connection_state_change	详见 connection-state-change。

返回值

void

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

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

参数

参数名	描述
event: "user-joined"	事件名称。
listener: typeof event_user_joined	详见 user-joined。

返回值

void

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

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

参数

参数名	描述
event: "user-left"	事件名称。
listener: typeof event_user_left	详见 user-left。

返回值

void

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

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

参数

参数名	描述
event: "user-published"	事件名称。
listener: typeof event_user_published	详见 user-published。

返回值

void

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

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

参数

参数名	描述
event: "user-unpublished"	事件名称。
listener: typeof event_user_unpublished	详见 user-unpublished。

返回值

void

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

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

参数

参数名	描述
event: "user-info-updated"	事件名称。
listener: typeof event_user_info_updated	详见 user-info-updated。

返回值

void

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

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

参数

参数名	描述
event: "media-reconnect-start"	事件名称。
listener: typeof event_media_reconnect_start	详见 media-reconnect-start。

返回值

void

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

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

参数

参数名	描述
event: "media-reconnect-end"	事件名称。
listener: typeof event_media_reconnect_end	详见 media-reconnect-end。

返回值

void

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

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

参数

参数名	描述
event: "stream-type-changed"	事件名称。
listener: typeof event_stream_type_changed	详见 stream-type-changed。

返回值

void

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

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

参数

参数名	描述
event: "stream-fallback"	事件名称。
listener: typeof event_stream_fallback	详见 stream-fallback。

返回值

void

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

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

参数

参数名	描述
event: "channel-media-relay-state"	事件名称。
listener: typeof event_channel_media_relay_state	详见 channel-media-relay-state。

返回值

void

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

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

参数

参数名	描述
event: "channel-media-relay-event"	事件名称。
listener: typeof event_channel_media_relay_event	详见 channel-media-relay-event。

返回值

void

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

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

参数

参数名	描述
event: "volume-indicator"	事件名称。
listener: typeof event_volume_indicator	详见 volume-indicator。

返回值

void

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

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

参数

参数名	描述
event: "crypt-error"	事件名称。
listener: typeof event_crypt_error	详见 crypt-error。

返回值

void

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

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

参数

参数名	描述
event: "token-privilege-will-expire"	事件名称。
listener: typeof event_token_privilege_will_expire	详见 token-privilege-will-expire。

返回值

void

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

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

参数

参数名	描述
event: "token-privilege-did-expire"	事件名称。
listener: typeof event_token_privilege_did_expire	详见 token-privilege-did-expire。

返回值

void

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

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

参数

参数名	描述
event: "network-quality"	事件名称。
listener: typeof event_network_quality	详见 network-quality。

返回值

void

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

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

参数

参数名	描述
event: "live-streaming-error"	事件名称。
listener: typeof event_live_streaming_error	详见 live-streaming-error。

返回值

void

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

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

参数

参数名	描述
event: "live-streaming-warning"	事件名称。
listener: typeof event_live_streaming_warning	详见 live-streaming-warning。

返回值

void

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

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

参数

参数名	描述
event: "exception"	事件名称。
listener: typeof event_exception	详见 exception。

返回值

void

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

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

参数

参数名	描述
event: "is-using-cloud-proxy"	事件名称。
listener: typeof event_is_using_cloud_proxy	详见 is-using-cloud-proxy。

返回值

void

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

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

deprecated: 自 4.19.0 起废弃。

参数

参数名	描述
event: "join-fallback-to-proxy"	事件名称。
listener: typeof event_join_fallback_to_proxy	详见 join-fallback-to-proxy。

返回值

void

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

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

参数

参数名	描述
event: "published-user-list"	事件名称。
listener: typeof event_published_user_list	详见 published-user-list。

返回值

void

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

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

参数

参数名	描述
event: "content-inspect-connection-state-change"	事件名称。
listener: typeof event_content_inspect_connection_state_change	详见 content-inspect-connection-state-change。

返回值

void

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

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

参数

参数名	描述
event: "content-inspect-error"	事件名称。
listener: typeof event_content_inspect_error	详见 content-inspect-error。

返回值

void

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

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

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

参数

参数名	描述
event: "image-moderation-connection-state-change"	事件名称。
listener: typeof event_image_moderation_connection_state_change	详见 image-moderation-connection-state-change。

返回值

void

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

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

参数

参数名	描述
event: "stream-message"	事件名称。
listener: typeof event_stream_message	详见 stream-message。

返回值

void

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

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

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

参数

参数名	描述
event: string	事件名称。
listener: Function	回调函数。

返回值

void

once

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

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

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

参数

参数名	描述
event: string	指定事件的名称。
listener: Function	传入的回调函数。

返回值

void

presubscribe

presubscribe(uid: UID, mediaType: "audio"): Promise<IRemoteAudioTrack>

presubscribe(uid: UID, mediaType: "audio"): Promise<IRemoteAudioTrack>

参数

参数名	描述
uid: UID
mediaType: "audio"

返回值

Promise<IRemoteAudioTrack>

presubscribe(uid: UID, mediaType: "video"): Promise<IRemoteVideoTrack>

presubscribe(uid: UID, mediaType: "video"): Promise<IRemoteVideoTrack>

参数

参数名	描述
uid: UID
mediaType: "video"

返回值

Promise<IRemoteVideoTrack>

presubscribe(uid: UID, mediaType: "video" | "audio"): Promise<IRemoteTrack>

presubscribe(uid: UID, mediaType: "video" | "audio"): Promise<IRemoteTrack>

参数

参数名	描述
uid: UID
mediaType: "video" \| "audio"

返回值

Promise<IRemoteTrack>

removeAllListeners

removeAllListeners(event?: string): void

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

参数

参数名	描述
event: string	指定事件的名称，如果没有指定事件，则取消所有事件的所有监听。

返回值

void

renewToken

renewToken(token: string): Promise<void>

更新 token。

如果启用了 token 机制，过一段时间后 token 会失效。当收到 AgoraRTCClient.on("token-privilege-will-expire") 回调时, 调用该方法传入新的 token，否则 SDK 会无法和服务器建立连接。

参数

参数名	描述
token: string	新的 token。

返回值

Promise<void>

sendCustomReportMessage

sendCustomReportMessage(reports: EventCustomReportParams[] | EventCustomReportParams): Promise<void>

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

注意

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

参数

参数名描述

reports: EventCustomReportParams[] | EventCustomReportParams

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

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");
});

返回值

Promise<void>

setClientRole

setClientRole(role: ClientRole, options?: ClientRoleOptions): Promise<void>

设置直播场景中（mode 设为 "live"）的用户角色。

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

注意

注意事项：

通信场景（mode 设为 "rtc"）无法使用本方法，默认所有用户都是 "host" 角色。
如果在加入频道后调用该方法切换用户角色，远端会触发 AgoraRTCClient.on("user-joined") 或者 AgoraRTCClient.on("user-left") 回调。
如果已经调用了 publish，想要将用户角色切换为 "audience" 时，必须先调用 unpublish 取消发布后再调用本方法，否则会设置失败并抛出异常。

参数

参数名	描述
role: ClientRole	用户角色。
options: ClientRoleOptions	用户具体设置，包含观众延时级别。

返回值

Promise<void>

setEncryptionConfig

setEncryptionConfig(encryptionMode: EncryptionMode, secret: string, salt?: Uint8Array, encryptDataStream?: boolean): void

设置加密方案。

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

如果该方法设置错误，在发布或者订阅时会触发 AgoraRTCClient.on("crypt-error") 回调。

注意

注意事项：

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

参数

参数名	描述
encryptionMode: EncryptionMode	加密模式。
secret: string	ASCII 字符。当用户设置的密码为弱密码时，SDK 会在控制台打印警告信息，提醒用户设置强密码，即密码必须包含大写字母、小写字母、数字和特殊字符，以及长度至少 8 个字符。由于浏览器加密算法限制，密钥长度不能超过 62 个字符。声网推荐你在服务端使用 OpenSSL 生成密钥，详见媒体流加密。
salt: Uint8Array	盐值，仅当加密模式为 `"aes-128-gcm2"` 或 `"aes-256-gcm2"` 时有效。声网推荐你在服务端使用 OpenSSL 生成盐值，详见媒体流加密。
encryptDataStream: boolean	是否加密数据流。数据流加密模式需与媒体流一致。数据流加密目前仅支持 `"aes-128-gcm2"` 和 `"aes-256-gcm2"` 模式，使用其他加密模式会出现报错。 `true`: 启用数据流加密。 `false`: 不启用数据流加密。

返回值

void

setImageModeration

setImageModeration(enabled: false): Promise<void>

setImageModeration(enabled: false): Promise<void>

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

参数

参数名	描述
enabled: false	默认为 `false` 且只能设为 `false`。

返回值

Promise<void>

setImageModeration(enabled: true, config: ImageModerationConfiguration): Promise<void>

setImageModeration(enabled: true, config: ImageModerationConfiguration): Promise<void>

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

调用该方法后，SDK 会触发 image-moderation-connection-state-change 回调，并且对本地用户发送的视频进行截图、发送给第三方服务商进行审核。

注意

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

参数

参数名	描述
enabled: true	默认为 `true` 且只能设为 `true`。
config: ImageModerationConfiguration	视频审核服务的配置。详见 ImageModerationConfiguration。

返回值

Promise<void>

setLocalAccessPointsV2

setLocalAccessPointsV2(config: LocalAccessPointConfig): void

自从

4.16.0

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

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

注意

Note:

使用混合云或私有化平台时，不支持开启云代理服务，因此该方法不能与 startProxyServer 一起调用。
成功配置混合云或私有化平台后，SDK 如果直接连接 SD-RTN™ 失败，将不会自动切换到 TCP/TLS 443 通道，即不会再触发 join-fallback-to-proxy 回调。
由于 Chrome 已知问题，使用该接口过程中 Chrome 控制台可能会误报错误信息提示，开发者可以忽略。

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
 }
})

参数

参数名	描述
config: LocalAccessPointConfig	混合云或私有化平台的配置参数。详见 LocalAccessPointConfig。

返回值

void

Proxy Methods

setProxyServer

setProxyServer(proxyServer: string): void

自从

4.18.0

部署你的代理服务器。

该方法不能与 startProxyServer 同时调用，二者区别如下：

setProxyServer：自定义代理，可以用于信令传输、日志上传、事件上报等，但不能用于媒体传输。
startProxyServer：声网提供的云代理服务，可以传输媒体流、信令等，只需简单设置即可使用。详见使用云代理服务。

注意

注意事项：

该方法必须在 join 之前调用。
在使用 Firefox 浏览器时，跨运营商代理速度会比较慢。声网建议使用同运营商进行代理。如果必须使用跨运营商代理，则避免使用 Firefox 浏览器。

参数

参数名	描述
proxyServer: string	你的代理服务器域名，ASCII 字符。

返回值

void

startProxyServer

startProxyServer(mode?: number): void

开启云代理服务。

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

使用云代理服务还需要一些额外设置，详见使用云代理服务。

参数

参数名	描述
mode: number	云代理模式： `3`: UDP 协议的云代理，即 Force UDP 云代理模式。在该模式下，SDK 始终通过 UDP 协议传输数据。 `5`: TCP（加密）协议的云代理，即 Force TCP 云代理模式。在该模式下，SDK 始终通过 TLS 443 传输数据。注意事项：自 v4.15.0 起，`mode` 的默认值为 `3`。

返回值

void

stopProxyServer

stopProxyServer(): void

关闭云代理服务。

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

返回值

void

Events​

channel-media-relay-event

参数​

返回值​

channel-media-relay-state

参数​

返回值​

connection-state-change

参数​

返回值​

content-inspect-connection-state-change

参数​

返回值​

content-inspect-error

参数​

返回值​

crypt-error

返回值​

exception

参数​

返回值​

image-moderation-connection-state-change

参数​

返回值​

is-using-cloud-proxy

参数​

返回值​

join-fallback-to-proxy

参数​

返回值​

live-streaming-error

参数​

返回值​

live-streaming-warning

参数​

返回值​

media-reconnect-end

参数​

返回值​

media-reconnect-start

参数​

返回值​

network-quality

参数​

返回值​

published-user-list

参数​

返回值​

stream-fallback

参数​

返回值​

stream-message

参数​

返回值​

stream-type-changed

参数​

返回值​

token-privilege-did-expire

返回值​

token-privilege-will-expire

返回值​

user-info-updated

参数​

返回值​

user-joined

参数​

返回值​

user-left

参数​

返回值​

user-published

参数​

返回值​

user-unpublished

参数​

返回值​

volume-indicator

参数​

返回值​

Properties​

Events

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

Properties

Agora Core Methods

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

Channel Media Relay Methods

参数

返回值

返回值

参数

返回值

Dual Stream Methods

返回值

返回值

参数

返回值