本页提供 Agora Web SDK 4.x 版本的发版说明。

概览

Web SDK 4.x 是通过 HTML 网页加载的 JavaScript 和 TypeScript 库。你可以使用 SDK 在网页浏览器中调用 API 建立连接，控制音视频通话和直播服务。

兼容性说明

详见 Web SDK 兼容性。

已知问题

Chrome 弃用和删除 Plan B 语义

Chrome 93 及之后的版本中将弃用和删除 WebRTC 中的 Plan B 语义，详见官方说明。该改动影响以下 Web SDK 版本：

Web SDK 版本	影响范围
2.5.0-2.9.0 3.0.0-3.6.1	在调用 publish 方法后再调用 switchDevice 方法，出现视频卡顿或无声问题。
4.0.0-4.0.1	publish 和 subscribe 方法不生效。

Chrome 93 正式版本计划于 2021 年 8 月发布，详见 Chrome 发版计划。如你使用上述版本的 Web SDK，请尽快升级至最新版本。

4.6.0 版

该版本于 2021 年 7 月 16 日发布。

新增特性

极速直播

Web SDK 自 v4.6.0 起支持极速直播。极速直播与互动直播的区别主要在于主播到观众的延时不同：

• 互动直播中观众端延时级别为超低延时 400 毫秒到 800 毫秒。
• 极速直播中观众端延时级别为低延时 1500 毫秒到 2000 毫秒。

Agora 针对不同级别的观众端延时收取不同的费用。详见极速直播的产品概述和计费说明。

你可通过以下两种方式实现低延时观众端：

• 调用 createClient 创建客户端对象时，将 role 参数设为 "audience"（观众），将 clientRoleOptions 中的 level 参数设为 1（低延时）。
• 调用 setClientRole 方法，将 role 参数设为 "audience"（观众），将 clientRoleOptions 中的 level 参数设为 1（低延时）。

本地轨道 Mute 状态管理

v4.6.0 新增 localTrack.setMuted 方法用于暂停发送本地轨道的媒体数据。该方法与 localTrack.setEnabled 相比，主要有以下区别：

• 调用 localVideoTrack.setEnabled(false) 停止发送视频后，SDK 会立刻关闭摄像头并停止采集视频，摄像头的指示灯会关闭。而 localVideoTrack.setMuted 不影响视频采集状态。
• 调用setEnabled(true) 恢复发送较慢，调用 setMuted(false) 恢复发送较快。

更多信息，参见 setEnabled 和 setMuted 有什么区别？

改进

自动播放失败回调

为优化 iOS 上的视频自动播放处理机制，v4.6.0 废弃了原先的 onAudioAutoplayFailed 回调，新增 onAutoplayFailed 回调作为替代，用于提示音频或视频自动播放失败。在大部分浏览器中，播放纯视频不受到自动播放策略的限制，但是在低电量模式下的 iOS Safari 浏览器中以及开启过自定义自动播放限制的 iOS WKWebView 中（如 iOS 微信浏览器），纯视频的自动播放也会受到限制。

问题修复

v4.6.0 修复了以下问题：

• 调用 localAudioTrack.setVolume 方法没有立即生效。
• 一个页面中使用多个 client 时出现的异常问题。
• SDK 没有检查 App ID 是否是大小为 1 到 256 字节的字符串。

API 变更

新增

• localTrack.setMuted
• onAutoplayFailed
• ClientConfig 中新增 clientRoleOptions 参数
• setClientRole 方法新增 options 参数

废弃

• onAudioAutoplayFailed

4.5.0 版

该版本于 2021 年 5 月 25 日发布。

新增特性

本地播放音频回声消除

在多个用户同时播放一个媒体文件的场景中，例如一起看电影，如果用户 A 在 Chrome 浏览器上通过 HTMLMediaElement 使用扬声器播放媒体文件，扬声器播放的声音会和人声一起被 SDK 采集，因此其他用户会听到自己本地播放的媒体音频以及用户 A 发送的媒体音频，从而产生回声。针对这种情况，v4.5.0 提供 processExternalMediaAEC 方法。你可以在调用 processExternalMediaAEC 方法时传入 HTMLMediaElement，对本地播放的媒体进行回声消除，提升音频体验。

改进

媒体流加密

为了加强密钥的安全性，v4.5.0 新增 "aes-128-gcm2" 和 "aes-256-gcm2" 加密模式，使用 PBKDF2 (Password-Based Key Derivation Function 2) 函数来派生密钥。调用 setEncryptionConfig 将加密模式设为 "aes-128-gcm2" 或 "aes-256-gcm2" 时，除了 secret，你还需要设置盐值 salt。secret 和 salt 的生成和设置方式详见媒体流加密。

