本页提供 声网 Web SDK 4.x 版本的发版说明。
Web SDK 4.x 是通过 HTML 网页加载的 JavaScript 和 TypeScript 库。你可以使用 SDK 在网页浏览器中调用 API 建立连接,控制音视频通话和直播服务。
详见 Web SDK 兼容性。
Chrome 弃用和删除 Plan B 语义
Chrome 计划弃用和删除 WebRTC 中的 Plan B 语义,详见官方说明。该改动影响声网 Web SDK 版本使用和体验,具体如下:
Web SDK 版本 | 影响范围 |
---|---|
在调用 publish 方法后再调用 switchDevice 方法,出现视频卡顿或无声问题。 |
|
4.0.0-4.0.1 | publish 和 subscribe 方法不生效。 |
如你使用上述版本的 Web SDK,请尽快升级至最新版本。
该版本于 2023 年 9 月 20 日发布。
该版本修复了 SDK 在 Safari 17 上音视频统计数据缺失的问题。
该版本于 2023 年 7 月 11 日发布。
该版本修复了 SDK 加载完成后,在特定情况下触发麦克风和摄像头设备权限申请弹窗的问题。
该版本于 2023 年 7 月 7 日发布。
事件监听支持错误处理
自该版本起,如果你在事件监听器(listener
) 中传入的回调函数在执行时发生错误,SDK 不会中断正常运行,而是捕获异常并在日志中输出错误信息。
优化异步方法的并发控制
该版本优化了异步方法的并发控制。如果以下异步方法出现并发执行的情况,SDK 会按照方法被调用的顺序依次执行,保证一致性:
join
和 leave
publish
和 unpublish
subscribe
和 unsubscribe
以 publish
和 unpublish
为例,如果你在调用 publish
之后立即调用 unpublish
:
unpublish
有可能不生效,即仍然发布成功。该版本修复了在不具备任何可用摄像头或麦克风的设备上,第一次插入外接摄像头或外接麦克风不会触发以下回调的问题:
onCameraChanged
或 AgoraRTC.on("camera-changed")
onMicrophoneChanged
或 AgoraRTC.on("microphone-changed")
该版本于 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
为例:
// 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 消息压缩,可以缩短用户在弱网环境下加入频道的耗时。
其它改进
该版本还有以下改进:
新增
setProxyServer
IBufferSourceAudioTrack
中新增 setAudioBufferPlaybackSpeed
方法和 playbackSpeed
属性
IAgoraRTC
类中新增以下继承自 EventEmitter
类的方法:
on
off
once
getListeners
removeAllListeners
"camera-changed"
"microphone-changed"
"playback-device-changed"
"autoplay-failed"
"security-policy-violation"
v4.18.0 修复了以下问题:
renewToken
方法生成新的 Token 后,SDK 在尝试重连时依然使用已过期的 Token 加入频道的问题。该版本于 2023 年 4 月 19 日发布。
该版本修复了 getCurrentFrameData
方法返回值异常的问题。
该版本于 2023 年 4 月 19 日发布。
为兼容 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")
如需开启该功能,请联系技术支持。
新增
ScreenVideoTrackInitConfig
中的 displaySurface
(替代 screenSourceType
)、selfBrowserSurface
、surfaceSwitching
和 systemAudio
属性CustomVideoTrackInitConfig
中的 width
、height
、frameRate
属性LocalVideoTrack.setEncoderConfiguration
该版本于 2023 年 3 月 22 日发布。
为进一步减小包体积,该版本移除了 SDK 内置的美颜模块,并且删除了 setBeautyEffect
。如果你需要实现美颜功能,声网推荐你使用效果升级、性能更优的美颜插件。详见使用美颜插件(Beta)。
千人主播(Beta)
自 v4.17.0 起,单个频道可支持最多 1000 位主播同时在线并同时发布音视频流,观众人数无限制,每位主播或观众最多可同时订阅 50 位主播。
如需启用该功能,请联系 sales@agora.io。
本地合图(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 浏览器上体验该优化。
其它改进
该版本还有以下改进:
新增
ILocalVideoTrack.replaceTrack
删除
ILocalVideoTrack.setBeautyEffect
v4.17.0 修复了在 iOS 14.7 及以上版本的 Safari 浏览器上,反复订阅、取消订阅多路音频流可能导致听不到远端用户声音的问题。
该版本于 2023 年 2 月 8 日发布。
该版本修复了使用 v4.16.0 版本的 SDK 时,水晶球统计的视频卡顿率异常升高的问题。
该版本于 2023 年 1 月 5 日发布。
混合云或私有化平台
v4.16.0 新增 setLocalAccessPointsV2
方法,用于配置声网混合云或私有化平台的相关服务。你可以联系 sales@agora.io 了解和部署声网混合云或声网私有化平台。
兼容 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 还有以下改进:
v4.16.0 修复了以下问题:
uid
为 0 的问题。 新增
IAgoraRTCClient.setLocalAccessPointsV2
该版本于 2022 年 12 月 2 日发布。
该版本修复了在 iOS 13.7 上接收的音频流无声的问题。
该版本于 2022 年 11 月 10 日发布。
云代理服务默认采用 Force UDP 模式
v4.15.0 将 startProxyServer
方法的 mode
参数默认值改为 3
,即 Force UDP 云代理模式。在该模式下,SDK 始终通过 UDP 协议传输数据。详情参考使用云代理服务。
音强选流(Beta)
v4.15.0 新增音强选流功能。该功能开启后,声网服务器会根据音量大小对接收端已订阅的音频流进行筛选,选出 N 路音量最大的音频流传输至接收端。N 默认为 3 路,如需自定义设置 N,请联系技术支持。
同时,声网还支持发流端自定义设置是否参与音强选流,不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下,开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗。
自 v4.15.0 起,Web SDK 在以下版本的浏览器上支持 VP9 视频编解码:
支持的浏览器版本 ① | |
---|---|
桌面端 | |
Android 端 | |
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")
回调的准确性。新增
IAgoraRTC.onSecurityPolicyViolation
该版本于 2022 年 10 月 27 日发布。
该版本修复了在 iOS 14.x 上使用微信浏览器时,订阅的第一路音频流无声的问题。
该版本于 2022 年 10 月 24 日发布。
v4.14.1 修复了以下问题:
该版本于 2022 年 8 月 31 日发布。
getVolumeLevel 准确性优化
自 v4.14.0 起,SDK 校准了 getVolumeLevel
返回的音量值,能更准确地反映音量大小关系。该方法返回的音量值取值范围依然为 [0,1],其中 1 代表理论最大音量。如果你的业务场景依赖 getVolumeLevel
返回的音量值(比如根据音量值显示用户说话的图标),升级 SDK 后你需要关注对应场景中该音量值的变化。
v4.14.0 修复了以下问题:
getRemoteVideoStats
获取的视频解码帧率decodeFrameRate
为 0。LocalVideoTrack.setBeautyEffect
开启美颜后,调用 LocalVideoTrack.unpipe
方法报错。新增
enableContentInspect
client.on("content_inspect_result")
该版本于 2022 年 7 月 25 日发布。
媒体处理插件
自 v4.13.0 起,SDK 支持对远端音视频轨道使用媒体处理插件(本地音视频轨道已经在 v4.10.0 支持)。
声网目前提供以下用于远端音频轨道的插件:
插件 | 说明 | 相关文档 |
---|---|---|
空间音效插件 (Beta) | 用户语音根据位置变化而实时改变,支持声音模糊、空气衰减等效果,打造沉浸式体验。 | 联系 sales@agora.io 了解详情。 |
AI 降噪和虚拟背景
AI 降噪插件和虚拟背景插件由 Beta 发布转变为正式发布(v1.0.0)。
相比之前的版本,v1.0.0 版本的 AI 降噪具有更好的人声保真度、更干净的噪声抑制,并新增了去混响 (Dereverberation) 能力。
Token 过期回调
v4.13.0 完善了 token 过期回调的触发逻辑。如果 token 在设备休眠或断网时过期,当设备恢复并尝试重连时,SDK 会触发 token-privilege-did-expire
事件。
新增
RemoteAudioTrack.pipe
RemoteAudioTrack.unpipe
RemoteVideoTrack.pipe
RemoteVideoTrack.unpipe
该版本于 2022 年 7 月 7 日发布,优化了 SDK 的自动模式(在自动模式下,SDK 优先连接 SD-RTN™ ,如果连接失败,会自动切换到 TCP/TLS 443)。
该版本于 2022 年 6 月 27 日发布,修复了以下问题:
该版本于 2022 年 6 月 15 日发布。
媒体处理插件
媒体处理插件有以下改动:
v4.12.0 修复了在 Safari 上开启双流模式后,调用 Track.setEnabled(false)
、Track.close()
等方法无法关闭摄像头指示灯的问题。
该版本于 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 内使用媒体处理插件。声网当前提供以下插件可与 Web SDK 搭配使用。如需了解如何使用插件,请查看相关文档。
插件 | 说明 | 相关文档 |
---|---|---|
虚拟背景插件 (Beta) | 支持将用户的背景设为纯色、自定义图片或虚化。 | 使用虚拟背景插件 |
AI 降噪插件 (Beta) | 支持降低上百种噪声,减少多人同时说话时的人声失真。 | 使用 AI 降噪插件 |
新增
AgoraRTC.registerExtensions
LocalAudioTrack.pipe
LocalAudioTrack.unpipe
LocalVideoTrack.pipe
LocalVideoTrack.unpipe
该版本于 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 使用该模式。
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")
回调的准确性。v4.9.0 修复了以下问题:
play
播放本地视频轨道、传入的参数是来自另一个窗口的元素时,SDK 会报错。新增
setRemoteDefaultVideoStreamType
client.on("join-fallback-to-proxy")
localVideoTrack.on("video-element-visible-status")
remoteVideoTrack.on("video-element-visible-status")
localVideoTrack.getVideoElementVisibleStatus
remoteVideoTrack.getVideoElementVisibleStatus
该版本于 2022 年 1 月 27 日发布,修复了 iOS 微信浏览器上锁屏后解锁可能会黑屏的问题。
该版本于 2022 年 1 月 6 日发布,修复了一个内部问题。
该版本于 2021 年 12 月 29 日发布。
v4.8.0 进行了一些内部改进。
v4.8.0 修复了以下问题:
client.on("volume-indicator")
回调返回的音量可能为 0。setDevice
再调用 setEncoderConfiguration
会报错。该版本于 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 起支持极速直播。极速直播与互动直播的区别主要在于主播到观众的延时不同:
声网针对不同级别的观众端延时收取不同的费用。详见极速直播的产品概述和计费说明。
你可通过以下两种方式实现低延时观众端:
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
为确保你在有网络访问限制的环境中能够使用声网产品,如果你将 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
的返回值不准确。新增
client.on("is-using-cloud-proxy")
EncryptionMode
新增 "aes-128-gcm"
和 "aes-256-gcm"
该版本于 2021 年 1 月 26 日发布。
云代理服务
该版本优化了声网云代理架构,进一步加强了有网络访问限制的环境中 SDK 的连通性,同时支持限定访问区域。
你可联系 sales@agora.io 或技术支持申请使用优化后的云代理服务,然后调用 startProxyServer
方法将 mode
参数设为 3 实现使用云代理服务。详见使用云代理服务。
该版本于 2020 年 12 月 23 日发布,修复了 client.publish
方法传入非法参数时错误说明抛出异常的问题。
该版本于 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 会在控制台打印警告信息,提醒用户设置强密码,即密码必须满足以下要求:
该版本修复了以下问题:
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
方法。