开发者中心
语音通话
Agora.io 社区
中文
search-icon
Agora Web API Reference
概览 AgoraRTC Client Stream 错误代码 警告代码

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

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

Hierarchy

  • Client

Index

Methods

Methods

addInjectStreamUrl

  • 输入在线媒体流

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

    Note

    • 频道内同一时间只允许输入一个在线媒体流。
    • 请确保已开通旁路推流的功能。

    调用该方法后，SDK 会在本地触发 Client.on("streamInjectedStatus") 回调，报告输入在线媒体流的状态；成功输入媒体流后，该音视频流会出现在频道中，频道内所有用户都会收到 Client.on("stream-added") 和 Client.on("peer-online") 回调，其中 UID 为 666。

    Parameters

    • url: string

      添加到直播中的视频流 HTTP/HTTPS 地址，ASCII 字符，字符串长度小于 256 字节。支持 RTMP，HLS，HTTP-FLV 协议传输。

      • 支持的 FLV 音频编码格式：AAC
      • 支持的 FLV 视频编码格式：H.264 (AVC)
    • config: InjectStreamConfig

      输入的在线媒体流的设置，详见 InjectStreamConfig。

    Returns void

configPublisher

  • configPublisher(param: { bitrate: number; framerate: number; height: number; publisherUrl?: string | null; width: number }): void

  • 配置直播旁路推流

    DEPRECATED

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

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

    Note

    该方法需要在 Client.join 前调用。

    example

    示例代码

    client.configPublisher({
  width: 360,
  height: 640,
  framerate: 30,
  bitrate: 500,
  publishUrl: "rtmp://xxx/xxx/"
});

    Parameters

    • param: { bitrate: number; framerate: number; height: number; publisherUrl?: string | null; width: number }

      设置旁路直播的属性

      • 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?: () => void, onFailure?: (err: string) => void): void

  • 关闭双流模式

    该方法关闭双流模式。

    example

    示例代码

    client.disableDualStream(function() {
  console.log("Disable dual stream success!")
}, function(err) {
  console.log(err)
});

    Parameters

    • Optional onSuccess: () => void

      方法调用成功时执行的回调函数

        • (): void

        • Returns void

    • Optional onFailure: (err: string) => void

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

      • "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?: () => void, onFailure?: (err: string) => void): 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: () => void

      方法调用成功时执行的回调函数

        • (): void

        • Returns void

    • Optional onFailure: (err: string) => void

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

      • "IOS_NOT_SUPPORT": 不支持 iOS。
      • "WECHAT_NOT_SUPPORT": 不支持微信。
      • "STILL_ON_PUBLISHING": 处于正在发布的状态中无法开启大小流。
      • "ENABLE_DUALSTREAM_FAILED": 开启大小流失败。
        • (err: string): void

        • Parameters

          • err: string

          Returns void

    Returns void

getCameras

  • 枚举视频输入设备

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

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

    Parameters

    Returns void

getConnectionState

  • getConnectionState(): string

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

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

    Returns string

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

    • DISCONNECTED：连接断开。该状态表示 SDK 处于以下任一阶段：
    • CONNECTING：正在连接中。在调用 Client.join 或者连接中断自动重连的时候为此状态。
    • CONNECTED：已连接。该状态表示用户已经加入频道，可以在频道内发布或订阅媒体流。
    • DISCONNECTING：正在断开连接。在调用 Client.leave 的时候为此状态。

getLocalAudioStats

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

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

    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

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

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

    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: (stats: NetworkStats) => void): void

  • 获取系统网络信息

    DEPRECATED

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

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

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

    Note

    该功能仅支持 Chrome 61+ ，且无法保证兼容性，详见网络状况 API。

    example

    示例代码

    client.getNetworkStats((stats) => {
    console.log(`Current network type: ${stats.NetworkType}`);
});

    Parameters

    Returns void

getPlayoutDevices

  • 枚举音频输出设备

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

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

    Note

    仅支持 Chrome 49 及以上。

    Parameters

    Returns void

getRecordingDevices

  • getRecordingDevices(callback: (devices: MediaDeviceInfo[]) => void): void

  • 枚举音频输入设备

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

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

    Parameters

    Returns void

getRemoteAudioStats

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

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

    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

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

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

    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: (stats: SessionStats) => void): 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

    Returns void

