本页提供 Agora Web SDK 4.x 版本的发版说明。
Web SDK 4.x 是通过 HTML 网页加载的 JavaScript 和 TypeScript 库。你可以使用 SDK 在网页浏览器中调用 API 建立连接,控制音视频通话和直播服务。
详见 Web SDK 兼容性。
Chrome 弃用和删除 Plan B 语义
Chrome 计划弃用和删除 WebRTC 中的 Plan B 语义,详见官方说明。该改动影响 Agora Web SDK 版本使用和体验,具体如下:
Web SDK 版本 | 影响范围 |
---|---|
在调用 publish 方法后再调用 switchDevice 方法,出现视频卡顿或无声问题。 |
|
4.0.0-4.0.1 | publish 和 subscribe 方法不生效。 |
如你使用上述版本的 Web SDK,请尽快升级至最新版本。
该版本于 2022 年 5 月 9 日发布,修复了以下问题:
该版本于 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@agora.io。
v4.11.0 修复了以下问题:
Promise.finally
调用出错。unpublish
时不传参数会导致调用失败。新增
AgoraRTCClient.massSubscribe
AgoraRTCClient.massUnsubscribe
AgoraRTCClient.on('published-user-list')
ERR_TOO_MANY_BROADCASTERS
ERR_TOO_MANY_SUBSCRIBERS
该版本于 2022 年 3 月 24 日发布,修复了在特定场景下调用 join
会触发代理异常的问题。
该版本于 2022 年 3 月 17 日发布,在 package.json
中补充了对声网插件系统 agora-rte-extension
的 TypeScript 类型定义依赖。如果你使用 TypeScript 进行类型检查,建议将 Typescript 升级至 4.3.2 或以上版本。
该版本于 2022 年 3 月 11 日发布。
支持媒体处理插件
v4.10.0 支持在 SDK 内使用媒体处理插件。Agora 当前提供以下插件可与 Web SDK 搭配使用。如需了解如何使用插件,请查看相关文档。
插件 | 说明 | 相关文档 |
---|---|---|
虚拟背景插件 (Beta) | 支持将用户的背景设为纯色、自定义图片或虚化。 | 使用虚拟背景插件 |
AI 降噪插件 (Beta) | 支持降低上百种噪声,减少多人同时说话时的人声失真。 | 使用 AI 降噪插件 |
新增
AgoraRTC.registerExtensions
LocalTrack.pipe
LocalTrack.unpipe
LocalTrack.processorDestination
该版本于 2022 年 3 月 16 日发布,修复了在 Chrome 隐身模式下的 iFrame 中加载 SDK 时访问 localStorage 报错的问题。
该版本于 2022 年 3 月 3 日发布,修复了一些内部问题。
该版本于 2022 年 2 月 24 日发布,修复了一些内部问题。
该版本于 2022 年 2 月 17 日发布。
指定所有远端用户的视频流类型
v4.9.0 新增 setRemoteDefaultVideoStreamType
方法,用于发流端通过 enableDualStream
开启双流模式后,接收端指定所有远端用户的视频流类型。
云代理服务 Force TCP 模式
v4.9.0 新增支持云代理服务 Force TCP 模式。该模式下,SDK 始终通过 TLS 443 传输数据。你可在调用 startProxyServer
时将 mode
设为 5 使用该模式。
client.on("is-using-cloud-proxy")
回调的准确性。v4.9.0 修复了以下问题:
play
播放本地视频轨道、传入的参数是来自另一个窗口的元素时,SDK 会报错。新增
setRemoteDefaultVideoStreamType
client.on("join-fallback-to-proxy")
该版本于 2022 年 1 月 27 日发布,修复了 iOS 微信浏览器上锁屏后解锁可能会黑屏的问题。
该版本于 2022 年 1 月 6 日发布,修复了一个内部问题。
该版本于 2021 年 12 月 29 日发布。
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>
标签的可见性和不可见原因,排查问题。
v4.8.0 进行了一些内部改进。
v4.8.0 修复了以下问题:
client.on("volume-indicator")
回调返回的音量可能为 0。setDevice
再调用 setEncoderConfiguration
会报错。新增
localVideoTrack.on("video-element-visible-status")
remoteVideoTrack.on("video-element-visible-status")
localVideoTrack.getVideoElementVisibleStatus
remoteVideoTrack.getVideoElementVisibleStatus
该版本于 2021 年 11 月 17 日发布,规避了 iOS 15.1 中 Safari 浏览器上音视频通话被打断后无法恢复播放的问题。
该版本于 2021 年 10 月 14 日发布,有以下改动:
videoTrack.play(element, {mirror: true})
播放视频时可能出现黑屏的问题,详见问题说明。AgoraRTC.checkSystemRequirements()
返回 false
的问题。该版本于 2021 年 9 月 13 日发布,修复了在 Safari 11 和 iPad Chrome 浏览器上的一些问题。
该版本于 2021 年 9 月 1 日发布。
自 v4.7.0 起,如果你启用媒体流加密,用户离开频道后,SDK 会自动关闭加密并重置加密设置。如需重新开启加密,你需要在用户再次加入频道前调用 setEncryptionConfig
方法。
v4.7.0 进行了以下改进:
getVolumeLevel
方法获取到的音量的准确性。v4.7.0 修复了以下问题:
LocalAudioTrack.setVolume
调整本地音量后,本地用户无法感知到音量变化。LocalAudioTrack.setDevice
返回的 Promise 可能一直处于 pending 状态。该版本于 2021 年 8 月 10 日发布,修复了一个偶现问题:本地关闭标签页或浏览器后,远端没有立即收到 user-left
事件。
该版本于 2021 年 7 月 30 日发布,修复了 SDK 内部存在未销毁的 Media Player 的问题。由于 Chrome 92 新增了一个页面最多创建 75 个 Media Player 的限制,数次播放轨道后,SDK 内未销毁的 MediaPlayer 会导致当前页面无法继续播放。
该版本于 2021 年 7 月 21 日发布,修复了一个内部错误。
该版本于 2021 年 7 月 16 日发布。
极速直播
Web SDK 自 v4.6.0 起支持极速直播。极速直播与互动直播的区别主要在于主播到观众的延时不同:
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
方法没有立即生效。新增
localTrack.setMuted
onAutoplayFailed
ClientConfig
中新增 clientRoleOptions
参数setClientRole
方法新增 options
参数废弃
onAudioAutoplayFailed
该版本于 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
设置不生效。getRemoteVideoStats
方法获取到的视频分辨率仍然是大流的分辨率。remoteAudioTrack.setVolume
修改音量后,暂停播放再恢复播放,音量修改失效。localAudioTrack.setVolume
没有生效。新增
processExternalMediaAEC
ClientConfig
中新增 clientRoleOptions
参数setClientRole
方法新增 options
参数setEncryptionConfig
新增 salt
参数EncryptionMode
新增 "aes-128-gcm2"
和 "aes-256-gcm2"
属性setArea
方法新增 excludedArea
参数该版本于 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
的返回值不准确。新增
client.on("is-using-cloud-proxy")
EncryptionMode
新增 "aes-128-gcm"
和 "aes-256-gcm"
该版本于 2021 年 1 月 26 日发布。
云代理服务
该版本优化了 Agora 云代理架构,进一步加强了有网络访问限制的环境中 SDK 的连通性,同时支持限定访问区域。
你可联系 sales@agora.io 或技术支持申请使用优化后的云代理服务,然后调用 startProxyServer
方法将 mode
参数设为 3 实现使用云代理服务。详见使用云代理服务。
该版本于 2020 年 12 月 23 日发布,修复了 client.publish
方法传入非法参数时错误说明抛出异常的问题。
该版本于 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 会在控制台打印警告信息,提醒用户设置强密码,即密码必须满足以下要求:
该版本修复了以下问题:
setEnabled(false)
禁用该轨道,发布会失败且无法恢复。BufferSourceAudioTrack
的声音失真。onMicrophoneChanged
、onCameraChanged
或 onPlaybackDeviceChanged
),之后再有设备变更时才会触发设备变更事件。新增
AgoraRTC.setArea
localVideoTrack.setOptimizationMode
AgoraRTCClient.getRemoteNetworkQuality
更新
AgoraRTCClient.startProxyServer
方法的 mode
参数类型由 boolean
改成 number
该版本于 2020 年 10 月 27 日发布。该版本修复了以下问题:
event_network_quality
回调的准确性。createCameraVideoTrack
的调用无法结束。unsubscribe
取消订阅某远端用户的一路未发布的轨道后,后续对该用户的订阅和取消订阅操作都失效。setEnabled
方法启用和禁用视频轨道的消耗。client.getLocalVideoStats
方法的偶现报错。该版本于 2020 年 9 月 4 日发布。
客户端截图
v4.1.0 新增 getCurrentFrameData
方法,用于获取当前渲染的视频帧数据。
音频播放设备管理
v4.1.0 新增了以下方法和回调,用于音频播放设备的管理:
setPlaybackDevice
: 用于设置音频播放设备,比如扬声器。该方法仅支持 Chrome 浏览器。getPlaybackDevices
: 用于获取可用的音频播放设备。onPlaybackDeviceChanged
: 用于提示有音频播放设备被添加或移除。network-quality
事件的准确性。checkVideoTrackIsActive
不准确。setEnabled
可能失败。UNEXPECTED_RESPONSE: ERR_SUBSCRIBE_REQUEST_INVALID
。新增
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
等方法来获取本地和远端的媒体质量信息。该版本于 2020 年 7 月 18 日发布,该版本修复了以下问题:
该版本于 2020 年 7 月 15 日发布。
v4.0.0 删除了 setMute
方法,新增 setEnabled
方法来实现启用或禁用本地轨道。这样做的好处在于:
Client.on("user-mute-updated")
回调。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
方法创建视频轨道时选择视频画面是清晰优先还是流畅优先:
通过
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")
回调不准。新增
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
方法。