屏幕共享视频属性预设值

v4.5.0 在屏幕共享视频属性 ScreenEncoderConfigurationPreset 中新增以下预设值：

• "480p_3": 分辨率为 640 × 480，帧率为 15 fps。
• "720p_3": 分辨率为 1280 × 720，帧率为 15 fps。
• "1080p_3": 分辨率为 1920 × 1080，帧率为 15 fps。

问题修复

v4.5.0 修复了以下问题：

• OptimizationMode 设置不生效。
• 在 iOS 上使用 Web SDK 采集媒体流时，听到的对端的声音有杂声。
• Firefox 上切换成小流后，getRemoteVideoStats 方法获取到的视频分辨率仍然是大流的分辨率。
• Chrome 上调用 remoteAudioTrack.setVolume 修改音量后，暂停播放再恢复播放，音量修改失效。
• Chrome 上 localAudioTrack.setVolume 没有生效。

API 变更

新增

• processExternalMediaAEC
• ClientConfig 中新增 clientRoleOptions 参数
• setClientRole 方法新增 options 参数
• setEncryptionConfig 新增 salt 参数
• EncryptionMode 新增 "aes-128-gcm2" 和 "aes-256-gcm2" 属性
• setArea 方法新增 excludedArea 参数

4.4.0 版

该版本于 2021 年 4 月 2 日发布。

升级必看

域名白名单变更

自 v4.4.0 起，SDK 的域名白名单变更为：

.agora.io
.edge.agora.io
.sd-rtn.com
.edge.sd-rtn.com

为确保你在有网络访问限制的环境中能够使用 Agora 产品，如果你将 SDK 升级至 v4.4.0，请务必更新防火墙的域名白名单。

改进

AES-GCM 加密模式

在安全要求高的场景中，为保证数据的保密性、完整性和真实性，提高数据加密的计算效率，v4.4.0 在 EncryptionMode 中新增以下加密模式：

• "aes-128-gcm": 128 位 AES 加密，GCM 模式。
• "aes-256-gcm": 256 位 AES 加密，GCM 模式。

开启加密功能后，同一频道内的所有用户都必须使用相同的加密模式和密钥，包括服务端用户（例如 Agora 录制服务）。

云代理服务

v4.4.0 新增 client.on("is-using-cloud-proxy") 事件，SDK 会在本地成功发布媒体流后触发该事件，提示当前媒体流是否经云代理服务转发。

错误码

Windows 上禁用采集设备后进行媒体采集，SDK 抛出的错误由 UNEXPECTED_ERROR 调整为 NOT_READABLE。

问题修复

v4.4.0 修复了以下问题：

• 远端音频轨道的 "first-frame-decoded" 事件没有触发。
• AgoraRTC.checkSystemRequirement 的返回值不准确。
• 网络存在多出口 IP 时，开启云代理后没有生效。

API 变更

新增

• client.on("is-using-cloud-proxy")
• EncryptionMode 新增 "aes-128-gcm" 和 "aes-256-gcm"

4.3.0 版

该版本于 2021 年 1 月 26 日发布。

新增特性

云代理服务

该版本优化了 Agora 云代理架构，进一步加强了有网络访问限制的环境中 SDK 的连通性，同时支持限定访问区域。

你可联系 sales@agora.io 或技术支持申请使用优化后的云代理服务，然后调用 startProxyServer 方法将 mode 参数设为 3 实现使用云代理服务。详见使用云代理服务。

4.2.1 版

该版本于 2020 年 12 月 23 日发布，修复了 client.publish 方法传入非法参数时错误说明抛出异常的问题。

4.2.0 版

该版本于 2020 年 12 月 1 日发布。

新增特性

设置区域访问限制

该版本新增 AgoraRTC.setArea 方法用于指定服务器的访问区域。指定访问区域之后，SDK 只会连接到指定区域内的 Agora 服务器。支持的区域如下：

• 中国
• 北美
• 欧洲
• 亚洲（中国大陆除外）
• 日本
• 印度
• 全球

该功能为高级设置，适用于有访问安全限制的场景。

视频传输优化策略

该版本新增 localVideoTrack.setOptimizationMode 方法用于设置视频传输优化模式，可设为：

• "balanced": 使用默认的传输优化模式。
• "detail": 清晰优先。
• "motion": 流畅优先。

各个传输优化模式的介绍详见 API 参考。该方法适用于在视频通话、视频直播或屏幕共享过程中需要动态调整视频传输优化模式的场景。例如在屏幕共享过程中，如想要把屏幕共享内容从演示文稿切换为视频，可以调用此方法将传输优化模式从 "detail" 切换为 "motion"，确保视频画面在网络波动时不会出现卡顿。

