发版说明

v4.1.0 版

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

新增特性

1. 版权音乐

为解决直播、语聊房、在线 K 歌房等场景下歌曲的应用版权问题，该版本新增版权音乐相关 API。你可以通过调用 AgoraMusicContentCenter 、AgoraMusicPlayerProtocol 、AgoraMusicContentCenterEventDelegate 类下的相关 API 实现在实时互动场景中播放版权音乐以及相关功能，例如检索音乐资源、获取音乐榜单及榜单详情、预加载及播放音乐资源、下载歌词及海报等功能。你还可以参考在线 K 歌房来体验搭配了演唱评分、美声音效等一系列功能的线上 K 歌场景化解决方案。

2. 耳机均衡器

该版本新增 setHeadphoneEQParameters 方法，用于调节耳机均衡器的低频和高频参数，主要应用于空间音效场景。如果在调用 setHeadphoneEQPreset 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。

3. MPUDP (MultiPath UDP)

自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在移动端和桌面端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。

4. 多频道管理

该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。

• 新增 muteLocalAudioStreamEx 方法，分别用于取消或恢复发布本地音频流。
• 新增 muteAllRemoteAudioStreamsEx 方法，分别用于取消或恢复订阅所有远端用户的音频流。
• 新增 startRtmpStreamWithoutTranscodingEx、startRtmpStreamWithTranscodingEx、updateRtmpTranscodingEx 和 stopRtmpStreamEx 方法，用于实现多频道场景下的旁路推流。
• 新增startChannelMediaRelayEx、updateChannelMediaRelayEx、pauseAllChannelMediaRelayEx、resumeAllChannelMediaRelayEx 和 stopChannelMediaRelayEx 方法，用于实现多频道场景下的跨频道媒体流转发。
• 新增 leaveChannelEx [2/2] 方法，相较于 leaveChannelEx [1/2] 方法新增了 options 参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。

5. 日志上传

使用声网私有媒体服务器的场景下，为支持用户在调用 setLocalAccessPoint 方法时的进阶设置，该版本在 AgoraLocalAccessPointConfiguration 中新增 advancedConfig 成员参数，该参数支持如下设置：

logUploadServer：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。

6. 用户角色切换

为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 didClientRoleChanged 回调中新增 newRoleOptions 参数，该参数取值如下：

• AgoraAudienceLatencyLevelLowLatency (1): 低延时，属于极速直播。
• AgoraAudienceLatencyLevelUltraLowLatency (2): 超低延时，属于互动直播。

改进

1. 跨频道媒体流转发

该版本对 updateChannelMediaRelay 方法做了如下优化：

• 4.1.0 版本前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码 AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8)，你需要重新调用 updateChannelMediaRelay 方法。
• 4.1.0 版本及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。

2. AIAEC

该版本基于 AI 方法重构了AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景

其他改进

• 降低了推送外部音频源时的上行延迟。
• 提升了会议场景 (AgoraAudioScenarioMeeting) 默认参数配置下的回声消除性能。
• 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。

问题修复

该版本修复了以下问题：

• 调用 startAudioMixing 播放 ipod-library://item 路径的音乐文件失败。
• 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。
• 同时通过 onRecordAudioFrame 回调分别获取的音频数据时间戳不同。
• 调用 getExtensionProperty 失败，返回空字符串。

API 变更

新增

• setHeadphoneEQParameters
• muteLocalAudioStreamEx
• muteAllRemoteAudioStreamsEx
• startRtmpStreamWithoutTranscodingEx
• startRtmpStreamWithTranscodingEx
• updateRtmpTranscodingEx
• stopRtmpStreamEx
• startChannelMediaRelayEx
• updateChannelMediaRelayEx
• pauseAllChannelMediaRelayEx
• resumeAllChannelMediaRelayEx
• stopChannelMediaRelayEx
• leaveChannelEx [2/2]
• AgoraLocalAccessPointConfiguration 中增加 advancedConfig 成员
• didClientRoleChanged 中增加 newRoleOptions
• adjustUserPlaybackSignalVolumeEx
• enableAudioVolumeIndicationEx
• AgoraMusicContentCenter 接口类及其中方法
• AgoraMusicPlayerProtocol 协议及其中方法
• AgoraMusicContentCenterEventDelegate 接口类及其中回调
• AgoraMusic 类
• AgoraMusicChartInfo 类
• AgoraMusicContentCenterConfig 类
• AgoraClimaxSegment 类
• AgoraMusicCollection 类
• AgoraMusicContentCenterPreloadStatus
• AgoraMusicContentCenterStatusCode

