Client | Agora Web SDK API 参考 v3.1.1

Client 接口提供音视频通话的核心功能，例如加入频道、发布和订阅音视频流等。

你可以通过 createClient 创建 Client 对象。一个 Client 对象代表一个本地客户端。

Hierarchy

Client

Index

Methods

addInjectStreamUrl

addInjectStreamUrl(url: string, config: InjectStreamConfig): void

输入在线媒体流

该方法通过在服务端拉取视频流并发送到频道中，将正在播出的视频输入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。详见输入在线媒体流。

Note
- 频道内同一时间只允许输入一个在线媒体流。
- 请确保已开通旁路推流的功能。
调用该方法后，SDK 会在本地触发 Client.on("streamInjectedStatus") 回调，报告输入在线媒体流的状态；成功输入媒体流后，该音视频流会出现在频道中，频道内所有用户都会收到 Client.on("stream-added") 和 Client.on("peer-online") 回调，其中 UID 为 666。
Parameters
- url: string
  添加到直播中的视频流 HTTP/HTTPS 地址，ASCII 字符，字符串长度不得超过 1024 字节。支持 RTMP，HLS，HTTP-FLV 协议传输。
  - 支持的 FLV 音频编码格式：AAC
  - 支持的 FLV 视频编码格式：H.264 (AVC)
- config: InjectStreamConfig
  
  输入的在线媒体流的设置，详见 InjectStreamConfig。
Returns void

configPublisher

configPublisher(param: object): void

配置直播旁路推流

DEPRECATED

该方法已废弃，Agora 推荐你使用以下方法设置直播推流：
该方法在加入频道前配置旁路直播推流服务。

Note

该方法需要在 Client.join 前调用。
example
示例代码
```
client.configPublisher({
  width: 360,
  height: 640,
  framerate: 30,
  bitrate: 500,
  publishUrl: "rtmp://xxx/xxx/"
});
```
Parameters
- param: object
  
  设置旁路直播的属性
  - bitrate: number
    
    设置旁路直播的输出码流的码率。默认值为 500 Kbps。正整数，取值范围为 [1,10000000]。
  - framerate: number
    
    设置旁路直播的输出码流的帧率。默认值为 15 fps。正整数，取值范围为 [1,10000]。
  - height: number
    
    设置旁路直播的输出码流的高度。默认值为 640。正整数，取值范围为 [1,10000]。
  - Optional publisherUrl?: string | null
    
    设置合图的推流地址，默认为 null, ASCII 字符，字符串长度大于 0 小于 256 字节。
  - width: number
    
    设置旁路直播的输出码流的宽度。默认值为 360。正整数，取值范围为 [1,10000]。
Returns void

disableDualStream

disableDualStream(onSuccess?: function, onFailure?: function): void

关闭双流模式

该方法关闭双流模式。
example
示例代码
```
client.disableDualStream(function() {
  console.log("Disable dual stream success!")
}, function(err) {
  console.log(err)
});
```
Parameters
- Optional onSuccess: function
  
  方法调用成功时执行的回调函数
  - - (): void
    - Returns void
- Optional onFailure: function
  方法调用失败时执行的回调函数，常见的错误如下：
  - "STILL_ON_PUBLISHING": 处于正在发布状态的状态中无法关闭大小流。
  - "DISABLE_DUALSTREAM_FAILED": 关闭大小流失败。
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

enableAudioVolumeIndicator

enableAudioVolumeIndicator(): void

启用说话者音量提示

该方法允许 SDK 定期返回正在说话的远端用户及其音量。

启用该方法后，无论频道中有没有人说话，SDK 都会每两秒触发 "volume-indicator" 回调返回音量提示。

Note

在同一台 PC 上开多个通话页面可能会导致该功能不准或失效。
example
示例代码
```
client.enableAudioVolumeIndicator(); // 每两秒触发 "volume-indicator" 回调
client.on("volume-indicator", function(evt){
    evt.attr.forEach(function(volume, index){
            console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
    });
});
```
Returns void

enableDualStream

enableDualStream(onSuccess?: function, onFailure?: function): void

开启双流模式

该方法在 Publish 端，即发送端，开启双流模式。该方法建议在加入频道（Client.join）后调用。

双流为视频大流和视频小流，其中视频大流指高分辨率、高码率的视频流，视频小流指低分辨率、低码率的视频流。

建议不要对双流进行 track 操作（包括 addTrack/removeTrack/replaceTrack），否则会导致大流和小流的表现不一致。
example
示例代码
```
client.enableDualStream(function() {
  console.log("Enable dual stream success!")
}, function(err) {
  console.log(err)
});
```
Note

该方法对以下场景无效：
- 使用自采集属性（audioSource 和 videoSource）创建的流
- 音频通话 (audio: true, video: false)
- Safari 浏览器
- 共享屏幕的场景
Parameters
- Optional onSuccess: function
  
  方法调用成功时执行的回调函数
  - - (): void
    - Returns void
- Optional onFailure: function
  方法调用失败时执行的回调函数，常见的错误如下:
  - "IOS_NOT_SUPPORT": 不支持 iOS。
  - "WECHAT_NOT_SUPPORT": 不支持微信。
  - "STILL_ON_PUBLISHING": 处于正在发布的状态中无法开启大小流。
  - "ENABLE_DUALSTREAM_FAILED": 开启大小流失败。
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

getCameras

getCameras(callback: function): void

枚举视频输入设备

该方法枚举可用的视频输入设备，比如摄像头。

调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的视频输入设备。

Parameters
- callback: function
  - - (devices: MediaDeviceInfo[]): void
    - Parameters
      - devices: MediaDeviceInfo[]
      Returns void
Returns void

getConnectionState

getConnectionState(): string

获取 SDK 与服务器的连接状态

调用该方法会返回 SDK 与服务器的连接状态。

Returns string

SDK 与服务器的连接状态，共有以下 4 种：
- DISCONNECTED：连接断开。该状态表示 SDK 处于以下任一阶段：
  - 调用 Client.join 加入频道前的初始化阶段
  - 调用 Client.leave 后的离开频道阶段
- CONNECTING：正在连接中。在调用 Client.join 或者连接中断自动重连的时候为此状态。
- CONNECTED：已连接。该状态表示用户已经加入频道，可以在频道内发布或订阅媒体流。
- DISCONNECTING：正在断开连接。在调用 Client.leave 的时候为此状态。

getLocalAudioStats

getLocalAudioStats(callback: function): void

获取本地发布流的音频统计数据

该方法获取发布流的音频统计数据，包括音频编码类型、采样率、码率等。

Note

部分统计数据需要在 stream-published 事件后进行统计，可能耗费 0-3 秒时间返回。你可以循环调用该方法获取数据。
本方法仅支持 Chrome 浏览器。

example

示例代码

setInterval(() => {
  client.getLocalAudioStats((localAudioStats) => {
    for(var uid in localAudioStats){
      console.log(`Audio CodecType from ${uid}: ${localAudioStats[uid].CodecType}`);
      console.log(`Audio MuteState from ${uid}: ${localAudioStats[uid].MuteState}`);
      console.log(`Audio RecordingLevel from ${uid}: ${localAudioStats[uid].RecordingLevel}`);
      console.log(`Audio SamplingRate from ${uid}: ${localAudioStats[uid].SamplingRate}`);
      console.log(`Audio SendBitrate from ${uid}: ${localAudioStats[uid].SendBitrate}`);
      console.log(`Audio SendLevel from ${uid}: ${localAudioStats[uid].SendLevel}`);
    }
  });
}, 1000)

Parameters

callback: function

包含本地发布流的音频统计数据的回调。
- - (stats: LocalAudioStatsMap): void
  - Parameters
    - stats: LocalAudioStatsMap
    Returns void

Returns void

getLocalVideoStats

getLocalVideoStats(callback: function): void

获取本地发布流的视频统计数据

该方法获取本地发布流的视频统计数据，包括视频分辨率、视频码率、视频帧率等。

Note

部分统计数据需要在 stream-published 事件后进行统计，可能耗费 0-3 秒时间返回。你可以循环调用该方法获取数据。
本方法仅支持 Chrome 浏览器。

example

示例代码