远端用户网络质量

该版本新增 AgoraRTCClient.getRemoteNetworkQuality 方法用于获取本地订阅的所有远端用户的上下行网络质量。

云代理

该版本中 AgoraRTCClient.startProxyServer 方法的 mode 参数类型由 boolean 改成 number。

改进

• 音频或视频轨道被 setEnabled 方法禁用时，依然可以调用 setDevice 方法切换设备。

• 调用 AgoraRTCClient.setEncryptionConfig 开启 SDK 内置加密功能后，当终端用户设置的密码为弱密码时，SDK 会在控制台打印警告信息，提醒用户设置强密码，即密码必须满足以下要求：

  • 包含大写字母、小写字母、数字和特殊字符。
  • 长度至少 8 位。

问题修复

该版本修复了以下问题：

• 本地的某一个视频轨道被禁用时，不能发布另一个视频轨道。
• 开启双流模式后，发布视频轨道过程中，调用 setEnabled(false) 禁用该轨道，发布会失败且无法恢复。
• 直播模式下观众尝试发布本地轨道失败后，切换成主播后也不能发布轨道。
• 开启双流模式后，网络断开时偶现的 bug 导致重连后发布失败。
• 取消发布一个本地摄像头视频轨道再发布本地屏幕共享轨道时，视频码率固定为 700 Kbps 左右，分辨率和帧率下降。
• 由于 Safari 浏览器对于 WebAudio 的支持存在缺陷，在 Safari 浏览器上可能会出现 BufferSourceAudioTrack 的声音失真。
• 第一次获取设备权限时不会触发媒体设备变更事件（onMicrophoneChanged、onCameraChanged 或 onPlaybackDeviceChanged），之后再有设备变更时才会触发设备变更事件。

API 变更

新增

• AgoraRTC.setArea
• localVideoTrack.setOptimizationMode
• AgoraRTCClient.getRemoteNetworkQuality

更新

• AgoraRTCClient.startProxyServer 方法的 mode 参数类型由 boolean 改成 number

4.1.1 版

该版本于 2020 年 10 月 27 日发布。该版本修复了以下问题：

• 提升了 event_network_quality 回调的准确性。
• Safari 上 SDK 无法找到视频采集设备时， createCameraVideoTrack 的调用无法结束。
• 调用 unsubscribe 取消订阅某远端用户的一路未发布的轨道后，后续对该用户的订阅和取消订阅操作都失效。
• 降低双流模式时频繁调用 setEnabled 方法启用和禁用视频轨道的消耗。
• Safari 14 上调用 client.getLocalVideoStats 方法的偶现报错。

4.1.0 版

该版本于 2020 年 9 月 4 日发布。

新增特性

客户端截图

v4.1.0 新增 getCurrentFrameData 方法，用于获取当前渲染的视频帧数据。

音频播放设备管理

v4.1.0 新增了以下方法和回调，用于音频播放设备的管理：

• setPlaybackDevice: 用于设置音频播放设备，比如扬声器。该方法仅支持 Chrome 浏览器。
• getPlaybackDevices: 用于获取可用的音频播放设备。
• onPlaybackDeviceChanged: 用于提示有音频播放设备被添加或移除。

改进

• 全面支持基于 Chromium 内核的 Windows Edge 浏览器（80 及以上版本）。
• 提升了 network-quality 事件的准确性。
• 新增支持在 macOS 平台上共享 Chrome 标签页时分享标签页的音频。

问题修复

• Safari 上 checkVideoTrackIsActive 不准确。
• 开启双流模式后断线重连可能失败。
• 离开频道后调用 setEnabled 可能失败。
• CDN 推流转码和非转码不能同时使用。
• 断开连接后自动重新订阅可能失败，报错 UNEXPECTED_RESPONSE: ERR_SUBSCRIBE_REQUEST_INVALID。
• 在同一个标签页中相同 UID 加入不同频道会失败。
• 频繁加入离开频道可能导致的频道连接状态错误。

API 变更

新增

• AgoraRTC.getPlaybackDevices
• AgoraRTC.onPlaybackDeviceChanged
• Client.getLocalAudioStats
• Client.getRemoteAudioStats
• Client.getLocalVideoStats
• Client.getRemoteVideoStats
• LocalVideoTrack.getCurrentFrameData
• RemoteVideoTrack.getCurrentFrameData
• LocalAudioTrack.setPlaybackDevice
• RemoteAudioTrack.setPlaybackDevice

废弃

• 废弃了 LocalTrack.getStats 和 RemoteTrack.getStats，请使用 Client.getLocalAudioStats 等方法来获取本地和远端的媒体质量信息。

4.0.1 版

