文档中心
互动直播
Agora.io 社区
中文
search-icon
Agora Web SDK 4.x 发版说明
更新时间 2021/10/14 04:19:20

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

本文仅适用于 Agora Web SDK 4.x。这是基于 Web SDK 3.x 的全量重构版本，不向下兼容。
  • 查看 Web SDK 4.x 介绍及迁移指南。
  • 查看 Web SDK 3.x 及之前版本的发版说明。
  • 查看 Web SDK 3.x 及之前版本的相关文档。

    • 概览

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

    兼容性说明

    详见 Web SDK 兼容性。

    为保证最佳的用户体验，Agora 强烈推荐使用桌面端 Google Chrome 浏览器官方最新版本。

    已知问题

    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.7.2 版

    该版本于 2021 年 10 月 14 日发布，有以下改动：

    • 规避了在某些场景下，iOS 15 中 Safari 浏览器上音视频通话被系统来电打断后，无法恢复音视频播放和发送的问题，详见问题说明。
    • 规避了在桌面端和移动端 Safari 15 浏览器上，使用 videoTrack.play(element, {mirror: true}) 播放视频时可能出现黑屏的问题，详见问题说明。
    • 修复了在 Edge 浏览器上调用 AgoraRTC.checkSystemRequirements() 返回 false 的问题。

    4.7.1 版

    该版本于 2021 年 9 月 13 日发布，修复了在 Safari 11 和 iPad Chrome 浏览器上的一些问题。

    4.7.0 版

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

    升级必看

    自 v4.7.0 起，如果你启用媒体流加密，用户离开频道后，SDK 会自动关闭加密并重置加密设置。如需重新开启加密，你需要在用户再次加入频道前调用 setEncryptionConfig 方法。

    改进

    v4.7.0 进行了以下改进：

    • 优化了 Web SDK 在移动端浏览器上的体验。
    • 提升了 getVolumeLevel 方法获取到的音量的准确性。
    • 支持在 Safari 上开启双流模式。

    问题修复

    v4.7.0 修复了以下问题：

    • 调用 LocalAudioTrack.setVolume 调整本地音量后，本地用户无法感知到音量变化。
    • 设置日志等级为不打印日志时，SDK 仍会打印初始化的一些日志。
    • LocalAudioTrack.setDevice 返回的 Promise 可能一直处于 pending 状态。

    4.6.3 版

    该版本于 2021 年 8 月 10 日发布，修复了一个偶现问题：本地关闭标签页或浏览器后，远端没有立即收到 user-left 事件。

    4.6.2 版

    该版本于 2021 年 7 月 30 日发布，修复了 SDK 内部存在未销毁的 Media Player 的问题。由于 Chrome 92 新增了一个页面最多创建 75 个 Media Player 的限制，数次播放轨道后，SDK 内未销毁的 MediaPlayer 会导致当前页面无法继续播放。

    4.6.1 版

    该版本于 2021 年 7 月 21 日发布，修复了一个内部错误。

    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（低延时）。
    极速直播暂不支持 Firefox 浏览器。

    本地轨道 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 方法。