setInterval(() => {
  client.getLocalVideoStats((localVideoStats) => {
    for(var uid in localVideoStats){
      console.log(`Video CaptureFrameRate from ${uid}: ${localVideoStats[uid].CaptureFrameRate}`);
      console.log(`Video CaptureResolutionHeight from ${uid}: ${localVideoStats[uid].CaptureResolutionHeight}`);
      console.log(`Video CaptureResolutionWidth from ${uid}: ${localVideoStats[uid].CaptureResolutionWidth}`);
      console.log(`Video EncodeDelay from ${uid}: ${localVideoStats[uid].EncodeDelay}`);
      console.log(`Video MuteState from ${uid}: ${localVideoStats[uid].MuteState}`);
      console.log(`Video SendBitrate from ${uid}: ${localVideoStats[uid].SendBitrate}`);
      console.log(`Video SendFrameRate from ${uid}: ${localVideoStats[uid].SendFrameRate}`);
      console.log(`Video SendResolutionHeight from ${uid}: ${localVideoStats[uid].SendResolutionHeight}`);
      console.log(`Video SendResolutionWidth from ${uid}: ${localVideoStats[uid].SendResolutionWidth}`);
      console.log(`Video TargetSendBitrate from ${uid}: ${localVideoStats[uid].TargetSendBitrate}`);
      console.log(`Video TotalDuration from ${uid}: ${localVideoStats[uid].TotalDuration}`);
      console.log(`Video TotalFreezeTime from ${uid}: ${localVideoStats[uid].TotalFreezeTime}`);
    }
  });
}, 1000)

Parameters

callback: function

包含本地发布流的视频统计数据。
- - (stats: LocalVideoStatsMap): void
  - Parameters
    - stats: LocalVideoStatsMap
    Returns void

Returns void

getNetworkStats

getNetworkStats(callback: function): void

获取系统网络信息

DEPRECATED

该方法自 2.5.1 起废弃，请使用 getTransportStats 获取网络信息。

该方法可获取浏览器本地网络信息。

目前仅提供网络类型信息，详见 NetworkType。

Note

该功能仅支持 Chrome 61+ ，且无法保证兼容性，详见网络状况 API。
example
示例代码
```
client.getNetworkStats((stats) => {
    console.log(`Current network type: ${stats.NetworkType}`);
});
```
Parameters
- callback: function
  
  包含系统网络信息的回调。
  - - (stats: NetworkStats): void
    - Parameters
      - stats: NetworkStats
      Returns void
Returns void

getPlayoutDevices

getPlayoutDevices(callback: function): void

枚举音频输出设备

该方法枚举可用的音频输出设备，比如扬声器。

调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的音频输出设备。

Note

仅支持 Chrome 49 及以上。

Parameters
- callback: function
  - - (devices: MediaDeviceInfo[]): void
    - Parameters
      - devices: MediaDeviceInfo[]
      Returns void
Returns void

getRecordingDevices

getRecordingDevices(callback: function): void

枚举音频输入设备

该方法枚举可用的音频输入设备，比如麦克风。

调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的音频输入设备。

Parameters
- callback: function
  - - (devices: MediaDeviceInfo[]): void
    - Parameters
      - devices: MediaDeviceInfo[]
      Returns void
Returns void

getRemoteAudioStats

getRemoteAudioStats(callback: function): void

获取远端订阅流的音频统计数据

该方法获取订阅流的音频统计数据，包括音频解码类型、丢包率、码率等。

Note

统计数据需要在 stream-subscribed 事件后进行统计，可能耗费 0-3 秒时间返回。你可以循环调用该方法获取数据。
本方法仅支持 Chrome 浏览器。

example

示例代码

setInterval(() => {
  client.getRemoteAudioStats((remoteAudioStatsMap) => {
    for(var uid in remoteAudioStatsMap){
      console.log(`Audio CodecType from ${uid}: ${remoteAudioStatsMap[uid].CodecType}`);
      console.log(`Audio End2EndDelay from ${uid}: ${remoteAudioStatsMap[uid].End2EndDelay}`);
      console.log(`Audio MuteState from ${uid}: ${remoteAudioStatsMap[uid].MuteState}`);
      console.log(`Audio PacketLossRate from ${uid}: ${remoteAudioStatsMap[uid].PacketLossRate}`);
      console.log(`Audio RecvBitrate from ${uid}: ${remoteAudioStatsMap[uid].RecvBitrate}`);
      console.log(`Audio RecvLevel from ${uid}: ${remoteAudioStatsMap[uid].RecvLevel}`);
      console.log(`Audio TotalFreezeTime from ${uid}: ${remoteAudioStatsMap[uid].TotalFreezeTime}`);
      console.log(`Audio TotalPlayDuration from ${uid}: ${remoteAudioStatsMap[uid].TotalPlayDuration}`);
      console.log(`Audio TransportDelay from ${uid}: ${remoteAudioStatsMap[uid].TransportDelay}`);
    }
  });
}, 1000)

Parameters

callback: function

包含远端订阅流的音频统计数据的回调。
- - (stats: RemoteAudioStatsMap): void
  - Parameters
    - stats: RemoteAudioStatsMap
    Returns void

Returns void

getRemoteVideoStats

getRemoteVideoStats(callback: function): void

获取远端订阅流的视频统计数据

该方法获取远端订阅流的视频统计数据，包括丢包率、视频码率、视频帧率等。

Note

统计数据需要在 stream-subscribed 事件后进行统计，可能耗费 0-3 秒时间返回。你可以循环调用该方法获取数据。
本方法仅支持 Chrome 浏览器。

example

示例代码

setInterval(() => {
  client.getRemoteVideoStats((remoteVideoStatsMap) => {
    for(var uid in remoteVideoStatsMap){
      console.log(`Video End2EndDelay from ${uid}: ${remoteVideoStatsMap[uid].End2EndDelay}`);
      console.log(`Video MuteState from ${uid}: ${remoteVideoStatsMap[uid].MuteState}`);
      console.log(`Video PacketLossRate from ${uid}: ${remoteVideoStatsMap[uid].PacketLossRate}`);
      console.log(`Video RecvBitrate from ${uid}: ${remoteVideoStatsMap[uid].RecvBitrate}`);
      console.log(`Video RecvResolutionHeight from ${uid}: ${remoteVideoStatsMap[uid].RecvResolutionHeight}`);
      console.log(`Video RecvResolutionWidth from ${uid}: ${remoteVideoStatsMap[uid].RecvResolutionWidth}`);
      console.log(`Video RenderFrameRate from ${uid}: ${remoteVideoStatsMap[uid].RenderFrameRate}`);
      console.log(`Video RenderResolutionHeight from ${uid}: ${remoteVideoStatsMap[uid].RenderResolutionHeight}`);
      console.log(`Video RenderResolutionWidth from ${uid}: ${remoteVideoStatsMap[uid].RenderResolutionWidth}`);
      console.log(`Video TotalFreezeTime from ${uid}: ${remoteVideoStatsMap[uid].TotalFreezeTime}`);
      console.log(`Video TotalPlayDuration from ${uid}: ${remoteVideoStatsMap[uid].TotalPlayDuration}`);
      console.log(`Video TransportDelay from ${uid}: ${remoteVideoStatsMap[uid].TransportDelay}`);
    }
  });
}, 1000)

Parameters

callback: function

包含远端订阅流的视频统计数据的回调。
- - (stats: RemoteVideoStatsMap): void
  - Parameters
    - stats: RemoteVideoStatsMap
    Returns void

Returns void

getSessionStats

getSessionStats(callback: function): void

获取与会话的连接状况统计数据

该方法获取与会话的连接状况统计数据。

Note

本方法需要在加入频道成功后调用，统计数据可能耗费 0-3 秒时间返回。你可以循环调用该方法获取数据。
本方法仅支持 Chrome 浏览器。

example

示例代码

setInterval(() => {
  client.getSessionStats((stats) => {
    console.log(`Current Session Duration: ${stats.Duration}`);
    console.log(`Current Session UserCount: ${stats.UserCount}`);
    console.log(`Current Session SendBytes: ${stats.SendBytes}`);
    console.log(`Current Session RecvBytes: ${stats.RecvBytes}`);
    console.log(`Current Session SendBitrate: ${stats.SendBitrate}`);
    console.log(`Current Session RecvBitrate: ${stats.RecvBitrate}`);
  });
}, 1000)