该版本于 2020 年 7 月 18 日发布，该版本修复了以下问题：

• 修复 Chrome 70 下发布失败的问题。
• 修复某些情况下离开频道发布操作没有被中止的问题。

4.0.0 版

该版本于 2020 年 7 月 15 日发布。

升级必看

v4.0.0 删除了 setMute 方法，新增 setEnabled 方法来实现启用或禁用本地轨道。这样做的好处在于：

• 彻底移除 Mute 这一概念，避免混淆 Mute 状态和发布状态。
  • 在 v4.0.0 之前的版本中，Mute 状态发生改变后 SDK 会触发 Client.on("user-mute-updated") 回调。
  • 在 v4.0.0 版本中，setEnabled 不会引入额外的远端回调事件。如果该本地轨道已发布，setEnabled(false) 后远端会触发 Client.on("user-unpublished") 回调，setEnabled(true) 后远端会触发 Client.on("user-published") 回调。
• setMute(true) 后，SDK 依然会发送黑帧和静音帧。对于视频轨道来说，Mute 后摄像头的指示灯并不会关闭，因而影响用户体验。而通过 setEnabled(false) 禁用本地视频轨道后，SDK 会立刻关闭摄像头并停止采集视频。

请注意，由于 setEnabled 涉及设备采集，所以是一个异步方法，通过 Promise 返回异步操作的结果。

新增特性

视频编码策略

v4.0.0 在 CameraVideoTrackInitConfig、ScreenVideoTrackInitConfig 和 CustomVideoTrackInitConfig 类中新增 optimizationMode 字段，支持在调用 createCameraVideoTrack、createCustomVideoTrack 和 createScreenVideoTrack 方法创建视频轨道时选择视频画面是清晰优先还是流畅优先：

• 清晰优先：
  • SDK 会自动根据你的采集分辨率和帧率设定一个最小码率。即使遭遇网络波动，发送码率也不会低于这个值，从而确保清晰的视频画面。
  • 大部分情况下，视频编码器不会降低发送分辨率，但是可能会降低帧率。
• 流畅优先：
  • SDK 不会启用最小码率策略。遭遇网络波动时，发送端会降低码率来确保接收端的视频画面不会出现中断和卡顿。
  • 大部分情况下，视频编码器不会降低帧率，但是可能会降低发送分辨率。

通过 createScreenVideoTrack 创建的视频轨道默认设置为清晰优先。

改进

• 重新设计 AgoraRTC.createScreenVideoTrack 的 withAudio 参数，除了 enable 和 disable 外，还可设为 auto，根据浏览器是否支持决定是否分享音频，以满足更多屏幕共享音频的使用场景。
• 不允许 mediaType 参数携带 "all"，只能为 "video" 或 "audio"，以避免代码的重复。这一改动涉及以下 API：
  • Client.subscribe 方法中的 mediaType 参数不能设为 "all"，只能设为 "audio" 或 "video"。
  • Client.on("user-published") 和 Client.on("user-unpublished") 回调的 mediaType 参数不再报告 "all"，只会报告 "audio" 或 "video"。

问题修复

v4.0.0 修复了以下问题：

• 调用 unpublish 后远端会触发 Client.on("user-left") 回调。
• 在 "rtc" 模式下进行屏幕共享发生周期性模糊。
• 频繁发布和取消发布时偶现的发布失败。
• Client.on("network-quality") 回调不准。

API 变更

新增

• 新增 Client.localTracks，用于保存已发布的本地轨道对象列表。
• 新增 LocalTrack.setEnabled，用于启用或禁用本地轨道。
• CameraVideoTrackInitConfig、ScreenVideoTrackInitConfig 和 CustomVideoTrackInitConfig 类中新增 optimizationMode 字段，用于在创建视频轨道时设置视频画面是清晰优先还是流畅优先。

更新

• AgoraRTC.createScreenVideoTrack 的 withAudio 参数新增支持设为 auto。
• Client.subscribe 的 mediaType 参数不能设为 "all"。
• Client.on("user-published") 和 Client.on("user-unpublished") 回调的 mediaType 参数不再报告 "all"。

废弃

• 废弃了 LocalAudioTrackStats.muteState 属性。
• 废弃了 LocalVideoTrackStats.muteState 属性。
• 废弃了 RemoteAudioTrackStats.muteState 属性。
• 废弃了 RemoteVideoTrackStats.muteState 属性。

删除

• 删除了 Client.on("user-mute-updated") 回调。
• 删除了 LocalTrack.setMute 方法。
• 删除了 AgoraRTCRemoteUser.audioMuted 属性。
• 删除了 AgoraRTCRemoteUser.videoMuted 属性。
• 删除了 LocalTrack.getUserId 方法。