Client | Agora Web SDK API Reference v2.4.1

通过 createClient 创建的客户端对象。

客户端对象提供 AgoraRTC 的核心功能。

Hierarchy

Client

Methods

configPublisher

configPublisher(width: number, height: number, framerate: number, bitrate: number, publisherUrl: string): void

配置直播旁路推流

DEPRECATED

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

Note:
- 如需使用直播 1.0 的功能，在 Client.join 前调用 configPublisher 方法即可。
- 如需使用直播 2.0 的功能，在 createStream 后调用 startLiveStreaming 和 setLiveTranscoding 方法即可。详见进阶：推流到 CDN。
example
示例代码
```
client.configPublisher({
  width: 360,
  height: 640,
  framerate: 30,
  bitrate: 500,
  publishUrl: "rtmp://xxx/xxx/"
});
```
Parameters
- width: number
  
  设置旁路直播的输出码流的宽度。默认值为 360
- height: number
  
  设置旁路直播的输出码流的高度。默认值为 640
- framerate: number
  
  设置旁路直播的输出码流的帧率。默认值为 15 fps
- bitrate: number
  
  设置旁路直播的输出码流的码率。默认值为 500 Kbps
- publisherUrl: string
  
  设置合图的推流地址，默认为 null
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
- onSuccess: function
  
  方法调用成功时执行的回调函数
  - - (): void
    - Returns void
- onFailure: function
  
  方法调用失败时执行的回调函数
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

enableAudioVolumeIndicator

enableAudioVolumeIndicator(): void

启用说话者音量提示

该方法允许 SDK 定期向 App 反馈当前谁在说话以及说话者的音量。

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

Note:
- 建议同时开启 DTX，详见 StreamSpec.audioProcessing。
- 在同一台 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 端，即推流端，开启双流模式。

双流为视频大流和视频小流，其中视频大流指高分辨率、高码率的视频流，视频小流指低分辨率、低码率的视频流。
example
示例代码
```
client.enableDualStream(function() {
  console.log("Enable dual stream success!")
}, function(err) {
  console,log(err)
})
```
Note:

该方法对以下场景无效：
- 音频通话 (audio: true, video: false)
- Safari 浏览器
- 共享屏幕的场景
Parameters
- onSuccess: function
  
  方法调用成功时执行的回调函数
  - - (): void
    - Returns void
- onFailure: function
  
  方法调用失败时执行的回调函数
  - - (err: any): void
    - Parameters
      - err: any
      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。关于如何获取 App ID，请参考创建 Agora 账号并获取 App ID。
- onSuccess: function
  
  方法调用成功时执行的回调函数
  - - (): void
    - Returns void
- onFailure: function
  
  方法调用失败时执行的回调函数
  - - (err: string): void
    - Parameters
      - err: string
      Returns void
Returns void

join

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

加入 AgoraRTC 频道

该方法让用户加入 AgoraRTC 频道。
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。
  - 安全要求高：传入从你的服务端获得的 Token 或 Channel Key 值。详情请参考密钥说明。
- channel: string
  
  标识通话频道的字符串，长度在 64 字节以内的字符串。以下为支持的字符集范围（共89个字符）: a-z,A-Z,0-9,space,! #$%&,()+, -,:;<=.#$%&,()+,-,:;<=.,>?@[],^_,{|},~
- uid: number
  
  指定用户的 ID。整数，需保证唯一性。如果不指定（即设为 null），服务器会自动分配一个，并在 onSuccess 回调方法中返回。
- onSuccess: function
  
  方法调用成功时执行的回调函数，返回值代表用户身份的 uid
  - - (uid: number): void
    - Parameters
      - uid: number
      Returns void
- onFailure: function
  
  方法调用失败时执行的回调函数
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

leave

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

离开 AgoraRTC 频道

该方法让用户离开 AgoraRTC 频道。
example
示例代码
```
client.leave(function() {
    console.log("client leaves channel");
    //……
}, function(err) {
    console.log("client leave failed ", err);
    //error handling
});
```
Parameters
- onSuccess: function
  
  方法调用成功时执行的回调函数
  - - (): void
    - Returns void
- onFailure: function
  
  方法调用失败时执行的回调函数
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

on