Parameters

callback: function

包含会话状况统计数据的回调。
- - (stats: SessionStats): void
  - Parameters
    - stats: SessionStats
    Returns void

Returns void

getSystemStats

getSystemStats(callback: function): void

获取系统信息

目前仅提供系统电量信息。

Note

该功能处于实验阶段，浏览器兼容信息请参考 Battery Status API。
example
示例代码
```
client.getSystemStats((stats) => {
    console.log(`Current battery level: ${stats.BatteryLevel}`);
});
```
Parameters
- callback: function
  
  包含系统信息的回调。
  - - (stats: SystemStats): void
    - Parameters
      - stats: SystemStats
      Returns void
Returns void

getTransportStats

getTransportStats(callback: function): void

获取与网关的连接状况统计数据

该方法获取与网关的连接状况的统计数据。

Note
- 部分统计数据可能耗费 0-3 秒时间返回。你可以循环调用该方法获取数据。
- 本方法仅支持 Chrome 浏览器。
example
示例代码
```
setInterval(() => {
  client.getTransportStats((stats) => {
    console.log(`Current Transport RTT: ${stats.RTT}`);
    console.log(`Current Network Type: ${stats.networkType}`);
    console.log(`Current Transport OutgoingAvailableBandwidth: ${stats.OutgoingAvailableBandwidth}`);
  });
}, 1000)
```
Parameters
- callback: function
  
  包含与网关的连接状况的统计数据的回调。
  - - (stats: TransportStats): void
    - Parameters
      - stats: TransportStats
      Returns void
Returns void

init

init(appId: string, onSuccess?: function, onFailure?: function): void

初始化客户端对象

使用该方法初始化客户端对象。
example
示例代码
```
client.init(appId, function() {
    console.log("client initialized");
    // Join a channel
    //……
}, function(err) {
    console.log("client init failed ", err);
    // Error handling
});
```
Parameters
- appId: string
  
  传入你的项目的 App ID。ASCII 字符，字符串长度大于 0 小于 256 字节。
- Optional onSuccess: function
  
  方法调用成功时执行的回调函数
  - - (): void
    - Returns void
- Optional onFailure: function
  方法调用失败时执行的回调函数，常见的错误如下：
  - "BAD_ENVIRONMENT": 不支持当前使用的浏览器。
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

join

join(tokenOrKey: string | null, channel: string, uid: number | string | null, onSuccess?: function, onFailure?: function): void

加入 AgoraRTC 频道

该方法让用户加入 AgoraRTC 频道。

调用该方法加入频道时，本地会触发 Client.on("connected") 和 Client.on("connection-state-change") 回调；通信场景下的用户和直播场景下的主播加入频道后，远端会触发 Client.on("peer-online") 回调。
example
示例代码
```
client.join(<token>, "1024", null, function(uid) {
    console.log("client" + uid + "joined channel");
    // Create a local stream
    //……
}, function(err) {
    console.error("client join failed ", err);
    // Error handling
});
```
Parameters
- tokenOrKey: string | null
  - 安全要求不高: 将参数值设为 null。
  - 安全要求高：传入从你的服务端获得的 Token 或 Channel Key 值。详情请参考校验用户权限。
- channel: string
  标识通话频道的字符串，长度在 64 字节以内的字符串。以下为支持的字符集范围（共89个字符）:
  - 26 个小写字母 a-z
  - 26 个大写字母 A-Z
  - 10 个数字 0-9
  - 空格
  - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","
- uid: number | string | null
  指定用户的 ID。整数或字符串，ASCII 字符，需保证唯一性。如果不指定（即设为 null）或设为 0，服务器会自动分配一个，并在 onSuccess 回调方法中返回。
  
  Note
  - 一个频道内的所有用户必须使用同样类型的 uid，即必须都为整数或都为字符串。
  - 如果使用整数作为用户 ID，需为 32 位无符号整数。建议设置范围：0 到 (2³²-1)
  - 如果使用字符串作为用户 ID，长度不超过 255 个字符。
  - 使用字符串作为用户 ID 支持与 Native SDK 2.8 及以上版本互通，请确保 Native SDK 使用 User Account 加入频道。详见使用 String 型的用户名。
- Optional onSuccess: function
  
  方法调用成功时执行的回调函数，返回值代表用户身份的 uid
  - - (uid: number | string): void
    - Parameters
      - uid: number | string
      Returns void
- Optional onFailure: function
  方法调用失败时执行的回调函数，常见的错误如下：
  - "INVALID_OPERATION": 当前无法加入频道，通常是因为重复调用了 Client.join。
  - "UID_CONFLICT": 当前 Client 的 uid 和频道中其他 Client 的 uid 冲突。
  - "ERR_REPEAT_JOIN": 当前 Client 已经加入了频道。
  - "SOCKET_ERROR": 加入频道过程中和 Agora 服务器断开连接。
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

leave

leave(onSuccess?: function, onFailure?: function): void

离开 AgoraRTC 频道

该方法让用户离开 AgoraRTC 频道。

调用该方法离开频道时，本地会触发 Client.on("connection-state-change") 回调；通信场景下的用户和直播场景下的主播离开频道后，远端会触发 Client.on("peer-leave") 回调。
example
示例代码
```
client.leave(function() {
    console.log("client leaves channel");
    //……
}, function(err) {
    console.log("client leave failed ", err);
    //error handling
});
```
Parameters
- Optional onSuccess: function
  
  方法调用成功时执行的回调函数
  - - (): void
    - Returns void
- Optional onFailure: function
  方法调用失败时执行的回调函数，可能的错误如下：
  - "INVALID_OPERATION": 操作非法，可能重复调用了 leave 或者当前没有完成加入频道
  - "SOCKET_ERROR": 离开频道过程中和 Agora 服务器断开连接
  - "LEAVE_MSG_TIMEOUT": 离开频道的消息发送超时，此时 SDK 会强制断开连接离开频道
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

off

off(eventType: string, callback: any): void

取消事件绑定

该方法用于移除通过 Client.on() 绑定的事件。

example

示例代码

client.on("stream-published", function processStreamPublished(evt) {
  console.log("Stream Published");
  evt.stream.play("divId");
  client.off("stream-published", processStreamPublished);
});

Parameters

eventType: string

要移除的事件名称
callback: any

要移除的函数变量名

Returns void

on

on(event: "first-audio-frame-decode", callback: function): void
on(event: "first-video-frame-decode", callback: function): void
on(event: "stream-published", callback: function): void
on(event: "stream-unpublished", callback: function): void
on(event: "stream-added", callback: function): void
on(event: "stream-removed", callback: function): void
on(event: "stream-subscribed", callback: function): void
on(event: "peer-online", callback: function): void
on(event: "peer-leave", callback: function): void
on(event: "mute-audio", callback: function): void
on(event: "unmute-audio", callback: function): void
on(event: "mute-video", callback: function): void
on(event: "unmute-video", callback: function): void
on(event: "crypt-error", callback: function): void
on(event: "client-banned", callback: function): void
on(event: "active-speaker", callback: function): void
on(event: "volume-indicator", callback: function): void
on(event: "liveStreamingStarted", callback: function): void
on(event: "liveStreamingFailed", callback: function): void
on(event: "liveStreamingStopped", callback: function): void
on(event: "liveTranscodingUpdated", callback: function): void
on(event: "streamInjectedStatus", callback: function): void
on(event: "onTokenPrivilegeWillExpire", callback: function): void
on(event: "onTokenPrivilegeDidExpire", callback: function): void
on(event: "error", callback: function): void
on(event: "network-type-changed", callback: function): void
on(event: "recording-device-changed", callback: function): void
on(event: "playout-device-changed", callback: function): void
on(event: "camera-changed", callback: function): void
on(event: "stream-type-changed", callback: function): void
on(event: "connection-state-change", callback: function): void
on(event: "stream-reconnect-start", callback: function): void
on(event: "stream-reconnect-end", callback: function): void
on(event: "client-role-changed", callback: function): void
on(event: "reconnect", callback: function): void
on(event: "connected", callback: function): void
on(event: "network-quality", callback: function): void
on(event: "stream-fallback", callback: function): void
on(event: "stream-updated", callback: function): void
on(event: "exception", callback: function): void
on(event: "enable-local-video", callback: function): void
on(event: "disable-local-video", callback: function): void
on(event: "channel-media-relay-event", callback: function): void
on(event: "channel-media-relay-state", callback: function): void

