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

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

Hierarchy

  • Client

Index

Methods

configPublisher

  • configPublisher(width: number, height: number, framerate: number, bitrate: number, publisherUrl: string): void
  • 配置直播旁路推流

    DEPRECATED

    该方法已废弃,Agora 推荐你使用以下方法设置直播推流:

    该方法在加入频道前配置旁路直播推流服务。

    Note:

    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 机制,过一段时间后密钥会失效。 当收到 onTokenPrivilegeWillExpireonTokenPrivilegeDidExpire 消息时,调用该 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

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

  • 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