发版说明

v4.0.0 版

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

升级必看

1. 兼容性变更

v4.0.0 SDK 对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。升级 SDK 后，你需要结合实际业务场景更新 app 代码，详见迁移指南。

• 多频道
• 媒体流发布控制
• 警告码

2. 回调异常处理

自该版本起，为了方便开发者排查自身的集成问题，SDK 不再捕获开发者在 IRtcEngineEventHandler 类回调中自行实现的代码逻辑中的异常。你需要自行处理该异常，否则异常出现时可能引起 app 崩溃。

新增特性

1. 多路媒体流

该版本支持通过设置 ChannelMediaOptions，实现一个 RtcEngine 实例同时采集多路音频源并发布到远端，适应各种业务场景。例如：

• 同时发布单路麦克风采集、自采集的音频流和媒体播放器的音频流。

结合多频道能力，你还可以体验如下功能：

• 将多组音频流通过不同的用户 ID（uid）发布到远端。
• 将多路音频流混音后通过一个用户 ID（uid）发布到远端。

2. 内置媒体播放器

为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 createMediaPlayer 创建媒体播放器后，你可以通过 IMediaPlayer 类的一系列方法体验内置媒体播放器的各类功能：

• 自动播放本地、在线、自定义的媒体资源。
• 预先加载待播放的媒体资源。
• 根据网络情况切换媒体资源的播放线路。
• 将媒体播放器的音频流推送到任意频道、分享给远端用户。
• 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。

3. 新版 AI 降噪

自该版本起，SDK 支持新版 AI 降噪（相对于 v3.7.0 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响（Dereverberation）能力。

4. 超高音质

为还原音频的细节、提升音频的清晰度，该版本新增 ULTRA_HIGH_QUALITY_VOICE。在语聊、歌唱等以人声为主的场景中，你可以调用 setVoiceBeautifierPreset 并使用该枚举体验超高音质。

5. 实时合唱

该版本为实时合唱赋予了如下能力：

• 支持两人及两人以上合唱。
• 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。
• 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。

该版本新增 AUDIO_SCENARIO_CHORUS 枚举来设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。

6. 云市场插件

为在 Agora SDK 的基础上增强实时音视频互动性，该版本支持声网云市场插件的一站式解决方案：

• 方便集成：只需执行简单统一的 API 即可实现模块化功能的集成，将实时互动模块集成效率提高约 95%。
• 可扩展性设计：模块化和可扩展的 SDK 设计风格赋予了 Agora SDK 良好的可扩展性，更有利于开发者基于声网云市场插件生态快速搭建好用的实时互动应用。
• 打造生态系统：可容纳众多开发者的实时音视频 app 社区，提供多种扩展组合。添加并开启云市场插件后，开发者可以实现更为丰富的实时音视频互动功能，详见实现插件功能。
• 助力服务商：支持服务商将技术产品以插件的形式与 Agora SDK 做技术上的融合，在声网云市场中展示并售卖，与 Agora 一起共建开发者的实时互动生态系统。如何开发和发布插件详见服务商流程。

7. 增强的频道管理

为满足各类业务场景对频道管理的需求，该版本在 ChannelMediaOptions 结构体中新增了如下功能：

• 设置或切换多种音频源的发布
• 设置或切换频道场景、用户角色
• 控制音频发布时延

在调用 joinChannel 或 joinChannelEx 时设置 ChannelMediaOptions，明确媒体流发布和订阅行为，例如，是否要主动订阅远端用户的音频流。加入频道后，调用 updateChannelMediaOptions 随时更新 ChannelMediaOptions 中的设置，例如，切换发布的音频源。

8. 设置音频流订阅黑/白名单

该版本新增音频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音频黑白名单中，从而实现订阅/不订阅指定用户的音频流。在多频道场景下，你可以通 RtcEngineEx 类下的同名方法来实现该功能。

• setSubscribeAudioBlacklist：设置音频订阅黑名单。
• setSubscribeAudioWhitelist：设置音频订阅白名单。

如果某个用户同时在音频订阅的黑、白名单中，只有黑名单会生效。

9. 设置音频场景

为方便用户灵活修改音频场景，该版本新增 setAudioScenario 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 （AUDIO_SCENARIO_DEFAULT）切换为高音质场景 （AUDIO_SCENARIO_GAME_STREAMING），你可以调用该方法。

10. 设置本地代理

该本版新增 setLocalAccessPoint 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@agora.io 了解和部署声网混合云或声网私有化平台。

改进

1. 快速切换频道

该版本通过 leaveChannel 和 joinChannel 切换频道即可实现和 v3.7.0 中 switchChannel 一样的切换速度，无需额外调用 switchChannel 方法。

2. 本地人声音调

该版本在 onAudioVolumeIndication 的 AudioVolumeInfo 中新增 voicePitch 参数。你可以通过 voicePitch 获取本地用户的人声音调，从而实现唱歌评分等业务功能。

3. 设备权限管理

该版本新增 onPermissionError 方法，当获取音频采集设备或摄像头权限开启失败时自动上报，用户可根据该回调的提示开启相应的设备权限。