已完成远端音频首帧解码回调。

本地订阅远端流成功并完成第一帧音频解码时会触发该回调。

Note 该回调仅支持 Chrome 浏览器。
example
示例代码
```
client.on('first-audio-frame-decode', function (evt) {
  console.log('first-audio-frame-decode');
  console.log(evt.stream);
});
```
Parameters
- event: "first-audio-frame-decode"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
已完成远端视频首帧解码回调。

本地订阅远端流成功并完成第一帧视频解码时会触发该回调。
example
示例代码
```
client.on('first-video-frame-decode', function (evt) {
  console.log('first-video-frame-decode');
  console.log(evt.stream);
});
```
Parameters
- event: "first-video-frame-decode"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用本地音视频流已发布。
example
示例代码
```
client.on("stream-published", function(evt) {
    console.log("local stream published");
    //……
});
```
Parameters
- event: "stream-published"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用本地音视频流已取消发布。
example
示例代码
```
client.on("stream-unpublished", function(evt) {
    console.log("local stream unpublished");
    //……
});
```
Parameters
- event: "stream-unpublished"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用远端音视频流已添加。

Note

如果用户加入频道时频道内已经有其他用户，也会收到该回调报告已经存在的远端流。
example
示例代码
```
client.on("stream-added", function(evt) {
    var stream = evt.stream;
    console.log("new stream added ", stream.getId());
    // Subscribe the stream.
    //……
});
```
Parameters
- event: "stream-added"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用已删除远端音视频流，即对方调用了 Client.unpublish。
example
示例代码
```
client.on("stream-removed", function(evt) {
    var stream = evt.stream;
    console.log("remote stream was removed", stream.getId());
    //……
});
```
Parameters
- event: "stream-removed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void

该回调通知应用已接收远端音视频流。

example

示例代码

client.on("stream-subscribed", function(evt) {
    var stream = evt.stream;
    console.log("new stream subscribed ", stream.getId());
    // Play the stream.
    //……
});

Parameters

event: "stream-subscribed"
callback: function
- - (evt: any): void
  - Parameters
    - evt: any
    Returns void

Returns void

该回调提示有远端用户/主播加入频道。
- 通信场景下，该回调提示有远端用户加入了频道，并返回新加入用户的 ID；如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调。
- 直播场景下，该回调提示有主播加入了频道，并返回该主播的 ID。如果在加入之前，已经有主播在频道中了，新加入的用户也会收到已有主播加入频道的回调。Agora 建议连麦主播不超过 17 人。
该回调在如下情况下会被触发：
- 通信场景的远端用户/直播场景的远端主播调用 Client.join 方法加入频道。
- 直播场景的远端观众加入频道后调用 Client.setClientRole 将用户角色改变为主播。
- 通信场景的远端用户/直播场景的远端主播网络中断后重新加入频道。
- 主播通过调用 Client.addInjectStreamUrl 方法成功导入在线媒体流。
example
示例代码
```
client.on("peer-online", function(evt) {
  console.log("peer-online", evt.uid);
});
```
Parameters
- event: "peer-online"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        uid: string
        
        新加入频道的远端用户/主播 ID。
      Returns void
Returns void
该回调通知应用有远端用户离线。

离线包括以下情况：
- 用户离开频道
  - 正常离开：用户会收到类似“再见”的消息，接收此消息后，判断对方离开频道。
  - 超时掉线：在 20 秒内，用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。Agora 建议使用信令系统来做可靠的掉线检测。
- 用户角色从主播变为观众
Note 在直播场景中，只有角色为主播的用户会触发该回调。
example
示例代码
```
client.on("peer-leave", function(evt) {
    var uid = evt.uid;
    var reason = evt.reason;
    console.log("remote user left ", uid, "reason: ", reason);
    //……
});
```
Parameters
- event: "peer-leave"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        reason: string
        
        用户离线的原因。
        
        "Quit": 用户调用了 Client.leave 主动离开频道。
        
        "ServerTimeOut": 因过长时间收不到对方数据包，超时掉线。注意：由于 SDK 使用的是不可靠通道，也有可能对方主动离开本方没收到对方离开消息而误判为超时掉线。
        
        "BecomeAudience": 用户角色从主播切换为观众。
        
        uid: string
        
        离线的用户 UID。
      Returns void
Returns void
该回调通知应用对方用户在语音通话中将自己的声音关掉。
example
示例代码
```
client.on("mute-audio", function(evt) {
  var uid = evt.uid;
  console.log("mute audio:" + uid);
  //alert("mute audio:" + uid);
});
```
Parameters
- event: "mute-audio"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用对方用户在语音通话中将自己的声音打开。
example
示例代码
```
client.on("unmute-audio", function (evt) {
  var uid = evt.uid;
  console.log("unmute audio:" + uid);
});
```
Parameters
- event: "unmute-audio"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用对方用户在视频通话中将自己的视频关掉。
example
示例代码
```
client.on("mute-video", function (evt) {
  var uid = evt.uid;
  console.log("mute video" + uid);
  //alert("mute video:" + uid);
});
```
Parameters
- event: "mute-video"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用对方用户在视频通话中将自己的视频打开。
example
示例代码
```
client.on("unmute-video", function (evt) {
  var uid = evt.uid;
  console.log("unmute video:" + uid);
});
```
Parameters
- event: "unmute-video"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调表示用户在发布或者订阅流过程中出现了加密或者解密失败，一般都是因为加密密码（setEncryptionSecret）或者加密方案（setEncryptionMode）不匹配导致的。

自从
3.0.0
example
示例代码
```
client.on("crypt-error", function (evt) {
  console.log(evt.cryptType + "error!");
});
```
Parameters
- event: "crypt-error"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知用户已经在聊天过程中被踢，或没有进入频道就被封禁。当前只有被踢的用户会收到这个回调。通常原因是该 UID 被封禁（K_UID_BANNED(14)）。
example
示例代码
```
client.on("client-banned", function (evt) {
   var uid = evt.uid;
   var attr = evt.attr;
   console.log(" user banned:" + uid + ", bantype:" + attr);
   alert(" user banned:" + uid + ", bantype:" + attr);
});
```
Parameters
- event: "client-banned"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
DEPRECATED

自 3.0.2 起废弃，用 Client.on("volume-indicator") 替代。

该回调通知应用频道内谁在说话（音量最大的用户）。
example
示例代码
```
client.on("active-speaker", function(evt) {
     var uid = evt.uid;
     console.log("update active speaker: client " + uid);
  });
```
Parameters
- event: "active-speaker"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调提示频道内正在说话的远端用户及其音量。

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

音量范围为 0 到 100 之间的整数。通常在列表中音量大于 5 的用户为持续说话的人。
example
示例代码
```
client.on("volume-indicator", function(evt){
    evt.attr.forEach(function(volume, index){
    console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
  });
});
```
Parameters
- event: "volume-indicator"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用直播推流成功。

Parameters
- event: "liveStreamingStarted"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用直播推流失败。

Parameters
- event: "liveStreamingFailed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用直播推流已停止。

Parameters
- event: "liveStreamingStopped"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用推流转码设置已被更新。

调用 setLiveTranscoding 方法更新推流转码配置时，会触发该回调并向主播报告更新信息。

Note

首次调用 setLiveTranscoding 方法时不会触发此回调。

Parameters
- event: "liveTranscodingUpdated"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用导入在线媒体流状态已更新。

Parameters
- event: "streamInjectedStatus"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
在 Token 过期前 30 秒，会收到该事件通知。

一般情况下，在收到该消息之后，应向服务端重新申请 Token，并调用 Client.renewToken 方法。
example
示例代码
```
client.on("onTokenPrivilegeWillExpire", function(){
  //进行重新申请 Token 操作后
  client.renewToken(token);
});
```
Parameters
- event: "onTokenPrivilegeWillExpire"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
在 Token 过期后，会收到该事件通知。

