文档中心
语音通话
Console Agora.io 社区 提交工单
简体中文
search-icon

Agora Web API Reference

概览 AgoraRTC Client Stream Error Codes Warning Codes

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

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

Hierarchy

  • Client

Index

Methods

Methods

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

    在同一台设备上开多个通话页面可能会导致该功能不准或失效。

    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

    该方法对以下场景无效：

    • 音频通话 (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

    Returns void

getConnectionState

  • getConnectionState(): string

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

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

    Returns string

    SDK 与服务器的连接状态，共有以下 4 种：

    • DISCONNECTED：连接断开。该状态表示 SDK 处于以下任一阶段：
    • 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

    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

    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

      包含系统网络信息的回调。

    Returns void

getPlayoutDevices

  • getPlayoutDevices(callback: function): void

  • 枚举音频输出设备

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

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

    Note

    仅支持 Chrome 49 及以上。

    Parameters

    Returns void

getRecordingDevices

  • getRecordingDevices(callback: function): void

  • 枚举音频输入设备

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

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

    Parameters

    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

    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

    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

      包含会话状况统计数据的回调。

    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

      包含系统信息的回调。

    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

      包含与网关的连接状况的统计数据的回调。

    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, optionalInfo?: string, 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 到 (232-1)
      • 如果使用字符串作为用户 ID，长度不超过 255 个字符。
      • 使用字符串作为用户 ID 支持与 Native SDK 2.8 及以上版本互通，请确保 Native SDK 使用 User Account 加入频道。详见使用 String 型的用户名。
    • Optional optionalInfo: string

      （选填）你想要传入的附加信息。一般可设置为空，或频道相关信息。该信息不会传递给频道内的其他用户。

    • Optional onSuccess: function

      方法调用成功时执行的回调函数，返回值代表用户身份的 uid（整型）。如果使用字符串作为用户 ID 加入频道，则返回对应的整型 uid。

        • (uid: number): void

        • Parameters

          • uid: number

          Returns void

    • Optional onFailure: function

      方法调用失败时执行的回调函数，常见的错误如下：

      • "INVALID_OPERATION": 当前无法加入频道，通常是因为重复调用了 Client.join。
      • "UID_CONFLICT": 当前 Client 的 uid 和频道中其他 Client 的 uid 冲突。
      • "ERR_REPEAT_JOIN": 当前 Client 已经加入了频道。
      • "SOCKET_ERROR": 加入频道过程中和 Agora 服务器断开连接。
      • "CANNOT_MEET_AREA_DEMAND": 由于用户在指定的访问区域外，导致无法建立连接。例如，假设你将 ClientConfig.areaCode 设为 [AgoraRTC.AREAS.CHINA]，位于日本的用户尝试加入频道时就会发生此错误。如果你没有设置 ClientConfig.areaCode，SDK 默认会同时请求多个区域的服务器并择优进行连接，因此在用户加入频道时控制台日志可能也会打印该错误。这种情况你可以忽略该错误码。
        • (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

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": 媒体传输通道建立失败。
      • "REQUEST_ABORT": 发布过程中连接断开，退出频道。建议监听 rejoin 事件，等重连成功后再次调用 publish。
        • (err: string): void

        • Parameters

          • err: string

          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

    • 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" | "sm4-128-ecb" | "aes-128-gcm" | "aes-256-gcm" | "aes-128-gcm2" | "aes-256-gcm2" | "none", salt?: Uint8Array): void

  • 设置内置加密方案

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

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

    Note

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

    client.setEncryptionMode(encryptionMode);

    Parameters

    • encryptionMode: "aes-128-xts" | "aes-256-xts" | "aes-128-ecb" | "sm4-128-ecb" | "aes-128-gcm" | "aes-256-gcm" | "aes-128-gcm2" | "aes-256-gcm2" | "none"

      加密模式，包含以下几种：

      • "aes-128-xts": 128 位 AES 加密，XTS 模式。
      • "aes-256-xts": 256 位 AES 加密，XTS 模式。
      • "aes-128-ecb": 128 位 AES 加密，ECB 模式。
      • "aes-128-gcm": 128 位 AES 加密，GCM 模式。
      • "aes-256-gcm": 256 位 AES 加密，GCM 模式。
      • "sm4-128-ecb": 128 位国密 SM4 加密，ECB 模式。
      • "aes-128-gcm2": 128 位 AES 加密，GCM 模式，加盐。
      • "aes-256-gcm2": 256 位 AES 加密，GCM 模式，加盐。
      • "none": 不加密。
    • Optional salt: Uint8Array

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

    Returns void

setEncryptionSecret

  • setEncryptionSecret(password: string): void

  • 设置内置加密密钥

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

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

    Note

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

    client.setEncryptionSecret(password)

    Parameters

    • password: string

      加密密钥。ASCII 字符，字符串长度大于 0 小于 256 字节。当终端用户设置的密码为弱密码时，SDK 会在控制台打印警告信息，提醒用户设置强密码，即密码必须包含大写字母、小写字母、数字和特殊字符，以及长度至少 8 位。Agora 推荐你在服务端使用 OpenSSL 生成密钥，详见媒体流加密。

    Returns void

setLiveTranscoding

  • 设置直播推流转码

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

    Note

    Parameters

    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

  • 部署 TURN 服务器

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

    Note

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

    example

    client.setTurnServer(config);

    Parameters

    • turnServer: TurnServer[]

      由 TurnServer 对象组成的数组，支持传入多组 TURN 服务器设置。

    Returns void

startChannelMediaRelay

  • 开始跨频道媒体流转发

    自从
       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

    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 提供错误信息。

    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

  • 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

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

    自从
       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

    Returns void