发版说明

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

信息

本文仅适用于声网 Web SDK 4.x。这是基于 Web SDK 3.x 的全量重构版本，不向下兼容。声网已经停止维护 Web SDK 3.x 版本。建议你选择合适的时机，参考迁移指南从 3.x 及以下版本升级至 4.x 版本。

概览

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

兼容性说明

为保证最佳的用户体验，声网强烈推荐使用桌面端 Google Chrome 浏览器官方最新版本。详见 Web SDK 的浏览器兼容性。

已知问题

Chrome 弃用和删除 Plan B 语义

Chrome 计划弃用和删除 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` 方法不生效。

如你使用上述版本的 Web SDK，请尽快升级至最新版本。

4.18.3 版

该版本于 2023 年 9 月 20 日发布。

该版本修复了 SDK 在 Safari 17 上音视频统计数据缺失的问题。

4.18.2 版

该版本于 2023 年 7 月 11 日发布。

该版本修复了 SDK 加载完成后，在特定情况下触发麦克风和摄像头设备权限申请弹窗的问题。

4.18.1 版

该版本于 2023 年 7 月 7 日发布。

改进

事件监听支持错误处理

自该版本起，如果你在事件监听器（listener）中传入的回调函数在执行时发生错误，SDK 不会中断正常运行，而是捕获异常并在日志中输出错误信息。

优化异步方法的并发控制

该版本优化了异步方法的并发控制。如果以下异步方法出现并发执行的情况，SDK 会按照方法被调用的顺序依次执行，保证一致性：

join 和 leave
publish 和 unpublish
subscribe 和 unsubscribe

以 publish 和 unpublish 为例，如果你在调用 publish 之后立即调用 unpublish ：

在 4.18.1 之前， unpublish 有可能不生效，即仍然发布成功。
自 4.18.1 起，实际结果与你的调用顺序保持一致，即不会发布成功。

问题修复

该版本修复了在不具备任何可用摄像头或麦克风的设备上，第一次插入外接摄像头或外接麦克风不会触发以下回调的问题：

onCameraChanged 或 AgoraRTC.on("camera-changed")
onMicrophoneChanged 或 AgoraRTC.on("microphone-changed")

4.18.0 版

该版本于 2023 年 6 月 21 日发布。

新增特性

可伸缩视频编码（Beta）

自 v4.18.0 起，SDK 支持在使用 VP9 编解码时开启 SVC（可伸缩视频编码）。SVC 功能可以根据用户的网络环境和设备性能自适应调节视频流的编码质量，保证所有用户的观看体验。

如需开启 SVC 功能，请联系技术支持。

获取已编码数据（Beta）

自 v4.18.0 起，你可以获取到 SDK 已编码的音频和视频数据。如需开启该功能，请联系技术支持。

提升网络受限环境下的连接体验（Beta）

v4.18.0 支持新的媒体建连策略，可以优化在网络受限环境下的连接体验。如需开启该功能，请联系技术支持。

倍速播放音频文件

为方便在播放音效或音乐文件时调节当前文件的播放速度，v4.18.0 对 IBufferSourceAudioTrack 类做了以下修改：

新增 setAudioBufferPlaybackSpeed 方法。在加入频道前和加入频道后，你都可以调用该方法。
新增 playbackSpeed 属性，用于获取当前的播放速度。

自定义信令代理

在使用声网混合云或私有化平台相关服务时，为方便你自定义 SDK 使用的信令代理服务器，v4.18.0 新增 setProxyServer 方法。

灵活监听 AgoraRTC 对象的事件

自 v4.18.0 起，IAgoraRTC 类继承 EventEmitter 类的所有方法，用于监听 AgoraRTC 对象的所有事件。

以 onCameraChanged 为例：

JavaScript
//  v4.18.0 以前的监听方式
AgoraRTC.onCameraChanged = (info) => {
  console.log("camera changed!", info.state, info.device);
};
// v4.18.0 及以上版本新支持的监听方式
AgoraRTC.on("camera-changed", (info) => {
  console.log("Camera changed!", info.state, info.device);
});

你可以继续沿用以前的监听方式，但如果你需要更高的灵活性和可拓展性，声网推荐你在升级 SDK 后修改以下事件的监听方式：

onAutoplayFailed
onCameraChanged
onMicrophoneChanged
onPlaybackDeviceChanged
onSecurityPolicyViolation
onAudioAutoplayFailed （已废弃，请改用 onAutoplayFailed）

改进

缩短加入频道耗时

自 v4.18.0 起，SDK 默认开启 WebSocket 消息压缩，可以缩短用户在弱网环境下加入频道的耗时。

其它改进

该版本还有以下改进：

缩短了弱网环境下从视频小流切换到视频大流的耗时。
升级了云代理服务以提升在不同网络环境下的稳定性。

问题修复

v4.18.0 修复了以下问题：

开启消息通知服务后，移动端收到的主播离开频道事件通知（104 broadcaster leave channel）可能出现延迟的问题。
在部分旧版本浏览器上，观看使用 H.264 编码的视频流出现黑屏的问题。
SDK 和虚拟背景插件或美颜插件一起使用时，内存明显上涨的问题。
调用 renewToken 方法生成新的 Token 后，SDK 在尝试重连时依然使用已过期的 Token 加入频道的问题。

API 变更

新增

setProxyServer
IBufferSourceAudioTrack 中新增 setAudioBufferPlaybackSpeed 方法和 playbackSpeed 属性
IAgoraRTC 类中新增以下继承自 EventEmitter 类的方法：
- on
- off
- once
- getListeners
- removeAllListeners
  信息
  这些方法支持传入的事件名称如下：
  "camera-changed"
  "microphone-changed"
  "playback-device-changed"
  "autoplay-failed"
  "security-policy-violation"

4.17.2 版

该版本于 2023 年 4 月 19 日发布。

该版本修复了 getCurrentFrameData 方法返回值异常的问题。

4.17.1 版

该版本于 2023 年 4 月 19 日发布。

升级必看

注意

在 Chrome 107 上进行屏幕共享时，默认不能共享当前标签页。如果你需要允许用户在 Chrome 107 及以上版本共享当前标签页，请尽快升级 SDK 至 4.17.1 或以上版本。

为兼容 Chrome 107 的屏幕共享相关改动（详见官方说明），该版本对 createScreenVideoTrack 方法中的 config 参数做了以下修改：

废弃 screenSourceType 属性。如果你使用了该属性，升级到该版本后请改用新增的 displaySurface 属性。
新增 selfBrowserSurface、surfaceSwitching 和 systemAudio 属性。

以上属性的详细说明参考 ScreenVideoTrackInitConfig。

改进

提高设置视频属性的灵活性

该版本提高了对不同类型视频轨道设置视频属性的灵活性，具体包括：

调用 createCustomVideoTrack 创建自定义视频轨道时，支持通过 width、height、frameRate 参数设置分辨率和帧率。
创建屏幕共享视频轨道或者自定义视频轨道后，可以调用 setEncoderConfiguration 动态调整视频属性。在特定的 macOS Safari 版本上，对屏幕共享视频轨道调用该方法会导致一个已知问题，查看问题详情。

详细说明参考设置视频属性。

其它改进

该版本还有以下改进：

缩短在 Safari 浏览器上调用 createMicrophoneAudioTrack 或 createMicrophoneAndCameraTracks 创建轨道的时间。
当本地有两个 AgoraRTCClient 对象时，支持屏蔽其中一个 AgoraRTCClient 加入或离开频道、发布或取消发布的相关回调。以屏幕共享为例：Client A 用于发送屏幕共享视频轨道，Client B 用于发送摄像头视频轨道，开启屏蔽回调功能后，Client A 和 Client B 不会收到对方的以下回调：
- AgoraRTCClient.on("user-published")
- AgoraRTCClient.on("user-joined")
- AgoraRTCClient.on("user-unpublished")
- AgoraRTCClient.on("user-left")
- AgoraRTCClient.on("published-user-list")
- AgoraRTCClient.on("user-info-update")
如需开启该功能，请联系技术支持。

API 变更

新增

ScreenVideoTrackInitConfig 中的 displaySurface（替代 screenSourceType）、selfBrowserSurface、surfaceSwitching 和 systemAudio 属性
CustomVideoTrackInitConfig 中的 width、height、frameRate 属性
LocalVideoTrack.setEncoderConfiguration

4.17.0 版

该版本于 2023 年 3 月 22 日发布。

升级必看

为进一步减小包体积，该版本移除了 SDK 内置的美颜模块，并且删除了 setBeautyEffect。如果你需要实现美颜功能，声网推荐你使用效果升级、性能更优的美颜插件。详见使用美颜插件（Beta）。

新增特性

千人主播（Beta）

自 v4.17.0 起，单个频道可支持最多 1000 位主播同时在线并同时发布音视频流，观众人数无限制，每位主播或观众最多可同时订阅 50 位主播。

如需启用该功能，请联系 sales@shengwang.cn。

本地合图（Beta）

自 v4.17.0 起，SDK 可以与合图插件搭配使用，在发送端将多路视频流以及图片合为一路视频流。你还可以同时使用合图插件和虚拟背景插件，实现人像画中画效果。详见使用合图插件。

动态切换本地视频流

为方便灵活切换本地视频轨道，该版本新增 ILocalVideoTrack.replaceTrack 方法。

以发布本地视频流后、从摄像头 1 采集切换到摄像头 2 采集为例：在 v4.17.0 之前，你需要先调用 IAgoraRTCClient.unpublish 取消发布当前轨道，再调用 IAgoraRTCClient.publish 发布新的轨道；自 v4.17.0 起，直接调用 ILocalVideoTrack.replaceTrack 即可。

改进

优化重连机制

自 v4.17.0 起，SDK 在断线重连时将默认展示断线之前的最后一帧视频画面，避免因为重连而出现黑屏。由于 Safari 自身限制，暂时无法在 Safari 浏览器上体验该优化。

其它改进

该版本还有以下改进：

提升了水晶球上 SDK 相关质量指标的准确性。
缩短了加入频道所需的时间。由于 Firefox 自身限制，暂时无法在 Firefox 浏览器上体验该优化。

API 变更

新增

ILocalVideoTrack.replaceTrack

删除

ILocalVideoTrack.setBeautyEffect

问题修复

v4.17.0 修复了在 iOS 14.7 及以上版本的 Safari 浏览器上，反复订阅、取消订阅多路音频流可能导致听不到远端用户声音的问题。

4.16.1 版

该版本于 2023 年 2 月 8 日发布。

该版本修复了使用 v4.16.0 版本的 SDK 时，水晶球统计的视频卡顿率异常升高的问题。

4.16.0 版

该版本于 2023 年 1 月 5 日发布。

新增特性

混合云或私有化平台

v4.16.0 新增 setLocalAccessPointsV2 方法，用于配置声网混合云或私有化平台的相关服务。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。

改进

兼容 Chrome 即将弃用的 RTCMediaStreamTrackStats

Chrome 计划弃用 RTCMediaStreamTrackStats，详见官方说明。该改动影响声网 Web SDK 返回的一部分本地和远端媒体质量信息，具体如下：

媒体质量信息	受影响的值
`LocalVideoTrackStats`	`sendFrameRate` `sendResolutionHeight` `sendResolutionWidth`
`RemoteVideoTrackStats`	`receiveFrameRate` `receiveResolutionHeight` `receiveResolutionWidth` `renderFrameRate` `receiveDelay`
`RemoteAudioTrackStats`	`receiveDelay` `receiveLevel`

为确保以上媒体质量信息在 Chrome 上的准确性，请尽快升级 SDK 至 4.16.0 或以上版本。

其它改进

v4.16.0 还有以下改进：

日志中支持打印 HTMLMediaElement error 事件的原因。
减小 SDK 包体积。

问题修复

v4.16.0 修复了以下问题：

修复在 SDK 断网重连过程中，无法进行其它媒体操作的问题。
修复转发跨频道媒体流时， ChannelMediaRelayConfiguration.addDestChannelInfo 无法指定被转发媒体流在目标频道中 uid 为 0 的问题。
修复 iOS 14.x 上的已知问题。

API 变更

新增

IAgoraRTCClient.setLocalAccessPointsV2

4.15.1 版

该版本于 2022 年 12 月 2 日发布。

该版本修复了在 iOS 13.7 上接收的音频流无声的问题。

4.15.0 版

该版本于 2022 年 11 月 10 日发布。

升级必看

云代理服务默认采用 Force UDP 模式

v4.15.0 将 startProxyServer 方法的 mode 参数默认值改为 3，即 Force UDP 云代理模式。在该模式下，SDK 始终通过 UDP 协议传输数据。详情参考使用云代理服务。

新增特性

音强选流（Beta）

v4.15.0 新增音强选流功能。该功能开启后，声网服务器会根据音量大小对接收端已订阅的音频流进行筛选，选出 N 路音量最大的音频流传输至接收端。N 默认为 3 路。

同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗。

注意

如需开启音强选流功能或者自定义设置 N，请联系技术支持。

VP9 编解码（Beta）

自 v4.15.0 起，Web SDK 在以下版本的浏览器上支持 VP9 视频编解码：

	支持的浏览器版本 ^①
桌面端	Chrome 65+ Firefox 69+ Edge 79+
Android 端	Chrome 68+ 微信 v8.0.6 及以上其它内嵌 WebView 的应用：WebView v55.0.28883.91 及以上
iOS 端	暂不支持

信息

① 为保证最佳的用户体验，声网建议使用上述浏览器的最新版本。

如果与集成声网 Native 端（包括 Android、iOS、Windows 和 macOS 平台）音视频 SDK 的 App 通过 VP9 进行音视频通话，请确保使用 v4.0.0 或以上版本的 Native 端 SDK 。

触发 CSP 规则回调

v4.15.0 新增 AgoraRTC.onSecurityPolicyViolation 回调。当声网服务相关的资源加载或请求发送因为触发浏览器的 CSP（Content Security Policy，内容安全策略）规则而失败时，SDK 会触发该回调。收到该回调后，请及时调整你的 CSP 设置，确保能正常体验声网的服务。

改进

SDK 有以下改进：

优化了某些场景下 AgoraRTCClient.on("network-quality") 回调的准确性。
缩短了切换 Wi-Fi 时音视频流的恢复时间。

API 变更

新增

IAgoraRTC.onSecurityPolicyViolation

4.14.2 版

该版本于 2022 年 10 月 27 日发布。

该版本修复了在 iOS 14.x 上使用微信浏览器时，订阅的第一路音频流无声的问题。

4.14.1 版

该版本于 2022 年 10 月 24 日发布。

问题修复

v4.14.1 修复了以下问题：

在 v17.x 版本的 Electron 上不能正常使用屏幕共享。解决方案详见 Electron 屏幕共享。
在桌面端 Safari 浏览器上如果禁用所有视频的自动播放，视频会不断尝试重新播放，导致卡顿。
移动端浏览器切换到后台时，SDK 统计的视频卡顿率过高。
Android WebView 中视频开始播放前会展示 video 元素默认的 poster（灰色播放图标）。
SDK 断网重连后，跨频道媒体流转发失败。
使用跨频道媒体流转发时，用户离开源频道后，SDK 仍然在发送心跳包。

4.14.0 版

该版本于 2022 年 8 月 31 日发布。

升级必看

getVolumeLevel 准确性优化

自 v4.14.0 起，SDK 校准了 getVolumeLevel 返回的音量值，能更准确地反映音量大小关系。该方法返回的音量值取值范围依然为 [0,1]，其中 1 代表理论最大音量。如果你的业务场景依赖 getVolumeLevel 返回的音量值（比如根据音量值显示用户说话的图标），升级 SDK 后你需要关注对应场景中该音量值的变化。

问题修复

v4.14.0 修复了以下问题：

接收 Opus 格式的立体声后，听不到立体声效果。
在版本低于 Chrome 76 的浏览器上，调用 getRemoteVideoStats 获取的视频解码帧率decodeFrameRate为 0。
在 iOS 14.1 和 14.2 的微信浏览器上，订阅的第一路音频流无声。
调用 LocalVideoTrack.setBeautyEffect 开启美颜后，调用 LocalVideoTrack.unpipe 方法报错。
特定场景下，Windows Chrome 103 及以上版本的浏览器上开启小流不生效。

API 变更

新增

enableContentInspect
client.on("content_inspect_result")

4.13.0 版

该版本于 2022 年 7 月 25 日发布。

新增特性

媒体处理插件

自 v4.13.0 起，SDK 支持对远端音视频轨道使用媒体处理插件（本地音视频轨道已经在 v4.10.0 支持）。

声网目前提供以下用于远端音频轨道的插件：

插件	说明	相关文档
空间音效插件 (Beta)	用户语音根据位置变化而实时改变，支持声音模糊、空气衰减等效果，打造沉浸式体验。	联系 sales@shengwang.cn 了解详情。

改进

AI 降噪和虚拟背景

AI 降噪插件和虚拟背景插件由 Beta 发布转变为正式发布（v1.0.0）。

相比之前的版本，v1.0.0 版本的 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。

注意

使用 AI 降噪插件和虚拟背景插件可能会产生费用。请与 sales@agora.io 沟通后再使用。

如果当前提供的降噪效果不能满足你的场景，你可以联系 sales@agora.io定制降噪效果。

Token 过期回调

v4.13.0 完善了 token 过期回调的触发逻辑。如果 token 在设备休眠或断网时过期，当设备恢复并尝试重连时，SDK 会触发 token-privilege-did-expire 事件。

API 变更

新增

RemoteAudioTrack.pipe
RemoteAudioTrack.unpipe
RemoteVideoTrack.pipe
RemoteVideoTrack.unpipe

4.12.2 版

该版本于 2022 年 7 月 7 日发布，优化了 SDK 的自动模式（在自动模式下，SDK 优先连接 SD-RTN™ ，如果连接失败，会自动切换到 TCP/TLS 443）。

4.12.1 版

该版本于 2022 年 6 月 27 日发布，修复了以下问题：

在特定情况下，重连后订阅远端音视频流会失败。
在 Firefox 浏览器上反复订阅、取消订阅多路视频流可能导致视频卡住。

4.12.0 版

该版本于 2022 年 6 月 15 日发布。

改进

媒体处理插件

媒体处理插件有以下改动：

新增美颜插件（Beta）。美颜插件封装了 Web SDK 4.x 内置的美颜功能（通过 setBeautyEffect），并且升级了美颜算法。通过该插件可以调节对比度、亮度、平滑度等参数，实现美白、磨皮、红润肤色等美颜效果。详见使用美颜插件。
虚拟背景插件（Beta）自 v1.0.0-beta-3 起支持动态虚拟背景，可以将用户的背景设置为一段视频。详见使用虚拟背景插件。

问题修复

v4.12.0 修复了在 Safari 上开启双流模式后，调用 Track.setEnabled(false)、Track.close() 等方法无法关闭摄像头指示灯的问题。

4.11.1 版

该版本于 2022 年 5 月 9 日发布，修复了以下问题：

Firefox 浏览器中订阅音频流可能导致无声。
iOS 12 Safari 浏览器以及 iOS 13 微信浏览器的兼容性问题。

4.11.0 版

该版本于 2022 年 4 月 1 日发布。

升级必看

自 v4.11.0 起，为保障连通性，SDK 默认使用自动模式。在自动模式下，SDK 优先连接 SD-RTN™ ，如果连接失败，会自动切换到 TCP/TLS 443。你可以通过 client.on("join-fallback-to-proxy") 回调监听 SDK 自动切换到 TCP/TLS 443 的事件。

改进

频道能力提升

自 v4.11.0 起，单个频道可支持最多 128 位主播同时在线并同时发布音视频流，观众人数无限制，每位主播或观众最多可同时订阅 50 位主播。

如有需要，请联系 sales@shengwang.cn。

问题修复

v4.11.0 修复了以下问题：

Angular 依赖的 zone.js 导致 SDK 中的 Promise.finally 调用出错。
在 Chrome 上发送双声道音频时不能开启 AEC。
SDK 在 Chrome 100 上获取的解码帧率和发送帧率数据不准确。
开启双流模式后，调用 unpublish 时不传参数会导致调用失败。

API 变更

新增

AgoraRTCClient.massSubscribe
AgoraRTCClient.massUnsubscribe
AgoraRTCClient.on('published-user-list')
错误码中新增：
- ERR_TOO_MANY_BROADCASTERS
- ERR_TOO_MANY_SUBSCRIBERS

4.10.2 版

该版本于 2022 年 3 月 24 日发布，修复了在特定场景下调用 join 会触发代理异常的问题。

4.10.1 版

该版本于 2022 年 3 月 17 日发布，在 package.json 中补充了对声网插件系统 agora-rte-extension 的 TypeScript 类型定义依赖。如果你使用 TypeScript 进行类型检查，建议将 Typescript 升级至 4.3.2 或以上版本。

4.10.0 版

该版本于 2022 年 3 月 11 日发布。

新增特性

支持媒体处理插件

v4.10.0 支持在 SDK 内使用媒体处理插件。声网当前提供以下插件可与 Web SDK 搭配使用。如需了解如何使用插件，请查看相关文档。

插件	说明	相关文档
虚拟背景插件 (Beta)	支持将用户的背景设为纯色、自定义图片或虚化。	使用虚拟背景插件
AI 降噪插件 (Beta)	支持降低上百种噪声，减少多人同时说话时的人声失真。	使用 AI 降噪插件

API 变更

新增

AgoraRTC.registerExtensions
LocalAudioTrack.pipe
LocalAudioTrack.unpipe
LocalVideoTrack.pipe
LocalVideoTrack.unpipe

4.9.4 版

该版本于 2022 年 3 月 16 日发布，修复了在 Chrome 隐身模式下的 iFrame 中加载 SDK 时访问 localStorage 报错的问题。

4.9.3 版

该版本于 2022 年 3 月 3 日发布，修复了一些内部问题。

4.9.1 版

该版本于 2022 年 2 月 24 日发布，修复了一些内部问题。

4.9.0 版

该版本于 2022 年 2 月 17 日发布。

新增特性

指定所有远端用户的视频流类型

v4.9.0 新增 setRemoteDefaultVideoStreamType 方法，用于发流端通过 enableDualStream 开启双流模式后，接收端指定所有远端用户的视频流类型。

云代理服务 Force TCP 模式

v4.9.0 新增支持云代理服务 Force TCP 模式。该模式下，SDK 始终通过 TLS 443 传输数据。你可在调用 startProxyServer 时将 mode 设为 5 使用该模式。

HTML <video> 标签可见性检测

使用 Web SDK 时，你调用 play 后 SDK 会创建 HTML <video> 标签用于播放视频轨道。v4.8.0 新增以下方法和事件用于获取该 <video> 标签的可见性：

localVideoTrack.on("video-element-visible-status")
remoteVideoTrack.on("video-element-visible-status")
localVideoTrack.getVideoElementVisibleStatus
remoteVideoTrack.getVideoElementVisibleStatus

当 localTrack.isPlaying 或 remoteTrack.isPlaying 为 true 却看不到图像时，你可通过上述方法或事件获取 <video> 标签的可见性和不可见原因，排查问题。

改进

提升 client.on("is-using-cloud-proxy") 回调的准确性。
如果你自定义了视频分辨率但是没有设置码率，SDK 会自动根据分辨率和帧率来计算并设置一个合理的码率，避免码率过高影响带宽。

问题修复

v4.9.0 修复了以下问题：

调用 play 播放本地视频轨道、传入的参数是来自另一个窗口的元素时，SDK 会报错。
v4.8.0 与 Angular、zone.js 一起使用时，zone.js 修改了 promise 对象导致加入频道失败。
iOS 上的一些已知问题。

API 变更

新增

setRemoteDefaultVideoStreamType
client.on("join-fallback-to-proxy")
localVideoTrack.on("video-element-visible-status")
remoteVideoTrack.on("video-element-visible-status")
localVideoTrack.getVideoElementVisibleStatus
remoteVideoTrack.getVideoElementVisibleStatus

4.8.2 版

该版本于 2022 年 1 月 27 日发布，修复了 iOS 微信浏览器上锁屏后解锁可能会黑屏的问题。

4.8.1 版

该版本于 2022 年 1 月 6 日发布，修复了一个内部问题。

4.8.0 版

该版本于 2021 年 12 月 29 日发布。

改进

v4.8.0 进行了一些内部改进。

问题修复

v4.8.0 修复了以下问题：

iOS Safari 上以观众角色收流时，能听到主播的声音但 client.on("volume-indicator") 回调返回的音量可能为 0。
iOS Safari 上发流时，先调用 setDevice 再调用 setEncoderConfiguration 会报错。

4.7.3 版

该版本于 2021 年 11 月 17 日发布，规避了 iOS 15.1 中 Safari 浏览器上音视频通话被打断后无法恢复播放的问题。

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 毫秒。

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

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

调用 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

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

改进

AES-GCM 加密模式

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

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

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

云代理服务

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 日发布。

新增特性

云代理服务

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

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

4.2.1 版

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

4.2.0 版

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

新增特性

设置区域访问限制

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

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

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

视频传输优化策略

该版本新增 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 方法。

概览​

兼容性说明​

已知问题​

4.18.3 版

4.18.2 版

4.18.1 版

4.18.0 版

4.17.2 版

4.17.1 版

4.17.0 版

4.16.1 版

4.16.0 版

4.15.1 版

4.15.0 版

4.14.2 版

4.14.1 版

4.14.0 版

4.13.0 版

4.12.2 版

4.12.1 版

4.12.0 版

4.11.1 版

4.11.0 版

4.10.2 版

4.10.1 版

4.10.0 版

4.9.4 版

4.9.3 版

4.9.1 版

4.9.0 版

4.8.2 版

4.8.1 版

4.8.0 版

4.7.3 版

4.7.2 版

4.7.1 版

4.7.0 版

4.6.3 版

4.6.2 版

4.6.1 版

4.6.0 版

4.5.0 版

4.4.0 版

4.3.0 版

4.2.1 版

4.2.0 版

4.1.1 版

4.1.0 版

4.0.1 版

4.0.0 版

概览

兼容性说明

已知问题