on(event: "stream-published", 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-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: "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: "lliveStreamingStopped", callback: function): void
on(event: "liveTranscodingUpdated", callback: function): void
on(event: "onTokenPrivilegeWillExpire", callback: function): void
on(event: "onTokenPrivilegeDidExpire", callback: function): void
on(event: "error", callback: function): void

该回调通知 App 本地音视频流已发布。
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

该回调通知 App 远程音视频流已添加。

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

该回调通知 App 已删除远程音视频流，即对方调用了 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

该回调通知 App 已接收远程音视频流。

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

该回调通知 App 对方用户已离开频道，即对方调用了 Client.leave。
example
示例代码
```
client.on("peer-leave", function(evt) {
    var uid = evt.uid;
    console.log("remote user left ", uid);
    //……
});
```
Parameters
- event: "peer-leave"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知 App 对方用户在语音通话中将自己的声音关掉。
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
该回调通知 App 对方用户在语音通话中将自己的声音打开。
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
该回调通知 App 对方用户在视频通话中将自己的视频关掉。
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
该回调通知 App 对方用户在视频通话中将自己的视频打开。
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
该回调通知用户已经在聊天过程中被踢，或没有进入频道就被封禁。当前只有被踢的用户会收到这个回调。
example
示例代码
```
client.on("client-banned", function (evt) {
   var uid = evt.uid;
   var attr = evt.attr;
   console.log(" user banned:" + uid + ", banntype:" + attr);
   alert(" user banned:" + uid + ", banntype:" + attr);
});
```
Parameters
- event: "client-banned"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该回调通知 App 频道内谁在说话（音量最大的用户）。
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
该回调通知 App 直播推流成功。

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

Parameters
- event: "liveStreamingFailed"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该方法通知 App 直播推流已停止。

Parameters
- event: "lliveStreamingStopped"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void
该方法通知 App 主播转码已更新。

Parameters
- event: "liveTranscodingUpdated"
- 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
该回调通知 App 有出错信息，需要进行处理。
example
示例代码
```
client.on("error", function(err) {
    console.log("Got error msg:", err.reason);
  });
```
具体错误及原因详见错误代码和警告代码。
Parameters
- event: "error"
- callback: function
  - - (evt: any): void
    - Parameters
      - evt: any
      Returns void
Returns void

publish

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

发布本地音视频流

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

Note:

在直播场景里，调用该方法的用户即为主播。
example
示例代码
```
client.publish(stream, function(err) {
    console.log(err);
    //……
})
```
Parameters
- stream: Stream
  
  本地音视频流对象
- onFailure: function
  
  方法调用失败时执行的回调函数
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
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
- onSuccess: function
  
  方法调用成功时执行的回调函数
  - - (): void
    - Returns void
- onFailure: function
  
  方法调用失败时执行的回调函数
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

renewToken

renewToken(token: string): void

更新 Token

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

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

setEncryptionMode

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

设置 AES 加密方案

Note:

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

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 加密密码

Note:

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

example

client.setEncryptionSecret(password)

Parameters
- password: string
  
  加密密码
Returns void

setLiveTranscoding

setLiveTranscoding(coding: LiveTranscoding): void

设置直播转码

该方法设置直播转码。

Parameters
- coding: LiveTranscoding
  
  直播转码的设置，详见 LiveTranscoding。
Returns void

setLowStreamParameter

setLowStreamParameter(param: object): void

设置小流视频参数

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

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

Note:
- 由于不同的浏览器对于视频参数设置有不同的限制，通过该接口设置的视频参数不一定都会生效。目前发现的未能充分适配的浏览器有 Firefox 浏览器，对其设置帧率不生效，浏览器本身会把帧率固定在 30 fps 。
- 由于设备和浏览器的限制，部分浏览器设置视频分辨率可能不会生效，这种情况下浏览器会自动调整分辨率，计费也将按照实际分辨率计算。
- 该方法必须在 Client.join 之后调用才能生效。
- 屏幕共享只支持大流模式。
Parameters
- param: object
  
  设置小流的视频属性。
  - birate: number
    
    小流视频帧的码率，单位为 Kbps。如果不填，SDK 会自动适配。
  - framerate: number
    
    小流视频帧的帧率，单位为 fps。如果不填，SDK 会自动适配。
  - height: number
    
    小流视频帧的高度。width 和 height 参数互相绑定，只有两个都填才有效，否则视为缺省，SDK 会自动适配。
  - width: number
    
    小流视频帧的宽度。width 和 height 参数互相绑定，只有两个都填才有效，否则视为缺省，SDK 会自动适配。
Returns void

setProxyServer

setProxyServer(proxyServer: string): void

部署 Nginx 服务器

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

client.setProxyServer(proxyServer);
Parameters
- proxyServer: string
  
  你的 Nginx 服务器域名
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, hightOrLow);
}

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