一般情况下，在收到该消息之后，应向服务端重新申请 Token，并调用 Client.renewToken 方法。
example
示例代码
```
client.on("onTokenPrivilegeDidExpire", function(){
  //进行重新申请 Token 操作后
  client.renewToken(token);
});
```
Parameters
- event: "onTokenPrivilegeDidExpire"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用有错误信息，需要进行处理，可能的错误如下：
- reason 为 "SOCKET_DISCONNECTED" 表示此时 SDK 和 Agora 服务器的连接因为网络原因断开了，SDK 会自动尝试重连。
- reason 为其他错误，表示在连接断开后 SDK 自动重连阶段触发的错误。
example
示例代码
```
client.on("error", function(err) {
console.log("Got error msg:", err.reason);
});
```
Parameters
- event: "error"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        reason: any
        
        type: "error"
      Returns void
Returns void
该回调通知应用网络类型发生改变。
example
示例代码
```
client.on("network-type-changed", function(evt) {
    console.log("Network Type Changed to", evt.networkType);
  });
```
Note

该功能仅支持 Chrome 61+ ，且无法保证兼容性，详见网络状况 API。
Parameters
- event: "network-type-changed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用有音频输入设备被添加或移除。
example
示例代码
```
client.on("recording-device-changed", function(evt) {
    console.log("Recording Device Changed", evt.state, evt.device);
  });
```
Parameters
- event: "recording-device-changed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用有音频输出设备被添加或移除。
example
示例代码
```
client.on("playout-device-changed", function(evt) {
    console.log("Playout Device Changed", evt.state, evt.device);
  });
```
Note

仅支持 Chrome 49 及以上
Parameters
- event: "playout-device-changed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用有摄像头被添加或移除。
example
示例代码
```
client.on("camera-changed", function(evt) {
    console.log("Camera Changed", evt.state, evt.device);
  });
```
Parameters
- event: "camera-changed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用视频流类型发生改变。

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

视频流类型 (streamType)：
- 0: 高码率、高分辨率的视频流
- 1: 低码率、低分辨率的视频流
example
示例代码
```
client.on("stream-type-changed", function(evt) {
    console.log("Stream Type Change", evt.uid, evt.streamType);
  });
```
Parameters
- event: "stream-type-changed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知应用SDK 与服务器的连接状态发生改变

SDK 与服务器的连接状态共有以下 4 种：
- DISCONNECTED：连接断开。该状态表示 SDK 处于以下任一阶段：
  - 调用 Client.join 加入频道前的初始化阶段
  - 调用 Client.leave 后的离开频道阶段
- CONNECTING：正在连接中。在调用 Client.join 或者连接中断自动重连的时候为此状态。
- CONNECTED：已连接。该状态表示用户已经加入频道，可以在频道内发布或订阅媒体流。如果因网络断开或切换而导致 SDK 与服务器的连接中断，SDK 会自动重连，此时应用会收到该回调，通知网络状态由 CONNECTED 变为 CONNECTING。
- DISCONNECTING：正在断开连接。在调用 Client.leave 的时候为此状态。
example
示例代码
```
client.on("connection-state-change", function(evt) {
  console.log(evt.prevState, evt.curState);
});
```
Parameters
- event: "connection-state-change"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        curState: string
        
        改变之后的连接状态
        
        prevState: string
        
        改变之前的连接状态
      Returns void
Returns void
该回调通知 SDK 开始尝试重新发布/订阅音视频流
example
示例代码
```
client.on("stream-reconnect-start", function(evt) {
  console.log(evt.uid);
});
```
Parameters
- event: "stream-reconnect-start"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        uid: number | string
        
        重新发布/订阅的音视频流对应的 uid
      Returns void
Returns void
该回调通知重新发布/订阅音视频流结束
example
示例代码
```
client.on('stream-reconnect-end', function(evt) {
  console.log(evt.uid, evt.success, evt.reason);
});
```
Parameters
- event: "stream-reconnect-end"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        reason: string
        
        如果 success 为 true，该参数为空字符串。
        
        如果 success 为 false，该参数显示重新发布/订阅失败的原因。可能出现的原因：
        
        REQUEST_ABORT: 由于服务器正在重连，重新发布/订阅被打断。服务器重连后会再次重新发布/订阅流，该错误可以忽略。
        
        success: boolean
        
        重新发布/订阅的结果
        
        true：成功
        
        false：失败
        
        uid: number | string
        
        重新发布/订阅的流的 uid
      Returns void
Returns void
该回调通知本地用户的角色发生改变。

直播场景下，当用户角色切换时会触发此回调，即主播切换为观众，或观众切换为主播时。
example
示例代码
```
client.on("client-role-changed", function(evt) {
  console.log("client-role-changed", evt.role);
});
```
Parameters
- event: "client-role-changed"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        role: string
        
        改变后的角色。
      Returns void
Returns void
该回调通知正在与服务器重新建立连接
example
示例代码
```
client.on("reconnect", function() {
  console.log("reconnect");
});
```
Parameters
- event: "reconnect"
- callback: function
  - - (): void
    - Returns void
Returns void
该回调通知与服务器已经成功建立连接
example
示例代码
```
client.on("connected", function() {
  console.log("connected");
});
```
Parameters
- event: "connected"
- callback: function
  - - (): void
    - Returns void
Returns void
该回调报告本地用户的上下行网络质量。

该回调每 2 秒触发，向应用报告本地用户当前的上行和下行网络质量。

Note

该功能目前处于实验阶段，网络质量评分仅供参考。
example
示例代码
```
client.on("network-quality", function(stats) {
    console.log("downlinkNetworkQuality", stats.downlinkNetworkQuality);
    console.log("uplinkNetworkQuality", stats.uplinkNetworkQuality);
});
```
Parameters
- event: "network-quality"
- callback: function
  - - (stats: NetworkQualityStats): void
    - Parameters
      - stats: NetworkQualityStats
        
        用户的网络质量，分上行网络质量和下行网络质量，详见 NetworkQualityStats。
      Returns void
Returns void
该回调表示订阅的音视频流回退为音频流或恢复为音视频流。

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

Note

视频大流（高码率、高分辨率）变为视频小流（低码率、低分辨率），或视频小流变为视频大流会触发 stream-type-changed 回调。

Parameters
- event: "stream-fallback"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        attr: number
        
        流的回退类型：
        
        1: 从音视频流回退为纯音频流
        
        0: 从音频流恢复为音视频流
        
        uid: string | number
        
        远端用户的 UID
      Returns void
Returns void
该回调表示订阅流的音视频轨道发生变化。

当远端用户对音视频流做了 addTrack 或 removeTrack 操作会触发该回调。

Parameters
- event: "stream-updated"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        stream: Stream
        
        发生音视频轨道变化的流，包含以下属性：
        
        video：布尔值，表示远端流是否有视频轨道
        
        audio：布尔值，表示远端流是否有音频轨道
      Returns void
Returns void
该回调通知应用频道内的异常事件。

异常事件不是错误，但是往往会引起通话质量问题。

发生异常事件后，如果恢复正常，也会收到该回调通知。

每一个异常事件都有对应的恢复事件，详见下表：

Note

该回调仅支持 Chrome 浏览器。
example
示例代码
```
client.on("exception", function(evt) {
  console.log(evt.code, evt.msg, evt.uid);
});
```
Parameters
- event: "exception"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        code: number
        
        事件码
        
        msg: string
        
        提示消息
        
        uid: string
        
        发生异常或恢复的用户 UID
      Returns void
Returns void
该回调表示远端 Native 用户调用了 enableLocalVideo(true) 打开视频采集。

自从
3.0.0

Parameters
- event: "enable-local-video"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        uid: string
        
        远端用户的 UID
      Returns void
Returns void
该回调表示远端 Native 用户调用了 enableLocalVideo(false) 关闭视频采集。

自从
3.0.0

Parameters
- event: "disable-local-video"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        uid: string
        
        远端用户的 UID
      Returns void
Returns void
跨频道媒体流转发事件回调。

自从
3.0.0

该回调报告跨频道媒体流转发过程中发生的事件。

Parameters
- event: "channel-media-relay-event"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        code: number
        
        事件码
        
        0: 网络中断导致用户与服务器连接断开。
        
        1: 用户与服务器建立连接。
        
        2: 用户已加入源频道。
        
        3: 用户已加入目标频道。
        
        4: SDK 开始向目标频道发送数据包。
        
        5: 服务器收到了目标频道发送的视频流。
        
        6: 服务器收到了目标频道发送的音频流。
        
        7: 目标频道已更新。
      Returns void