废弃

• didApiCallExecute，改用具体方法触发的回调。

删除

• 删除了 AgoraLiveTranscoding 类中的废弃成员参数 backgroundImage 和 watermark
• didReceiveChannelMediaRelayEvent 中删除 AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8)

v4.0.1 版

该版本于 2022 年 9 月 29 日发布。

升级必看

如果你已经使用了以下类或方法，请在升级到该版本后重新调用方法并更新参数设置。

为提高代码易用性，该版本将以下类中 Optional 类型的参数变更为 Bool、Int 等基本数据类型：

• AgoraMediaSource 中的 isAgoraSource 和 isLiveSource 由 Optional 型变为 Bool 型。
• AgoraRtcChannelMediaOptions 中的所有参数类型由 Optional 变为 Bool 型或 Int 型。

新增特性

1. 耳返

该版本新增 getEarMonitoringAudioParams 回调，用于设置耳返音频数据格式，你可以使用自己的音效处理模块对耳返音频数据进行前处理，实现自定义音效。调用 setAudioFrameDelegate 注册音频观测器后，在 getEarMonitoringAudioParams 回调的返回值中设置耳返音频数据格式，SDK 会根据该回调的返回值计算采样间隔，并根据该采样间隔触发 onEarMonitoringAudioFrame 回调。

2. 本地网络连接类型

为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 getNetworkType 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 networkTypeChangedToType 回调，报告当前的网络连接类型。

3. 音强选流

该版本新增音强选流功能。该功能开启后，声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请联系技术支持。

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

4. 空间音效

该版本新增了如下适用于空间音效场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。

• 隔声区域：你可以通过调用 setZones 设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用 setPlayerAttenuation 和 setRemoteAudioAttenuation 方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖 setZones 中的声音衰减系数。
• 多普勒音效：你可以通过设置 SpatialAudioParams 中的 enable_doppler 参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下（比如赛车游戏场景），接收方会体验到明显的音调变化。
• 耳机均衡器：你可以通过调用 setHeadphoneEQPreset 方法使用预设的耳机均衡效果，以改善耳机的听感。

API 变更

新增

• getEarMonitoringAudioParams
• getNetworkType
• AgoraRtcChannelMediaOptions 中新增 isAudioFilterable
• setZones
• setPlayerAttenuation
• setRemoteAudioAttenuation
• muteRemoteAudioStream
• SpatialAudioParams
• setHeadphoneEQPreset
• AgoraHeadphoneEQPreset

修改

• enableDualStreamModeEx

废弃

• startEchoTest [2/3]

v4.0.0 版

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

升级必看

兼容性变更

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

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

新增特性

1. 多路媒体流

该版本通过设置 AgoraRtcEngineKit(Ex) 和 AgoraRtcChannelMediaOptions 实现一个 AgoraRtcEngineKit 实例同时采集多组音频流并发布到远端：

调用 joinChannelByToken 加入首个频道后，多次调用 joinChannelExByToken 加入多个频道，通过不同的用户 ID（localUid）和 AgoraRtcChannelMediaOptions 设置发布指定的流到不同的频道。

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

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

2. 内置媒体播放器

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

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

3. 新版 AI 降噪

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

4. 超高音质

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

5. 空间音效

该版本提供本地直角坐标系计算方案实现空间音效：

• 该方案使用 AgoraLocalSpatialAudioKit 类实现空间音效，通过 SDK 计算远端用户的空间坐标。你需要分别调用 updateSelfPosition 和 updateRemotePosition 更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音效。
  

• 该方案通过 SDK 计算媒体播放器的空间坐标。你需要在 AgoraCloudSpatialAudioKit 或 AgoraLocalSpatialAudioKit 类中分别调用 updateSelfPosition 和 updatePlayerPositionInfo 更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音效。
  

6. 实时合唱

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

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

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

7. 云市场插件

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

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

8. 增强的频道管理

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

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

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

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

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

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

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

10. 设置音频场景

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

11. 设置本地代理

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

改进

1. 快速切换频道

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

2. 本地人声音调

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

3. 设备权限管理

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