设置音视频流回退策略

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

Note:

该方法只可在发送端通过 enableDualStream 开启双流模式的情况下使用。

Parameters
- stream: Stream
  
  远端音视频流对象
- fallbackType: 0 | 1 | 2
  回退选项：
  - 0: （默认）关闭回退策略，弱网时不对音视频流作回退处理。
  - 1: 网络条件较差的情况下，SDK 将订阅视频小流。
  - 2: 网络较弱时，先尝试订阅视频小流，如果网络环境无法显示视频，则再回退到只订阅音频流。
Returns void

setTurnServer

setTurnServer(turnServer: object): void

部署 TURN 服务器

Note:

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

example

client.setTurnServer(config);

Parameters
- turnServer: object
  
  TURN 服务器配置
  - forceturn: boolean
    是否启用强制中转：
    
    true: 强制所有流走中转
    
    false: （默认值）不强制走中转
  - password: string
    
    你在 TURN 服务器上使用的密码
  - Optional tcpport?: string
    
    你想要添加的 TCP 端口
  - turnServerURL: string
    
    你的 TURN 服务器 URL 地址
  - Optional udpport?: string
    
    你想要添加的 UDP 端口
  - username: string
    
    你在 TURN 服务器上注册并使用的用户名
Returns void

startLiveStreaming

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

新建直播流

该方法新建直播流。
example
示例代码
```
client.setLiveTranscoding(<coding>);
client.startLiveStreaming(<url>, true)
```
Parameters
- url: string
  
  （必选项）直播推流的地址
- Optional enableTranscoding: boolean
  
  (非必选项) 是否启用直播转码。如果设为 true（启用转码），需先调用 setLiveTranscoding。
Returns void

stopLiveStreaming

stopLiveStreaming(url: string): void

删除直播流

该方法停止并删除直播流。

Parameters
- url: string
  
  直播推流的地址
Returns void

subscribe(stream: Stream, onFailure: function): void

订阅远程音视频流

该方法从服务器端接收远程音视频流。
example
示例代码
```
client.subscribe(stream, function(err) {
    console.error("stream subscribe failed", err);
    //……
})
```
Parameters
- stream: Stream
  
  远端音视频流对象
- onFailure: function
  
  方法调用失败时执行的回调函数
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

unpublish

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

取消发布本地音视频流

该方法取消发布本地音视频流。
example
示例代码
```
client.unpublish(stream, function(err) {
    console.log(err);
    //……
})
```
Parameters
- stream: Stream
  
  本地音视频流对象
- onFailure: function
  
  方法调用失败时执行的回调函数
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

unsubscribe

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

取消订阅远程音视频流

该方法取消接收远程音视频流。
example
示例代码
```
client.unsubscribe(stream, function(err) {
    console.log(err);
    //……
})
```
Parameters
- stream: Stream
  
  远端音视频流对象
- onFailure: function
  
  方法调用失败时执行的回调函数
  - - (err: any): void
    - Parameters
      - err: any
      Returns void
Returns void

Agora Web SDK API Reference

Hierarchy

Index

Methods

Methods

configPublisher

Parameters

width: number

height: number

framerate: number

bitrate: number

publisherUrl: string

Returns void

disableDualStream

Parameters

onSuccess: function

Returns void

onFailure: function

Parameters

err: any

Returns void

Returns void

enableAudioVolumeIndicator

Returns void

enableDualStream

Parameters

onSuccess: function

Returns void

onFailure: function

Parameters

err: any

Returns void

Returns void

init

Parameters

appId: string

onSuccess: function

Returns void

onFailure: function

Parameters

err: string

Returns void

Returns void

join

Parameters

tokenOrKey: string

channel: string

uid: number

onSuccess: function

Parameters

uid: number

Returns void

onFailure: function

Parameters

err: any

Returns void

Returns void

leave

Parameters

onSuccess: function

Returns void

onFailure: function

Parameters

err: any

Returns void

Returns void

on

Parameters

event: "stream-published"

callback: function

Parameters

evt: any

Returns void

Returns void

Parameters

event: "stream-added"

callback: function

Parameters

evt: any

Returns void