Returns void
跨频道媒体流转发状态回调。

自从
3.0.0

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

Parameters
- event: "channel-media-relay-state"
- callback: function
  - - (evt: object): void
    - Parameters
      - evt: object
        
        code: number
        
        跨频道媒体流转发出错的错误码：
        
        0: 一切正常。
        
        1: 服务器回应出错。
        
        2: 服务器无回应。
        
        3: SDK 无法获取服务，可能是因为服务器资源有限导致。
        
        4: 发起跨频道转发媒体流请求失败。
        
        5: 接受跨频道转发媒体流请求失败。
        
        6: 服务器接收跨频道转发媒体流失败。
        
        7: 服务器发送跨频道转发媒体流失败。
        
        8: SDK 因网络质量不佳与服务器断开，并且重连失败时抛出这个错。此时 SDK 会重置跨频道媒体流转发的相关状态，可以尝试调用 startChannelMediaRelay 重新进行跨频道媒体流转发。
        
        9: 服务器内部出错。
        
        10: 源频道的 Token 已过期。
        
        11: 目标频道的 Token 已过期。
        
        12: 已经开始跨频道媒体流转发。该错误一般是因为重复调用 startChannelMediaRelay，或者在调用 stopChannelMediaRelay 未成功时就调用了 startChannelMediaRelay。
        
        13: 尚未开始跨频道媒体流转发。该错误一般是因为调用 startChannelMediaRelay 还未成功时就调用了 updateChannelMediaRelay。
        
        state: number
        
        状态码
        
        0: SDK 正在初始化。
        
        1: SDK 尝试跨频道。
        
        2: 源频道主播成功加入目标频道。
        
        3: 发生异常，详见 code 中提示的错误信息。发生异常后，SDK 会重置跨频道媒体流转发的相关状态，你需要调用 startChannelMediaRelay 重新开始跨频道媒体流转发。
      Returns void
Returns void

publish

publish(stream: Stream, onFailure?: function): void

发布本地音视频流

该方法将本地音视频流发布至 SD-RTN。

发布音视频流之后，本地会触发 Client.on("stream-published") 回调；远端会触发 Client.on("stream-added") 回调。

Note

在直播场景里，调用该方法的用户即为主播。
example
示例代码
```
client.publish(stream, function(err) {
    console.log(err);
    //……
});
```
Parameters
- stream: Stream
  
  本地音视频流对象
- Optional onFailure: function
  方法调用失败时执行的回调函数, 可能的错误如下：
  - "STREAM_ALREADY_PUBLISHED": 该 stream 已经发布。
  - "INVALID_LOCAL_STREAM": 传入的 stream 格式非法。
  - "INVALID_OPERATION": 当前不在频道中，可能是没有加入频道或者是网络波动导致暂时断开连接。
  - "PUBLISH_STREAM_FAILED": 发布失败，一般是在发布过程中连接丢失。
  - "PEERCONNECTION_FAILED": 媒体传输通道建立失败。
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

removeInjectStreamUrl

removeInjectStreamUrl(url: string): void

删除输入的在线媒体流

该方法从直播中删除通过 addInjectStreamUrl 输入的在线媒体流。删除后频道內所有用户都会收到 Client.on("peer-leave") 和 Client.on("stream-removed") 回调。

Parameters
- url: string
  
  待删除的外部视频流 HTTP/HTTPS 地址。ASCII 字符，字符串长度不得超过 1024 字节。
Returns void

renewChannelKey

renewChannelKey(key: string, onSuccess?: function, onFailure?: function): void

更新 Channel Key

该方法更新 Channel Key。如果启用了 Channel Key 机制，过一段时间后密钥会失效。当 onFailure 回调报告 DYNAMIC_KEY_TIMEOUT 时，调用该 API 以更新 Channel Key，否则 SDK 会无法和服务器建立连接。

Parameters
- key: string
  
  指定新的 Channel Key
- Optional onSuccess: function
  
  方法调用成功时执行的回调函数
  - - (): void
    - Returns void
- Optional onFailure: function
  方法调用失败时执行的回调函数，常见的错误如下：
  - "INVALID_OPERATION": 只有在加入频道之后才能调用该方法。
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

renewToken

renewToken(token: string): void

更新 Token

该方法更新 Token。如果启用了 Token 机制，过一段时间后密钥会失效。当收到 onTokenPrivilegeWillExpire 或 onTokenPrivilegeDidExpire 消息时，调用该 API 以更新 Token，否则 SDK 会无法和服务器建立连接。

Parameters
- token: string
  
  指定新的 Token
Returns void

setClientRole

setClientRole(role: "audience" | "host", callback?: function): void

设置用户角色

本方法仅适用于直播场景。

直播场景下，可以调用本方法设置用户角色。

在加入频道前，用户可以通过本方法设置自己的角色。

在加入频道后，用户可以通过本方法切换角色：
- 用户在调用 publish 的时候会自动切换成 host 角色，调用 unpublish 的时候会自动切换为 audience 角色。
- 如果已经调用了 publish，调用本方法将用户角色设置为 audience，会自动进行 unpublish。
如果你在加入频道后调用该方法切换用户角色，切换成功后，本地会触发 Client.on("client-role-changed") 回调；远端会触发 Client.on("peer-online") 或者 Client.on("peer-leave") 回调。

Note

通信场景（mode 设置为 rtc）无法使用本方法，默认所有用户都是 host 角色。
example
示例代码
```
client.setClientRole("host", function(e) {
  if (!e) {
    console.log("setHost success");
  } else {
    console.log("setHost error", e);
  }
});
```
Parameters
- role: "audience" | "host"
  用户角色：
  - "audience"：观众，默认角色，只能接收音视频流，无法发布。
  - "host"：主播，可以发布和接收音视频流。
- Optional callback: function
  - - (err?: string | null): void
    - Parameters
      - Optional err: string | null
      Returns void
Returns void

setEncryptionMode

setEncryptionMode(encryptionMode: "aes-128-xts" | "aes-256-xts" | "aes-128-ecb"): void

设置 AES 加密方案

该方法和 setEncryptionSecret 搭配使用，可以开启内置加密功能，需要在加入频道前调用。

同一频道内的所有用户必须设置相同的加密方案和 secret 才能进行通话。

Note
- setEncryptionSecret 和 setEncryptionMode 没有调用顺序要求，但是必须都在加入频道前调用，否则加密不生效。
- 如果该方法设置错误，在发布或者订阅流时会触发 Client.on("crypt-error") 回调。
- 请勿在转码推流场景中使用加密功能。
example

client.setEncryptionMode(encryptionMode);
Parameters
- encryptionMode: "aes-128-xts" | "aes-256-xts" | "aes-128-ecb"
  加密方案，包含以下几种：
  - aes-128-xts: 设置 AES128XTS 加密方案。
  - aes-256-xts: 设置 AES256XTS 加密方案。
  - aes-128-ecb: 设置 AES128ECB 加密方案。
Returns void

setEncryptionSecret

setEncryptionSecret(password: string): void

设置 AES 加密密码

该方法和 setEncryptionMode 搭配使用，可以开启内置加密功能，需要在加入频道前调用。

同一频道内的所有用户应设置相同的 secret。如果未指定 secret，则无法激活加密功能。

Note
- setEncryptionSecret 和 setEncryptionMode 没有调用顺序要求，但是必须都在加入频道前调用，否则加密不生效。
- 请勿在转码推流场景中使用加密功能。
- 如果该方法设置错误，在发布或者订阅流时会触发 Client.on("crypt-error") 回调。
example

client.setEncryptionSecret(password)
Parameters
- password: string
  
  加密密码。ASCII 字符，字符串长度大于 0 小于 256 字节。
Returns void

setLiveTranscoding

setLiveTranscoding(coding: LiveTranscoding): void

设置直播推流转码

调用该方法更新转码设置后本地会触发 Client.on("liveTranscodingUpdated") 回调。