getSystemStats

  • getSystemStats(callback: (stats: SystemStats) => void): void

  • 获取系统信息

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

    Note

    该功能处于实验阶段，浏览器兼容信息请参考 Battery Status API。

    example

    示例代码

    client.getSystemStats((stats) => {
    console.log(`Current battery level: ${stats.BatteryLevel}`);
});

    Parameters

    Returns void

getTransportStats

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

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

    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

    Returns void

init

  • init(appId: string, onSuccess?: () => void, onFailure?: (err: string) => void): 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: () => void

      方法调用成功时执行的回调函数

        • (): void

        • Returns void

    • Optional onFailure: (err: string) => void

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

      • "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?: (uid: number) => void, onFailure?: (err: string) => void): 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: (uid: number) => void

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

        • (uid: number): void

        • Parameters

          • uid: number

          Returns void

    • Optional onFailure: (err: string) => void

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

      • "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?: () => void, onFailure?: (err: string) => void): 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: () => void

      方法调用成功时执行的回调函数

        • (): void

        • Returns void

    • Optional onFailure: (err: string) => void

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

      • "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: (evt: any) => void): void
  • on(event: "first-video-frame-decode", callback: (evt: any) => void): void
  • on(event: "stream-published", callback: (evt: any) => void): void
  • on(event: "stream-unpublished", callback: (evt: any) => void): void
  • on(event: "stream-added", callback: (evt: any) => void): void
  • on(event: "stream-removed", callback: (evt: any) => void): void
  • on(event: "stream-subscribed", callback: (evt: any) => void): void
  • on(event: "peer-online", callback: (evt: { uid: string }) => void): void
  • on(event: "peer-leave", callback: (evt: { reason: string; uid: string }) => void): void
  • on(event: "mute-audio", callback: (evt: any) => void): void
  • on(event: "unmute-audio", callback: (evt: any) => void): void
  • on(event: "mute-video", callback: (evt: any) => void): void
  • on(event: "unmute-video", callback: (evt: any) => void): void
  • on(event: "crypt-error", callback: (evt: any) => void): void
  • on(event: "client-banned", callback: (evt: any) => void): void
  • on(event: "active-speaker", callback: (evt: any) => void): void
  • on(event: "volume-indicator", callback: (evt: any) => void): void
  • on(event: "liveStreamingStarted", callback: (evt: any) => void): void
  • on(event: "liveStreamingFailed", callback: (evt: any) => void): void
  • on(event: "liveStreamingStopped", callback: (evt: any) => void): void
  • on(event: "liveTranscodingUpdated", callback: (evt: any) => void): void
  • on(event: "streamInjectedStatus", callback: (evt: any) => void): void
  • on(event: "onTokenPrivilegeWillExpire", callback: (evt: any) => void): void
  • on(event: "onTokenPrivilegeDidExpire", callback: (evt: any) => void): void
  • on(event: "error", callback: (evt: { reason: any; type: "error" }) => void): void
  • on(event: "network-type-changed", callback: (evt: any) => void): void
  • on(event: "recording-device-changed", callback: (evt: any) => void): void
  • on(event: "playout-device-changed", callback: (evt: any) => void): void
  • on(event: "camera-changed", callback: (evt: any) => void): void
  • on(event: "stream-type-changed", callback: (evt: any) => void): void
  • on(event: "connection-state-change", callback: (evt: { curState: string; prevState: string }) => void): void
  • on(event: "stream-reconnect-start", callback: (evt: { uid: number | string }) => void): void
  • on(event: "stream-reconnect-end", callback: (evt: { reason: string; success: boolean; uid: number | string }) => void): void
  • on(event: "client-role-changed", callback: (evt: { role: string }) => void): void
  • on(event: "reconnect", callback: () => void): void
  • on(event: "rejoin", callback: () => void): void
  • on(event: "connected", callback: () => void): void
  • on(event: "network-quality", callback: (stats: NetworkQualityStats) => void): void
  • on(event: "stream-fallback", callback: (evt: { attr: number; uid: string | number }) => void): void
  • on(event: "stream-updated", callback: (evt: { stream: Stream }) => void): void
  • on(event: "exception", callback: (evt: { code: number; msg: string; uid: string }) => void): void
  • on(event: "enable-local-video", callback: (evt: { uid: string }) => void): void
  • on(event: "disable-local-video", callback: (evt: { uid: string }) => void): void
  • on(event: "channel-media-relay-event", callback: (evt: { code: number }) => void): void
  • on(event: "channel-media-relay-state", callback: (evt: { code: number; state: number }) => void): 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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: { uid: string }) => void
        • (evt: { uid: string }): void

        • Parameters

          • evt: { uid: string }
            • 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: (evt: { reason: string; uid: string }) => void
        • (evt: { reason: string; uid: string }): void

        • Parameters

          • evt: { reason: string; uid: string }
            • 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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知应用直播推流成功。

    Parameters

    • event: "liveStreamingStarted"
    • callback: (evt: any) => void
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知应用直播推流失败。

    Parameters

    • event: "liveStreamingFailed"
    • callback: (evt: any) => void
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知应用直播推流已停止。

    Parameters

    • event: "liveStreamingStopped"
    • callback: (evt: any) => void
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知应用推流转码设置已被更新。

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

    Parameters

    • event: "liveTranscodingUpdated"
    • callback: (evt: any) => void
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知应用导入在线媒体流状态已更新。

    Parameters

    • event: "streamInjectedStatus"
    • callback: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: { reason: any; type: "error" }) => void
        • (evt: { reason: any; type: "error" }): void

        • Parameters

          • evt: { reason: any; type: "error" }
            • 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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (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: (evt: any) => void
        • (evt: any): void

        • Parameters

          • evt: any

          Returns void

    Returns void

  • 该回调通知应用SDK 与服务器的连接状态发生改变

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

    • DISCONNECTED：连接断开。该状态表示 SDK 处于以下任一阶段：
    • 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: (evt: { curState: string; prevState: string }) => void
        • (evt: { curState: string; prevState: string }): void

        • Parameters

          • evt: { curState: string; prevState: string }
            • 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: (evt: { uid: number | string }) => void
        • (evt: { uid: number | string }): void

        • Parameters

          • evt: { uid: number | string }
            • 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: (evt: { reason: string; success: boolean; uid: number | string }) => void
        • (evt: { reason: string; success: boolean; uid: number | string }): void

        • Parameters

          • evt: { reason: string; success: boolean; uid: number | string }
            • 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: (evt: { role: string }) => void
        • (evt: { role: string }): void

        • Parameters

          • evt: { role: string }
            • role: string

              改变后的角色。

          Returns void

    Returns void

  • 该回调通知正在与服务器重新建立连接。

    example

    示例代码

    client.on("reconnect", function() {
  console.log("reconnect");
});

    Parameters

    • event: "reconnect"
    • callback: () => void
        • (): void

        • Returns void

    Returns void

  • 该回调通知本地用户已经成功重新加入频道。

    example

    示例代码

    client.on("rejoin", function() {
  console.log("rejoin");
});

    Parameters

    • event: "rejoin"
    • callback: () => void
        • (): void

        • Returns void

    Returns void

  • 该回调通知与服务器已经成功建立连接。

    example

    示例代码

    client.on("connected", function() {
  console.log("connected");
});

    Parameters

    • event: "connected"
    • callback: () => void
        • (): 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

    Returns void

  • 该回调表示订阅的音视频流回退为音频流或恢复为音视频流。

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

    Note

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

    Parameters

    • event: "stream-fallback"
    • callback: (evt: { attr: number; uid: string | number }) => void
        • (evt: { attr: number; uid: string | number }): void

        • Parameters

          • evt: { attr: number; uid: string | number }
            • attr: number

              流的回退类型：

              • 1: 从音视频流回退为纯音频流
              • 0: 从音频流恢复为音视频流
            • uid: string | number

              远端用户的 UID

          Returns void

    Returns void

  • 该回调表示订阅流的音视频轨道发生变化。

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

    Parameters

    • event: "stream-updated"
    • callback: (evt: { stream: Stream }) => void
        • (evt: { stream: Stream }): void

        • Parameters

          • evt: { stream: Stream }
            • 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: (evt: { code: number; msg: string; uid: string }) => void
        • (evt: { code: number; msg: string; uid: string }): void

        • Parameters

          • evt: { code: number; msg: string; uid: string }
            • code: number

              事件码

            • msg: string

              提示消息

            • uid: string

              发生异常或恢复的用户 UID

          Returns void

    Returns void

  • 该回调表示远端 Native 用户调用了 enableLocalVideo(true) 打开视频采集。

    自从
       3.0.0

    Parameters

    • event: "enable-local-video"
    • callback: (evt: { uid: string }) => void
        • (evt: { uid: string }): void

        • Parameters

          • evt: { uid: string }
            • uid: string

              远端用户的 UID

          Returns void

    Returns void

  • 该回调表示远端 Native 用户调用了 enableLocalVideo(false) 关闭视频采集。

    自从
       3.0.0

    Parameters

    • event: "disable-local-video"
    • callback: (evt: { uid: string }) => void
        • (evt: { uid: string }): void

        • Parameters

          • evt: { uid: string }
            • uid: string

              远端用户的 UID

          Returns void

    Returns void

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

    自从
       3.0.0

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

    Parameters

    • event: "channel-media-relay-event"
    • callback: (evt: { code: number }) => void
        • (evt: { code: number }): void

        • Parameters

          • evt: { code: number }
            • 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: (evt: { code: number; state: number }) => void
        • (evt: { code: number; state: number }): void

        • Parameters

          • evt: { code: number; state: number }
            • 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?: (err: string) => void): 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: (err: string) => void

      方法调用失败时执行的回调函数, 可能的错误如下：

      • "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