Note
- 使用前请确保已开通旁路推流的功能。
- 首次调用该方法不会触发 Client.on("liveTranscodingUpdated") 回调。
- 该方法需要在 createStream 后调用。详见推流到 CDN。
Parameters
- coding: LiveTranscoding
  
  直播转码的设置，详见 LiveTranscoding。
Returns void

setLowStreamParameter

setLowStreamParameter(param: object): void

设置小流视频属性

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

如果你不调用该方法，SDK 会使用默认的小流视频属性：分辨率（宽 × 高）160 × 120，码率 50 Kbps，帧率 15 fps。

Note
- 视频小流和视频大流的宽高比会自动保持一致。如果为小流设置的分辨率宽高比和大流不同，SDK 会自动调整小流分辨率的高，以保持大小流的宽高比相同。
- 由于不同的浏览器对于视频参数设置有不同的限制，通过该接口设置的视频参数不一定都会生效。
  - Firefox 浏览器上设置帧率不生效，浏览器会把帧率固定在 30 fps。
  - 部分浏览器设置视频分辨率可能不生效，这种情况下浏览器会自动调整分辨率。
- 计费按照实际分辨率计算。
- 该方法必须在 Client.join 之后以及 Client.publish 之前调用。
Parameters
- param: object
  
  小流的视频属性。
  - Optional bitrate?: number
    
    小流视频帧的码率。
    
    正整数，取值范围为 [1,10000000]，单位为 Kbps。默认值 50。
  - Optional framerate?: number
    
    小流视频帧的帧率。
    
    正整数，取值范围为 [1,10000]，单位为 fps。默认值 15。
  - Optional height?: number
    
    小流视频帧的高度。正整数，取值范围为 [1,10000]。
    
    width 和 height 参数互相绑定，只有两个都填才有效，否则视为缺省，SDK 会自动设为 120。
  - Optional width?: number
    
    小流视频帧的宽度。正整数，取值范围为 [1,10000]。
    
    width 和 height 参数互相绑定，只有两个都填才有效，否则视为缺省，SDK 会自动设为 160。
Returns void

setProxyServer

setProxyServer(proxyServer: string): void

部署代理服务器

Agora Web SDK 还提供 startProxyServer 方法支持云代理服务，详见使用云代理。

Note
- 请在 Client.join 之前调用本方法。
- 在使用 Firefox 浏览器时，跨运营商代理速度会比较慢。Agora 建议使用同运营商进行代理。如果必须使用跨运营商代理，则避免使用 Firefox 浏览器。
example

client.setProxyServer(proxyServer);
Parameters
- proxyServer: string
  
  你的代理服务器域名。ASCII 字符，字符串长度大于 0 小于 256 字节。详见 ClientConfig.proxyServer。
Returns void

setRemoteVideoStreamType

setRemoteVideoStreamType(stream: Stream, streamType: 0 | 1): void

设置视频大小流

如果发送端选择发送视频双流 (大流或小流)，该方法可以在订阅端选择接收大流还是小流。如果不设置，订阅端默认接收大流。

example

示例代码

switchStream = function (){
  if (highOrLow === 0) {
    highOrLow = 1
    console.log("Set to low");
  }
  else {
    highOrLow = 0
    console.log("Set to high");
  }

  client.setRemoteVideoStreamType(stream, highOrLow);
}

Note:

某些浏览器对双流模式不完全适配。目前发现的适配问题有：

浏览器	可能出现的问题
macOS Safari	大小流帧率、分辨率一致
Firefox	小流帧率固定为 30 fps
iOS Safari	Safari 11 及以上当前不支持大小流切换

Parameters

stream: Stream

远端视频流对象
streamType: 0 | 1
设置远端视频流大小。视频流类型如下：
- 0: 高分辨率、高码率的视频大流
- 1: 低分辨率、低码率的视频小流

Returns void

setStreamFallbackOption

setStreamFallbackOption(stream: Stream, fallbackType: 0 | 1 | 2): void

设置音视频流回退策略

该接口用于设置订阅端在弱网情况下音视频流的回退策略。网络不理想的情况下，为保证通话质量，可以选择自动订阅视频小流（低分辨率、低码率视频流）或者仅订阅音频流。

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

Note

该方法只可在发送端通过 enableDualStream 开启双流模式的情况下使用。
example
示例代码
```
// 发送端, 发布大流之后
client.enableDualStream();

// 接收端，订阅成功后设置回退策略为2
client.setStreamFallbackOption(remoteStream, 2);
```
Parameters
- stream: Stream
  
  远端音视频流对象
- fallbackType: 0 | 1 | 2
  回退选项：
  - 0: 关闭回退策略，弱网时不对音视频流作回退处理。
  - 1: （默认）网络条件较差的情况下，SDK 将订阅视频小流。
  - 2: 网络较弱时，先尝试订阅视频小流，如果网络环境无法显示视频，则再回退到只订阅音频流。
Returns void

setTurnServer

setTurnServer(turnServer: TurnServer[]): void

部署 TURN 服务器

Agora Web SDK 还提供 startProxyServer 方法支持云代理服务，详见使用云代理。

Note

请在 Client.join 之前调用本方法。

example

client.setTurnServer(config);

Parameters
- turnServer: TurnServer[]
  
  由 TurnServer 对象组成的数组，支持传入多组 TURN 服务器设置。
Returns void

startChannelMediaRelay

startChannelMediaRelay(config: ChannelMediaRelayConfiguration, callback: function): void

开始跨频道媒体流转发

自从
3.0.0

该方法可用于实现跨频道媒体流转发。

调用该方法后，SDK 会触发以下回调：
- Client.on("channel-media-relay-state")，报告当前的跨频道媒体流转发状态和错误码。
  - 如果转发成功，该回调中 state 为 2，code 为 0。
  - 如果转发出现异常，该回调中 state 为 3，code 为错误码。你可以尝试再次调用本方法。
- Client.on("channel-media-relay-event")，报告跨频道媒体流转发相关的事件。
  - 如果转发成功，该回调中 code 为 4，表示 SDK 开始向目标频道发送数据包。
Note
- 跨频道媒体流转发功能需要提交工单联系技术支持开通。
- 该功能不支持 String 型 UID。
- 请在成功加入频道后调用该方法。
- 直播场景下，只有主播可以调用该方法。
- 成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
example
示例代码
```
client.startChannelMediaRelay(channelMediaConfig, function(e) {
  if(e) {
    utils.notification(`startChannelMediaRelay failed: ${JSON.stringify(e)}`);
  } else {
    utils.notification(`startChannelMediaRelay success`);
  }
});
```
Parameters
- config: ChannelMediaRelayConfiguration
  
  跨频道媒体流转发参数配置，详见 ChannelMediaRelayConfiguration。
- callback: function
  媒体流转发是否成功的回调。
  - null：媒体流转发成功。
  - 如果失败，会通过 ChannelMediaError 提供错误信息。
  - - (err: null | ChannelMediaError): void
    - Parameters
      - err: null | ChannelMediaError
      Returns void
Returns void

startLiveStreaming

startLiveStreaming(url: string, enableTranscoding?: boolean): void

新建直播流

该方法新建直播流。详见推流到 CDN。

推流开始后本地会触发 Client.on("liveStreamingStarted") 回调。如果推流失败会触发 Client.on("liveStreamingFailed") 回调。

Note
- 该方法只适用于直播场景，且只有角色为主播的用户才能使用该功能。
- 请确保在收到 publish 成功的回调之后调用本方法。
- 不支持同时推送多个流。如需推送多个流，请确认前一个流推送成功后再推送下一个流。
example
示例代码
```
client.setLiveTranscoding(<coding>);
client.startLiveStreaming(<url>, true)
```
Parameters
- url: string
  
  （必选项）直播推流的地址。 ASCII 字符，字符串长度不得超过 1024 字节。
- Optional enableTranscoding: boolean
  
  (非必选项) 是否启用直播转码。如果设为 true（启用转码），需先调用 setLiveTranscoding。
Returns void

startProxyServer

startProxyServer(type?: number): void

开启云代理服务

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

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

Parameters
- Optional type: number
Returns void

stopChannelMediaRelay

stopChannelMediaRelay(callback: function): void

停止跨频道媒体流转发

自从
3.0.0

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

调用该方法会触发 Client.on("channel-media-relay-state") 回调。
- 如果成功停止跨频道媒体流转发，该回调中 state 为 0。
- 如果未成功停止跨频道媒体流转发，该回调中 state 为 3，code 错误码可能为 2 或 8，一般是在网络较差的情况下，退出的消息发送不成功导致的。你可以调用 Client.leave 离开频道来停止跨频道媒体流转发。
example
示例代码
```
stopChannelMediaRelay: function() {
  client.stopChannelMediaRelay(function(e) {
    if(e) {
      utils.notification(`stopChannelMediaRelay failed: ${JSON.stringify(e)}`);
    } else {
      utils.notification(`stopChannelMediaRelay success`);
    }
  });
}
```
Parameters
- callback: function
  停止跨频道媒体流转发是否成功的回调。
  - null：停止跨频道媒体流转发成功。
  - 如果失败，会通过 ChannelMediaError 提供错误信息。
  - - (err: null | ChannelMediaError): void
    - Parameters
      - err: null | ChannelMediaError
      Returns void
Returns void

stopLiveStreaming

stopLiveStreaming(url: string): void

删除直播流

该方法停止并删除直播流。推流停止后本地会触发 Client.on("liveStreamingStopped") 回调。

Parameters
- url: string
  
  直播推流的地址。ASCII 字符，字符串长度不得超过 1024 字节。
Returns void

stopProxyServer

stopProxyServer(): void

关闭云代理服务

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

该方法会关闭所有代理服务，包括通过 setProxyServer 和 setTurnServer 设置的代理服务。

Returns void

subscribe(stream: Stream, options?: object, onFailure?: function): void

订阅远端音视频流

该方法从服务器端接收远端音视频流。

订阅远端音视频流之后，本地会触发 Client.on("stream-subscribed") 回调。如果订阅流中包含音频，还会触发 Client.on("first-audio-frame-decode") 回调；如果订阅流中包含视频，还会触发 Client.on("first-video-frame-decode") 回调。
example
示例代码
```
client.subscribe(stream, function(err) {
    console.error("stream subscribe failed", err);
    //……
});
```
进阶用法

该方法可以对同一个远端流多次调用，在接收音频和/或视频之间灵活切换。
example
示例代码
```
// 一开始订阅远端流，并且选择仅接收视频数据。
client.subscribe(stream, {video: true, audio: false});

// 一段时间后，切换到仅接收音频数据。
client.subscribe(stream, {video: false, audio: true});
```
Parameters
- stream: Stream
  
  远端音视频流对象
- Optional options: object
  设置是否接收视频或音频。
  
  Note
  - video 和 audio 不可同时设为 false。如果想取消订阅流，请调用 Client.unsubscribe 方法。
  - Safari 不支持单独订阅音频或视频。在 Safari 中请将 options 设为 null，否则会收到SAFARI_NOT_SUPPORTED_FOR_TRACK_SUBSCRIPTION错误。
  - Optional audio?: boolean
    设置是否接收音频数据。
    
    true：（默认）接收音频数据。
    
    false：不接收音频数据。
  - Optional video?: boolean
    设置是否接收视频数据。
    
    true：（默认）接收视频数据。
    
    false：不接收视频数据。
- Optional onFailure: function
  方法调用失败时执行的回调函数，以下列举一些常见的错误：
  - "SAFARI_NOT_SUPPORTED_FOR_TRACK_SUBSCRIPTION": Safari 目前不支持订阅单个 Track。
  - "INVALID_OPERATION": 当前不在频道中，可能是没有加入频道或者是网络波动导致暂时断开连接。
  - "SUBSCRIBE_STREAM_FAILED": 订阅失败，一般是在订阅过程中连接断开。
  - "PEERCONNECTION_FAILED": 媒体传输通道建立失败。
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

unpublish

unpublish(stream: Stream, onFailure?: function): void

取消发布本地音视频流

该方法取消发布本地音视频流。

取消发布音视频流之后，本地会触发 Client.on("stream-unpublished") 回调，远端会触发 Client.on("stream-removed") 回调。

Note

直播场景中，主播取消发布流之后用户角色会自动切换为观众，远端还会触发 Client.on("peer-leave") 回调。
example
示例代码
```
client.unpublish(stream, function(err) {
    console.log(err);
    //……
});
```
Parameters
- stream: Stream
  
  本地音视频流对象
- Optional onFailure: function
  方法调用失败时执行的回调函数，以下列举一些可能的错误：
  - "STREAM_NOT_YET_PUBLISHED": 指定的 stream 还没有发布。
  - "INVALID_LOCAL_STREAM": 传入的 stream 格式非法。
  - "INVALID_OPERATION": 当前不在频道中，可能是没有加入频道或者是网络波动导致暂时断开连接。
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

unsubscribe

unsubscribe(stream: Stream, onFailure?: function): void

取消订阅远端音视频流

该方法取消接收远端音视频流。
example
示例代码
```
client.unsubscribe(stream, function(err) {
    console.log(err);
    //……
});
```
Parameters
- stream: Stream
  
  远端音视频流对象
- Optional onFailure: function
  方法调用失败时执行的回调函数，常见的错误如下：
  - "INVALID_REMOTE_STREAM": 传入的 stream 对象格式非法。
  - "INVALID_OPERATION": 当前不在频道中，可能是没有加入或者是网络波动导致暂时断开连接。
  - "NO_SUCH_REMOTE_STREAM": 没有找到要取消订阅的远端流。
  - "UNSUBSCRIBE_STREAM_FAILED": 取消订阅失败，一般是取消订阅时连接断开。
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

updateChannelMediaRelay

updateChannelMediaRelay(config: ChannelMediaRelayConfiguration, callback: function): void

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

自从
3.0.0

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

调用该方法后，SDK 会触发 Client.on("channel-media-relay-event") 回调。
- 如果更新成功，回调中 code 为 7。
- 如果更新失败，回调中 code 为 8，同时还会触发 Client.on("channel-media-relay-state") 回调，其中 state 为 3。出错后跨频道媒体流转发状态会被重置，你需要调用 startChannelMediaRelay 重新开始跨频道媒体流转发。
Note
- 请在 startChannelMediaRelay 后调用该方法，更新媒体流转发的频道。
- 跨频道媒体流转发最多支持 4 个目标频道。
example
示例代码
```
client.updateChannelMediaRelay(channelMediaConfig, function(e) {
  if(e) {
    utils.notification(`updateChannelMediaRelay failed: ${JSON.stringify(e)}`);
  } else {
    utils.notification(`updateChannelMediaRelay success`);
  }
});
```
Parameters
- config: ChannelMediaRelayConfiguration
  
  跨频道媒体流转发参数配置，详见 ChannelMediaRelayConfiguration。
- callback: function
  更新目标频道是否成功的回调。
  - null：更新目标频道成功。
  - 如果失败，会通过 ChannelMediaError 提供错误信息。
  - - (err: null | ChannelMediaError): void
    - Parameters
      - err: null | ChannelMediaError
      Returns void
Returns void

Agora Web API Reference

Hierarchy

Index

Methods

Methods

addInjectStreamUrl

Parameters

url: string

config: InjectStreamConfig

Returns void

configPublisher

Parameters

param: object

bitrate: number

framerate: number

height: number

Optional publisherUrl?: string | null

width: number

Returns void

disableDualStream

Parameters

Optional onSuccess: function

Returns void

Optional onFailure: function

Parameters

err: string

Returns void

Returns void

enableAudioVolumeIndicator

Returns void

enableDualStream

Parameters

Optional onSuccess: function

Returns void

Optional onFailure: function

Parameters

err: string

Returns void

Returns void

getCameras

Parameters

callback: function

Parameters

devices: MediaDeviceInfo[]

Returns void

Returns void

getConnectionState

Returns string

getLocalAudioStats

Parameters

callback: function

Parameters

stats: LocalAudioStatsMap

Returns void

Returns void

getLocalVideoStats

Parameters

callback: function

Parameters

stats: LocalVideoStatsMap

Returns void

Returns void

getNetworkStats

Parameters

callback: function

Parameters

stats: NetworkStats

Returns void

Returns void

getPlayoutDevices

Parameters

callback: function

Parameters

devices: MediaDeviceInfo[]

Returns void

Returns void

getRecordingDevices

Parameters

callback: function

Parameters