removeInjectStreamUrl

  • removeInjectStreamUrl(url: string): void

  • 删除输入的在线媒体流

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

    Parameters

    • url: string

      待删除的外部视频流 HTTP/HTTPS 地址。ASCII 字符，字符串长度小于 256 字节。

    Returns void

renewChannelKey

  • renewChannelKey(key: string, onSuccess?: () => void, onFailure?: (err: string) => void): void

  • 更新 Channel Key

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

    Parameters

    • key: string

      指定新的 Channel Key

    • Optional onSuccess: () => void

      方法调用成功时执行的回调函数

        • (): void

        • Returns void

    • Optional onFailure: (err: string) => void

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

      • "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?: (err?: string | null) => void): 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: (err?: string | null) => void
        • (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" | "none"): 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" | "none"

      加密方案，包含以下几种：

      • "aes-128-xts": 128 位 AES 加密，XTS 模式。
      • "aes-256-xts": 256 位 AES 加密，XTS 模式。
      • "aes-128-ecb": 128 位 AES 加密，ECB 模式。
      • "sm4-128-ecb": 128 位国密 SM4 加密，ECB 模式。
      • "none": 不加密。

    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 位。

    Returns void

setLiveTranscoding

  • 设置直播推流转码

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

    Note

    Parameters

    Returns void

setLowStreamParameter

  • setLowStreamParameter(param: { bitrate?: number; framerate?: number; height?: number; width?: number }): void

  • 设置小流视频属性

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

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

    Note

    • 视频小流和视频大流的宽高比会自动保持一致。如果为小流设置的分辨率宽高比和大流不同，SDK 会自动调整小流分辨率的高，以保持大小流的宽高比相同。
    • 由于不同的浏览器对于视频参数设置有不同的限制，通过该接口设置的视频参数不一定都会生效。
      • Firefox 浏览器上设置帧率不生效，浏览器会把帧率固定在 30 fps。
      • 部分浏览器设置视频分辨率可能不生效，这种情况下浏览器会自动调整分辨率。
    • 计费按照实际分辨率计算。
    • 该方法必须在 Client.join 之后以及 Client.publish 之前调用。

    Parameters

    • param: { bitrate?: number; framerate?: number; height?: number; width?: number }

      小流的视频属性。

      • 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: ClientConfig["proxyServer"]): void

  • 部署代理服务器

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

    Note

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

    client.setProxyServer(proxyServer);

    Parameters

    • proxyServer: ClientConfig["proxyServer"]

      你的代理服务器域名。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

  • 停止跨频道媒体流转发

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

    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?: { audio?: boolean; video?: boolean }, onFailure?: (err: string) => void): 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: { audio?: boolean; video?: boolean }

      设置是否接收视频或音频。

      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: (err: string) => void

      方法调用失败时执行的回调函数，以下列举一些常见的错误：

      • "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?: (err: string) => void): 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: (err: string) => void

      方法调用失败时执行的回调函数，以下列举一些可能的错误：

      • "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?: (err: string) => void): void

  • 取消订阅远端音视频流

    该方法取消接收远端音视频流。

    example

    示例代码

    client.unsubscribe(stream, function(err) {
    console.log(err);
    //……
});

    Parameters

    • stream: Stream

      远端音视频流对象

    • Optional onFailure: (err: string) => void

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

      • "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

score