文档中心
语音通话 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

发版说明

更新时间 2023/03/13 03:17:19

本文提供声网音频 SDK 的发版说明。

已知问题和局限性

macOS Monterey 12 兼容性

SDK 自 3.4.4 版本起对 macOS Monterey 12 进行了兼容性适配。对 3.2.0（含）及 3.4.3（含）之间的 SDK 版本，在 macOS Monterey 12 上高概率会发生崩溃。为避免该问题，请务必将 SDK 升级至 3.4.4 或之后版本。

USB 设备驱动问题

macOS 上连接 USB 耳麦，可能会出现听不见声音或者声音显示异常等问题，通常为 USB 设备驱动的问题，macOS 上对普通的 USB 支持都不是很友好，建议购买更优质的 USB 耳麦。

Rosetta 转译问题

如果你在 app 中集成的 SDK 版本低于 3.3.0，在搭载 M1 芯片的 Mac 设备上只能使用 Rosetta 转译的方式运行 app，该方式会导致用户频繁进出频道时产生内存泄漏。

如果你希望避免该问题，请升级至 3.3.0 或之后版本，并将 app 适配 x86-64 和 arm64 架构。

3.7.2 版

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

升级必看

为增加 SDK 安全性，该版本对使用的第三方开源库进行如下更新：

  • OpenSSL 库：从 1.1.1l 升级到 1.1.1q。
  • zlib 库：从 1.2.11 升级到 1.2.12。
  • FFmpeg 库：修复了安全漏洞 CVE-2021-38114，CVE-2021-38291。

问题修复

该版本修复了如下问题：

  • 部分网络情况下，SDK 不支持报告端到端丢包率。
  • 本地用户使用 AirPods 进行通话时，可能听到电流杂音。

3.7.1 版

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

新增特性

1. 设置本地代理

该版本新增 setLocalAccessPoint 方法，用于设置本地代理。

调用该方法前，请确保已成功部署声网混合云或声网实时音视频私有化平台。你可以联系 sales@agora.io 了解和部署声网混合云或声网实时音视频私有化平台。

改进

1. 跨频道媒体流转发

该版本优化了 SDK 与跨频道媒体流转发服务器连接机制，提高了跨频道媒体流转发的成功率。

问题修复

该版本修复了如下问题：

  • 虽然远端用户未改变音频状态，但本地用户在断网重连后会收到 remoteAudioStateChangedOfUid(2,6) 回调。
  • 在网络时延过大或路由器不响应 ICMP 包的情况下，reportRtcStats 回调报告的 gatewayRtt 不准确。
  • 偶现用户第一次加频道用时较长。

API 变更

新增

  • setLocalAccessPoint
  • didProxyConnected 中新增支持 localProxyIp 参数
  • AgoraProxyType 中新增 AgoraNoneProxyType(0) 和 AgoraLocalProxyType(3)

3.7.0.2 版

该版本于 2022 年 6 月 6 日发布，提升了 SDK 稳定性。

3.7.0 版

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

升级必看

1. 优化集成 Swift API

Swift 开发者会将声网 SDK 提供的 Objective-C API 通过 Xcode 自动转换成 Swift API 进行集成开发工作。为避免自动转换导致的 API 语义混淆，该版本在头文件中通过 NS_SWIFT_NAME 宏显式定义出每个 Objective-C API 对应的 Swift API 的名称。

使用 Swift API 时需要注意声网定义的如下 Swift API 名与 Xcode 自动转换的 Swift API 名不一致：

声网 Objective-C API 声网定义的 Swift API Xcode 自动转换的 Swift API
AgoraAudioDataFrameProtocol 协议中的 - (BOOL)onRecordAudioFrame:(AgoraAudioFrame* _Nonnull)frame; func onRecordAudioFrame(_ frame: AgoraAudioFrame) -> Bool {} func onRecord(_ frame: AgoraAudioFrame) -> Bool {}

2. 日志路径

自该版本起，在该平台上，关闭沙盒时的 SDK 默认日志路径由 ～/Library/Logs/agorasdk.log 变为 /Users/<username>/Library/Caches/<App Bundle Identifier>/Logs/agorasdk.log。如果升级 SDK，旧日志存放在旧的路径，新日志存放在新的路径。

新增特性

1. 虚拟声卡

调用 enableLoopbackRecording 进行声卡采集时，开发者一般会采用 macOS 系统上常用的虚拟声卡，如 Soundflower、BlackHole。但这些虚拟声卡可能存在不兼容 M1 芯片、不兼容最新系统、维护不及时等问题。

为提升开发者声卡采集体验，声网自研了虚拟声卡 AgoraALD（声网 Audio Loopback Device）。你可以用 AgoraALD 替代你目前使用的虚拟声卡，替代步骤如下：

  1. 安装 AgoraALD，详见 AgoraALD 虚拟声卡。
  2. 将 enableLoopbackRecording 方法中的 deviceName 修改为 "AgoraALD"。

2. 空间音效

该版本新增空间音效功能，用于塑造远端用户声音的方位感和模拟声音在真实世界中的传播过程，实现本地用户听远端用户时的空间音效。

如有需要，请联系 sales@agora.io。

3. 本地语音音调

该版本新增 enableLocalVoicePitchCallback 方法和 reportLocalVoicePitchFrequency 回调，允许 SDK 按设置的时间间隔向 app 报告本地用户的语音音调。

4. 切换用户角色失败回调

该版本新增 didClientRoleChangeFailed 回调，用于报告直播场景下用户切换角色失败的原因和当前的用户角色。

5. 网络连接发生改变的原因

为方便用户了解网络连接发生改变的原因，该版本在 AgoraConnectionChangedReason 中新增如下枚举：

  • AgoraConnectionChangedSameUidLogin(19)：使用相同的 UID 从不同的设备加入同一频道。
  • AgoraConnectionChangedTooManyBroadcasters(20)：频道内主播人数已达上限。该枚举仅在开启 128 人功能后报告。

改进

1. 频道能力提升

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

如有需要，请联系 sales@agora.io。

2. 新版 AI 降噪

自该版本起，声网在原版 AI 降噪功能的基础上增加了新版 AI 降噪功能，拥有更好的降噪效果。如果你希望体验新版 AI 降噪，请联系 sales@agora.io。

3. playEffect 优化

为避免阻塞，该版本优化了 playEffect 的内部实现逻辑，以减少播放音效文件时的卡顿。

4. 音频体验优化

该版本改善了网络突发抖动和高丢包情况下的音频卡顿问题。

5. 传输升级

该版本升级了传输协议和算法，增强了弱网对抗能力。

API 变更

新增

  • enableLocalVoicePitchCallback
  • reportLocalVoicePitchFrequency
  • didClientRoleChangeFailed
  • AgoraConnectionChangedReason 中新增 AgoraConnectionChangedSameUidLogin(19) 和 AgoraConnectionChangedTooManyBroadcasters(20)

废弃

  • 警告码 AgoraWarningCodeSetClientRoleNotAuthorized(119)，改用 AgoraClientRoleChangeFailedReason

3.6.2.1 版

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

修复了因部分动态库错误地强引用 Metal 库导致 SDK 在低于 macOS 10.11 的系统上的崩溃。

3.6.2 版

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

升级必看

动态库格式变更

该版本将 SDK 包中的 .framework 文件变更为 .xcframework 文件。相比 Framework 格式，XCFramework 格式更加灵活，并支持使用 Swift Package Manager 来集成 SDK。

如果你通过官网 SDK 下载链接进行集成，那么在升级到 3.6.2 版时，你需要修改项目：

  1. 在 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单下和项目文件夹中先移除所有 .framework 文件。
  2. 在该菜单下和项目文件夹中添加相应的 .xcframework 文件。

如需了解集成细节，请参考快速开始。

新增特性

1. 使用 CocoaPods 时删除插件

插件指可选集成到项目文件的动态库。自该版本起，通过 CocoaPods 集成 macOS SDK 时，声网支持你通过在 Podfile 中使用 subspecs 字段指定集成你需要的动态库，以排除你不需要使用的插件，从而减少集成 SDK 后的应用体积。示例代码和 subspecs 字段详情请参考减少 App 体积。

2. Wi-Fi 加速

该版本新增支持并默认开启 Wi-Fi 加速功能。当 SDK 发现集成加速插件的 Wi-Fi 路由器后，该功能会正式生效，使路由器合理分配 Wi-Fi 频谱资源，以降低丢包率和时延，从而减少音频卡顿。

当路由器提供加速服务后，SDK 会周期性触发 wlAccStats 回调，报告 Wi-Fi 加速效果，并在 Wi-Fi 连接质量不佳时触发 wlAccMessage 回调，报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

如果你不需要使用 Wi-Fi 加速功能，可以在加入频道前调用 enableWirelessAccelerate(NO) 关闭该功能。

声网提供的 Wi-Fi 加速功能除应用于音频流，还可以应用于其他第三方业务流，如私有信令、课件、RTMP 协议等。如有需要，请联系 sales@agora.io。

改进

1. 云代理

为丰富云代理的适用场景，该版本对云代理类型（proxyType）进行了如下改进：

  • AgoraNoneProxy(0) 由不使用云代理变更为自动模式。在该模式下，SDK 优先连接 SD-RTN™，如果连接失败，自动切换到 TCP/TLS 443。自 v3.6.2 起，SDK 默认开启该模式。
  • 新增 AgoraTcpProxy(2)，表示 TCP（加密）代理模式。在该模式下，SDK 始终通过 TCP/TLS 443 传输数据。

同时，该版本新增 didProxyConnected 回调，报告 SDK 连接代理的状态。例如，当用户调用 setCloudProxy 设置代理并成功加入频道后，SDK 会触发该回调，报告用户 ID，连接的代理类型和从调用 joinChannelByToken 到 SDK 触发该回调的经过的时间。

2. 音频设备检测

为支持在频道内进行音频设备检测，该版本对音频检测相关方法和回调作如下改进：

  • 新增 reportAudioDeviceTestVolume 回调，专门用于报告被检测音频设备的音量信息。

  • startRecordingDeviceTest、startPlaybackDeviceTest 和 startAudioDeviceLoopbackTest 方法由只能在加入频道前调用改为在加入频道前后均可调用，并触发如下回调：

    • 加入频道前调用，SDK 触发 reportAudioVolumeIndicationOfSpeakers 和 reportAudioDeviceTestVolume 回调。两种回调报告的音量信息相同。如果你将 SDK 升级到 3.6.2 或之后版本，建议你使用 reportAudioDeviceTestVolume 回调。

    • 加入频道后调用，SDK 触发 reportAudioDeviceTestVolume 回调。

加入频道后调用 startRecordingDeviceTest、startPlaybackDeviceTest 和 startAudioDeviceLoopbackTest 方法，只能检测当前正在使用的音频设备。

3. 音频录制

该版本扩展了 startAudioRecordingWithConfig 的功能，支持设置录制双声道和更高的音质：

  • 通过在 AgoraAudioRecordingConfiguration 中新增 recordingChannel，允许用户设置录制的音频声道为单声道或双声道。因为实际录制的音频声道与采集的音频声道有关，集成方案也会影响最终录制的音频声道，所以如需通过 startAudioRecordingWithConfig 录制立体声，请联系技术支持协助。
  • 通过在 AgoraAudioRecordingConfiguration.recordingQuality 中新增 AgoraAudioRecordingQualityUltraHigh(3)，允许用户设置录制的音质为超高音质。超高音质是 recordingQuality 中提供的最高音质。当采样率为 32000 Hz，以超高音质录制 10 分钟的 AAC 音频文件时，文件大小约为 7.5 M。

4. 播放音乐文件优化

该版本优化了调用 startAudioMixing 播放音频文件的体验，具体如下：

如果你希望体验这些优化，请确保已集成 AgoraFullAudioFormatExtension.xcframework 动态库。考虑到该库的体积较大，如果你对 app 体积有限制且不需要体验这些优化，你可以在集成 SDK 时自行删除该动态库。详见减少 App 体积。

5. 音频文件格式

该版本新增支持播放如下格式的音频文件：

  • MP4 格式的单音轨在线文件。
  • M4A 和 MP4 格式的多音轨在线文件。

对于 MP4 和 M4A 格式的在线文件，媒体信息（moov）必须在媒体数据（mdat）之前。

问题修复

该版本修复了高抖动网络下的音频卡顿。

API 变更

新增

  • enableWirelessAccelerate
  • wlAccStats
  • wlAccMessage
  • reportAudioDeviceTestVolume
  • AgoraAudioRecordingConfiguration 中新增 recordingChannel
  • AgoraAudioRecordingConfiguration.recordingQuality 中新增 AgoraAudioRecordingQualityUltraHigh(3)
  • didProxyConnected
  • AgoraCloudProxyType 中新增 AgoraTcpProxy(2)

修改

  • startRecordingDeviceTest、startPlaybackDeviceTest、startAudioDeviceLoopbackTest 的调用时序限制
  • AgoraCloudProxyType 中的 AgoraNoneProxy(0) 的行为

3.6.1.1 版

该版本于 2022 年 1 月 16 日发布，修复了 Web 用户恢复发送音频流后，3.6.0 或之后版本的 Native 用户可能听不到 Web 用户声音的问题。

3.6.1 版

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

该版本修复了该问题：对带端口号的 RTMP 推流地址解析异常而导致的推流失败。

3.6.0.1 版

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

问题修复

该版本修复了如下问题：

  • 3.6.0 版将动态库 Agorafdkaac.framework 错误地更名为 AgoraFDKAAC.framework。
  • 使用 CocoaPods 集成 3.6.0 版 SDK 出现崩溃。

3.6.0 版

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

升级必看

旁路推流

为降低旁路推流集成难度，该版本优化了推流 API 设计，并改善了推流客户端和服务端内部对网络问题的处理机制。你可以通过该版本新增的如下方法体验优化后的旁路推流功能：

  • startRtmpStreamWithoutTranscoding: 开始非转码推流。与旧推流方法 addPublishStreamUrl(false) 作用相同。
  • startRtmpStreamWithTranscoding: 开始 CDN 直播推流并设置转码属性。与依次调用旧推流方法 setLiveTranscoding、addPublishStreamUrl(true) 的作用相同。
  • updateRtmpTranscoding: 更新转码属性。与非首次调用旧推流方法 setLiveTranscoding 的作用相同。
  • stopRtmpStream: 结束 CDN 直播推流。与旧推流方法 removePublishStreamUrl 作用相同。

该版本废弃 addPublishStreamUrl、setLiveTranscoding、removePublishStreamUrl 这三个旧推流方法，声网推荐你使用新的推流方法，并参考《旁路推流》更新你的业务代码逻辑。

同时，自该版本起，不管你使用新推流方法还是旧推流方法，你都可以体验如下改进：

  • 推流状态、错误、事件透明：

    • 在 AgoraRtmpStreamingState 状态码中新增 AgoraRtmpStreamingStateDisconnecting(5)：SDK 正在与声网推流服务器和 CDN 服务器断开连接。当你调用 remove 或 stop 方法正常结束推流时，SDK 会依次报告推流状态为 Disconnecting、Idle。

    • 在 AgoraRtmpStreamingErrorCode 错误码中新增如下：

      • AgoraRtmpStreamPublishErrorNotBroadcaster(11)：用户角色不是主播，该用户无法使用推流功能。请检查你的应用代码逻辑。
      • AgoraRtmpStreamPublishErrorTranscodingNoMixStream(13)：非转码推流情况下，调用了 update 或 setLiveTranscoding 方法更新转码属性。请检查你的应用代码逻辑。
      • AgoraRtmpStreamPublishErrorNetDown(14)：主播的网络出错。
      • AgoraRtmpStreamPublishErrorInvalidAppId(15)：你的 App ID 没有使用声网推流服务的权限。请参考前提条件开启推流服务。

    • 在 AgoraRtmpStreamingEvent 事件码中新增如下：

      • AgoraRtmpStreamingEventAdvancedFeatureNotSupport(3)：功能不支持。
      • AgoraRtmpStreamingEventRequestTooOften(4)：预留参数。
      为保障推流质量，请务必根据推流状态码、错误码、事件码对业务逻辑进行处理。

  • 转码推流时，使用 HE-AAC v2 音频编解码器：通过在 AgoraAudioCodecProfileType 中新增 AgoraAudioCodecProfileHEAACv2 实现。

新增特性

1. 跟随系统默认音频设备

为方便开发者灵活控制音频设备的切换，该版本新增如下方法：

  • getDefaultAudioDevice：获取系统默认的音频设备。
  • followSystemPlaybackDevice：设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。
  • followSystemRecordingDevice：设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备。

在 macOS 平台，SDK 初始化后默认使用系统默认的音频设备来播放和采集音频，并始终跟随系统音频设备的变化。如果无需跟随，你可以调用 followSystemPlaybackDevice(YES) 和 followSystemRecordingDevice(NO)。

问题修复

该版本修复了偶现的 Web 端无法听见 Native 端的问题。

API 变更

新增

3.5.2 版

该版本于 2021 年 11 月 25 日发布。

升级必看

加入频道失败时返回的错误码变更

为准确报告加入频道失败的原因，自该版本起，在如下情况，SDK 直接在加入频道方法的返回值中返回 -17(AgoraErrorCodeJoinChannelRejected)：

  • 当已经加入 AgoraRtcEngineKit 频道的用户使用有效的频道名再次调用 AgoraRtcEngineKit 类中的加入频道方法。
  • 当已经加入某个 AgoraRtcChannel 频道的用户再次调用该 AgoraRtcChannel 对象的加入频道方法。

在之前的版本中，发生上述错误时，SDK 可能通过 didOccurError 回调报告错误码 17，或在加入频道方法的返回值中返回 -5(AgoraErrorCodeRefused)。

新增特性

音频通话回路测试

为方便用户自行检查本地音频设备、网络状态能否保障正常发送、接收音频流，该版本新增 startEchoTestWithConfig 方法。你可以在加入频道前调用该方法，以测试用户的音频设备和网络回路是否正常。

相比 startEchoTestWithInterval，startEchoTestWithConfig 可保障测试的安全性，不支持设置返回测试结果的时间间隔。

问题修复

该版本修复了如下问题：

  • 在某些 Android 机型上调用 startAudioMixing 时，远端用户听到的人声和伴奏有轻微的不同步。
  • 用户首次加入频道时偶现回声。

API 变更

该版本新增 startEchoTestWithConfig。

3.5.1 版

该版本于 2021 年 10 月 13 日发布。

新增特性

1. 暂停/恢复跨频道媒体流转发

为方便跨频道连麦中的主播快速暂停或恢复媒体流转发，该版本新增如下方法和和状态码：

  • pauseAllChannelMediaRelay：暂停向所有目标频道转发媒体流。
  • resumeAllChannelMediaRelay：恢复向所有目标频道转发媒体流。
  • AgoraChannelMediaRelayEventPauseSendPacketToDestChannelSuccess(12)：成功暂停向目标频道转发媒体流。
  • AgoraChannelMediaRelayEventPauseSendPacketToDestChannelFailed(13)：暂停向目标频道转发媒体流失败。
  • AgoraChannelMediaRelayEventResumeSendPacketToDestChannelSuccess(14)：成功恢复向目标频道转发媒体流。
  • AgoraChannelMediaRelayEventResumeSendPacketToDestChannelFailed(15)：恢复向目标频道转发媒体流失败。

成功调用 pauseAllChannelMediaRelay 或 resumeAllChannelMediaRelay 方法后，SDK 会触发 didReceiveChannelMediaRelayEvent 回调，并在回调中报告是否成功暂停或恢复媒体流转发。

2. 推送外部音频帧到指定位置

为满足不同场景对外部音频帧的不同处理要求，该版本废弃 pushExternalAudioFrameRawData [1/2] 和 pushExternalAudioFrameSampleBuffer [1/2]，并新增带 sourcePos 参数的 pushExternalAudioFrameRawData [2/2] 和 pushExternalAudioFrameSampleBuffer [2/2] 替代。你可以将外部音频帧推送到音频采集后、编码前或本地播放前的位置。例如，在 KTV 场景中，将歌声推送到音频采集后的位置，将伴奏推送到音频编码前的位置，既让歌声经过 SDK 音频模块的处理，又让伴奏不受 SDK 音频模块的影响。

该版本还新增了 setExternalAudioSourceVolume，你可以设置指定位置的外部音频帧音量。

3. 音乐文件高级设置

为设置音频文件的播放速度和声道模式，该版本新增如下方法：

  • setAudioMixingPlaybackSpeed: 设置音乐文件的播放速度。声网推荐取值范围为 [50,400]，100 表示原始速度。
  • setAudioMixingDualMonoMode: 设置音乐文件的声道模式为原始模式、左声道模式、右声道模式或混合模式。

4. 获取音频文件信息

为获取任意音频文件的信息，该版本废弃 getAudioMixingDuration 并新增 getAudioFileInfo 替代。加入频道后，你可以调用 getAudioFileInfo 并通过 didRequestAudioFileInfo 回调获取指定音频文件的时长等信息。

改进

1. 5G 移动网络的识别和质量测试

该版本新增对 5G 移动网络的识别和质量测试，具体如下：

  • 在 AgoraNetworkType 中新增 AgoraNetworkTypeMobile5G (6) 枚举，当本地网络切换为 5G 时，SDK 触发 networkTypeChangedToType 回调报告该网络连接类型。
  • 支持调用 enableLastmileTest 或 startLastmileProbeTest 测试 5G 网络连接质量。

2. 其他改进

该版本还提升了开启 AI 降噪后使用部分蓝牙耳机时的音频体验。

问题修复

该版本修复了如下问题：

  • AgoraAudioScenarioGameStreaming 场景下，偶现因音乐检测不准确导致的回声或噪声。
  • 本地用户调用 muteAllRemoteAudioStreams，收到 remoteAudioStateChangedOfUid (AgoraAudioRemoteReasonLocalMuted) 15 秒后，错误地收到了 remoteAudioStateChangedOfUid (AgoraAudioRemoteReasonRemoteMuted)。
  • 自 3.4.5 版本起，连续多次调用 joinChannelByToken 方法时，返回值不准确。
  • 加入频道前调用 enableExternalAudioSourceWithSampleRate 不生效。
  • 在部分机型上，使用扬声器播放音频，当扬声器音量设为最大值时，偶现回声。
  • 在频道内调用 enableLocalAudio(NO) 后，SDK 额外触发 localAudioStateChange 回调报告 AgoraAudioLocalStateRecording(1)。

API 变更

新增

  • pauseAllChannelMediaRelay
  • resumeAllChannelMediaRelay
  • AgoraChannelMediaRelayEvent 中新增以下枚举：
    • AgoraChannelMediaRelayEventPauseSendPacketToDestChannelSuccess
    • AgoraChannelMediaRelayEventPauseSendPacketToDestChannelFailed
    • AgoraChannelMediaRelayEventResumeSendPacketToDestChannelSuccess
    • AgoraChannelMediaRelayEventResumeSendPacketToDestChannelFailed
  • pushExternalAudioFrameRawData [2/2]
  • pushExternalAudioFrameSampleBuffer [2/2]
  • setExternalAudioSourceVolume
  • setAudioMixingPlaybackSpeed
  • setAudioMixingDualMonoMode
  • getAudioFileInfo
  • didRequestAudioFileInfo
  • AgoraNetworkType 中新增 AgoraNetworkTypeMobile5G

废弃

  • pushExternalAudioFrameRawData [1/2]
  • pushExternalAudioFrameSampleBuffer [1/2]
  • getAudioMixingDuration

3.5.0.4 版

该版本于 2021 年 9 月 26 日发布，修复了头文件中重复声明 didAudioMuted、didVideoEnabled、didLocalVideoEnabled、firstRemoteVideoDecodedOfUid 函数的问题。

3.5.0.3 版

该版本于 2021 年 9 月 6 日发布，修复了声网 RTC SDK 与声网 RTM SDK 的 AgoraReachability 命名冲突。

3.5.0.1 版

该版本于 2021 年 8 月 4 日发布，修复了：因 AgoraRtcEngineKit 强引用 AgoraRtcEngineDelegate，导致 AgoraRtcEngineDelegate 对象只有在 AgoraRtcEngineKit 销毁时才释放且产生内存堆积。

3.5.0 版

该版本在 AgoraRtcEngineKit 强引用 AgoraRtcEngineDelegate 的情况下会发生内存堆积。如果你设置了 AgoraRtcEngineKit 强引用 AgoraRtcEngineDelegate，声网推荐你跳过该版本，升级到 3.5.0.1 版本。详见 3.5.0.1 版。

该版本于 2021 年 7 月 20 日发布。

改进

在开启 AGC 的场景下，该版本缩短了降噪收敛的时间，从而降低了噪声忽大忽小的波动。

问题修复

该版本修复了如下问题：

  • 特定音频应用场景下，用户先关闭扬声器播放，再加入频道，扬声器被自动开启。
  • 调用 setAudioDataFrame 注册原始音频数据回调，并调用 enableLoopbackRecording 开启声卡采集后，播放本地音频文件出现杂音。
  • 调用 muteLocalAudioStream(YES) 停止发布本地音频后，用户第一次加入频道可以听到远端用户，但退出频道后再次加入频道偶现无法听到远端用户。
  • 本地网络环境较差时，SDK 报告的远端用户的下行网络质量 （rxQuality）不准确。
  • reportRtcStats 回调报告的 memoryTotalUsageRatio 的值不准确。

3.4.6 版

该版本在 AgoraRtcEngineKit 强引用 AgoraRtcEngineDelegate 的情况下会发生内存堆积。如果你设置了 AgoraRtcEngineKit 强引用 AgoraRtcEngineDelegate，声网推荐你跳过该版本，升级到 3.5.0.1 版本。详见 3.5.0.1 版。

该版本于 2021 年 7 月 15 日发布，修复了如下问题：

  • 在 M1 Mac 上，通过 My Mac (Designed for iPad) 方式在 Xcode 12 上运行 app 失败。
  • 连接 UltraStudio Recorder 3G 采集设备后，无法通过 UltraStudio Recorder 3G 采集音频。
  • Objective-C 头文件缺失 nonnull、 _Nullable 修饰符导致运行项目时出现警告。

3.4.5 版

该版本在 AgoraRtcEngineKit 强引用 AgoraRtcEngineDelegate 的情况下会发生内存堆积。如果你设置了 AgoraRtcEngineKit 强引用 AgoraRtcEngineDelegate，声网推荐你跳过该版本，升级到 3.5.0.1 版本。详见 3.5.0.1 版。

该版本于 2021 年 6 月 22 日发布。

升级必看

1. 支持 GCM2 加密

为进一步提升实时音频传输过程的安全性，该版本进行如下优化：

  • 在 AgoraEncryptionMode 中新增 AgoraEncryptionModeAES128GCM2 (7) 和 AgoraEncryptionModeAES256GCM2 (8) 加密模式。新的 GCM 加密模式使用了安全性更高的密钥派生函数，支持设置密钥和盐。
  • 在 AgoraEncryptionConfig 中新增 encryptionKdfSalt 成员，用于为 AgoraEncryptionModeAES128GCM2 (7) 和 AgoraEncryptionModeAES256GCM2 (8) 加密模式设置盐。

此外，该版本将默认的加密模式由 AgoraEncryptionModeAES128XTS (1) 修改为 AgoraEncryptionModeAES128GCM2 (7)。如果你原来使用了默认的加密模式，将 SDK 升级到 v3.4.5 之后，请务必调用 enableEncryption 并将 AgoraEncryptionMode 设置为 AgoraEncryptionModeAES128XTS (1)。

更多介绍见媒体流加密。

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

2. 音频流发布行为变更

为方便用户灵活控制多个频道中的发布状态，该版本对 AgoraRtcChannel 类进行如下优化：

  • 废弃 publish 和 unpublish，并新增 muteLocalAudioStream 作为替代。你可以分别设置音频流的发布状态。
  • 在 AgoraRtcChannelMediaOptions 中新增 publishLocalAudio 成员，默认值为 YES。你可以在加入频道时设置音频流的发布状态。如果用户已在一个频道中发流，则不论用户是主播还是观众，都需要在加入其他频道时设置 publishLocalAudio 为 NO。否则，加入频道会失败。
  • 调用 setClientRole(AgoraClientRoleBroadcaster) 后，本地用户默认发布音频流，无需再调用 publish。
publishLocalAudio = NO 和 muteLocalAudioStream(YES) 的功能相同，所以搭配使用时，后调用的 API 生效。

上述优化也带来了 AgoraRtcEngineKit 类的部分行为变更：

  • AgoraRtcEngineKit 类的 muteLocalAudioStream 对通过 AgoraRtcChannel 类创建的频道不生效，你需要改用 AgoraRtcChannel 类的 muteLocalAudioStream。
  • 通过带 options 参数的 joinChannelByToken 加入频道时，你可以设置音频流的发布状态。
  • 如果使用带 options 参数的 joinChannelByToken 加入频道，muteLocalAudioStream 只有在加入频道后调用才生效。

如果你将 SDK 升级到 v3.4.5 或之后版本，为保证你的业务功能不受影响，声网推荐你修改 muteLocalAudioStream、publish 及 unpublish 的实现。

更多介绍见设置发布状态和加入多频道。

3. 原始音频数据

原始音频数据可用于实现各种自定义音频处理功能，如音频录制和混音。为降低开发难度并支持精准地观测特定节点的音频数据，该版本对原始音频数据 API 进行如下优化：

  • 将 setAudioFrameDelegate 方法改名为 setAudioDataFrame，将 AgoraAudioFrameDelegate 协议名改为 AgoraAudioDataFrameProtocol。

  • 为方便获取传输各阶段预期格式的原始音频数据，在 AgoraAudioDataFrameProtocol 中新增如下回调：

    • getObservedAudioFramePosition：设置音频观测位置。
    • getRecordAudioParams：设置 onRecordAudioFrame 回调数据的格式。
    • getPlaybackAudioParams：设置 onPlaybackAudioFrame 回调数据的格式。
    • getMixedAudioParams：设置 onMixedAudioFrame 回调数据的格式。

如果你将 SDK 升级到 v3.4.5 或更高版本，为保证你的业务功能不受影响，请确保修改 setAudioFrameDelegate 和 AgoraAudioFrameDelegate 的实现。

4. startAudioMixing 变更

为避免阻塞，该版本将 startAudioMixing由同步调用改为异步调用。

改进

1. CDN 推流

为向用户透明更多的 CDN 推流错误和事件，该版本新增如下：

  • 在 rtmpStreamingChangedToState 中新增错误码 AgoraRtmpStreamingErrorCodeUnpublishOK (100): 报告推流已正常结束。当你调用 removePublishStreamUrl 结束推流时，SDK 会返回该错误码和状态码 AgoraRtmpStreamingStateIdle (0)。
  • 在 rtmpStreamingEventWithUrl 中新增事件码 AgoraRtmpStreamingEventUrlAlreadyInUse (2): 报告该推流 URL 已用于推流。如果你想开始新的推流，请使用新的推流 URL。

2. 媒体设备状态回调

为统一不同平台上媒体设备状态的定义，该版本优化了 stateChanged 回调中 state 参数的值：

  • 修改 0 的含义，由“已添加”改为“设备就绪”。
  • 报告设备被拔出的值由 1 修改为 8。

3. 音乐文件状态

在 pauseAudioMixing 后调用 startAudioMixing 时，该版本在报告 localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying, AgoraAudioMixingReasonStartedByUser) 状态之前新增了 localAudioMixingStateDidChanged(AgoraAudioMixingStateStopped, AgoraAudioMixingReasonStoppedByUser) 状态，提示已停止播放音乐文件。

问题修复

该版本修复了如下问题：

  • 在弱网环境下，调用 startAudioMixing 播放在线音乐文件时，偶现 SDK 响应时间过长而引起卡顿。
  • 弱网环境下，偶现用户无法切换角色。
  • 用户在频道内插拔音频设备时，SDK 没有触发媒体设备状态变化回调。

API 变更

新增

修改

废弃

  • AgoraRtcChannel 类的 publish 和 unpublish

3.4.4 版

该版本于 2021 年 6 月 18 日发布，对 macOS Monterey 12 进行了兼容性适配。

3.4.3 版

该版本于 2021 年 6 月 16 日发布，修复了如下问题：

  • Objective-C 头文件缺失 nonnull、 _Nullable 修饰符导致运行项目时出现警告。
  • 在 MacBook Air 系列的部分低端机上，客户端音频录制启动时间超过 5 秒时，音频设备模块（ADM）会无限重启。
  • 调用 startAudioMixing 无法播放扩展名为 m4a 的 MP3 本地音乐文件。
  • 3.0.0+ 版本的用户离开有 3.0.0 之前版本的用户的通信频道，并切换频道场景为直播场景后，在加入下一个频道前切换用户角色为主播，但设置未生效。
  • 特定场景下，用户加入频道 10 分钟后偶现音频延迟。

3.4.2 版

该版本于 2021 年 5 月 11 日发布，修复了特定场景下偶现的崩溃问题。

如果你从教育版本（2.3.4.10x 或 2.9.0.10x）迁移至 3.4.2 及之后版本，为避免兼容性问题，请确保你调用了 setAudioProfile 并将 scenario 设置为 AgoraAudioScenarioEducation。

3.4.1 版

该版本于 2021 年 4 月 22 日发布，修复了如下问题：

  • 在特定的基础变声场景下，出现崩溃。
  • 3.4.0 版中因 Non-public API usage 错误导致应用无法上架 Apple App Store。

3.4.0 版

该版本于 4 月 16 日发布。

升级必看

集成变更

为减少集成 SDK 后的 app 体积，该版本将部分功能以插件列表（命名以 Extension 为后缀）的形式发布，详见插件列表。如果你不需要使用相关插件功能，你可以直接删除对应的插件并重新编译项目。

行为变更

  1. 音乐文件播放状态

为监听音乐文件播放状态改变的原因，该版本对 localAudioMixingStateDidChanged 回调进行如下修改：

  • 将 errorCode 参数修改为 reason 参数。
  • 废弃 AgoraAudioMixingErrorCode，并新增 AgoraAudioMixingReasonCode 替代。通过 AgoraAudioMixingReasonCode，你可以获取播放开始、暂停、停止或失败的原因。
  • 修改 AgoraAudioMixingStateCode 的部分逻辑。例如，循环播放音乐时，播放完成或开始播放都会触发 AgoraAudioMixingStatePlaying 状态。

如果你将 SDK 升级到 v3.4.0 或更高版本，为保证你的业务功能不受影响，声网推荐你修改 localAudioMixingStateDidChanged 的实现。

  1. 调节麦克风采集信号音量

自该版本起，adjustRecordingSignalVolume 仅调节麦克风采集信号音量。如需调节声卡采集信号音量，请改用 adjustLoopbackRecordingSignalVolume。

新增特性

1. 调节声卡采集信号音量

该版本新增 adjustLoopbackRecordingSignalVolume，你可以在 enableLoopbackRecording 后调用该方法调节声卡采集的信号音量。

2. 音效文件播放进度

为控制音效文件的播放进度，该版本新增如下方法：

  • playEffect3: 通过 startPos 参数，在播放音效文件时设置播放位置。
  • setEffectPosition: 在播放音效文件后，设置音效文件的播放位置。
  • getEffectDuration: 获取本地音效文件的总时长。
  • getEffectCurrentPosition: 获取音效文件的播放进度。

同时，该版本废弃 playEffect2，请使用 playEffect3 替代。

改进

1. 音乐文件播放进度

为方便控制音乐文件的播放进度，该版本废弃 startAudioMixing 并新增同名方法替代。新方法允许你通过 startPos 参数在播放音乐文件时设置播放位置。

2. 客户端录音

为在录音时设置录音内容，该版本新增 startAudioRecordingWithConfig 方法并废弃 startAudioRecording2。通过 startAudioRecordingWithConfig 的 config 参数，你可以设置录音音质、内容、采样率及录音文件的存储路径。

该版本还新增了错误码 AgoraErrorCodeAlreadyInRecording(160)。如果你在当前录音结束前再次调用 startAudioRecordingWithConfig，SDK 会报告该错误码。

问题修复

该版本修复了调用 enableSoundPositionIndication(YES) 后 reportAudioVolumeIndicationOfSpeakers 回调的音量信息不准确的问题。

API 变更

新增

修改

废弃

  • startAudioRecording2
  • playEffect2
  • startAudioMixing1
  • AgoraAudioMixingErrorCode

3.3.2 版

该版本于 2021 年 3 月 29 日发布，修复了特定场景下，远端用户长时间无声时，本地用户听远端用户有杂音的问题。

3.3.1 版

该版本于 2021 年 3 月 4 日发布。

新增特性

基础变声

该版本新增 setVoiceConversionPreset 方法改变用户的声音。你可以把男声变得低沉、稳重，把女声变得甜美、中性。详见设置人声效果。

改进

1. AES-GCM 加密模式

在安全要求高的场景中，为保证数据的保密性、完整性和真实性，提高数据加密的计算效率，该版本在 AgoraEncryptionMode 中新增如下枚举值：

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

2. 远端音频统计

为监测通话中与音频相关的主观体验，该版本在 remoteAudioStats 中增加 mosValue，报告声网实时音频 MOS（平均主观意见分）评估系统对接收到的远端音频流的质量评分。

API 变更

新增

3.3.0 版

该版本于 2021 年 1 月 22 日发布。

升级必看

1. 集成变更

该版本新增声网基础计算框架 AgoraCore.framework。请参考集成 SDK 将 SDK 集成至你的项目。

2. 订阅行为变更

该版本废弃了 setDefaultMuteAllRemoteAudioStreams，并修改了 mute 相关方法的如下行为：

  • mute 相关方法需要在加入频道或切换频道后调用，否则会不生效。
  • mute 相关方法都能独立控制用户的订阅状态。一起调用 muteAll 为前缀的方法和 muteRemote 为前缀的方法时，后调用的方法会生效。
  • muteAll 为前缀的方法设置是否订阅所有音频流，包含调用时刻之后加入频道的用户的音频流，即 muteAll 为前缀的方法包含了 setDefaultMute 为前缀的方法的功能。声网不推荐一起调用 muteAll 和 setDefaultMute 为前缀的方法，否则设置可能会不生效。

更多介绍见设置订阅状态。

3. 人声状态行为变更

在远端用户的 reportAudioVolumeIndicationOfSpeakers 回调中，该版本将 vad 成员的值由始终为 0 修改为始终为 1。

新增特性

1. 原生支持 M1 芯片

该版本新增对 M1 芯片的原生支持，即同时支持 x86-64 和 arm64 架构。自 v3.3.0 起，集成了 SDK 的 app 可以直接在搭载 M1 芯片的 Mac 设备上运行，无需通过 Rosetta 转译。

2. 频道媒体选项

为方便开发者更灵活地控制媒体流订阅，该版本新增 joinChannelByToken2 和 switchChannelByToken2 方法，支持设置用户加入频道和切换频道时是否订阅频道内所有的远端音频流。

3. 云代理

为提升声网云代理的易用性，该版本新增 setCloudProxy 方法设置云代理并允许你选择连接 UDP 协议的云代理。详见云代理。

4. AI 降噪

为在传统降噪模式的基础上消除非平稳噪声，该版本新增 enableDeepLearningDenoise，用于开启 AI 降噪模式。

开启 AI 降噪前，请将 AgoraAIDenoiseExtension.framework 动态库集成到你的项目文件中。

5. 歌唱美声

在歌唱场景中，为美化歌声并添加混响效果，该版本新增 setVoiceBeautifierParameters，并在 AgoraVoiceBeautifierPreset 中添加 AgoraSingingBeautifier 常量。

你可以调用 setVoiceBeautifierPreset(AgoraSingingBeautifier) 美化男声并添加歌声在小房间的混响效果。如需更多设置，你可以调用 setVoiceBeautifierParameters(AgoraSingingBeautifier, param1, param2) 美化男声或女声，并添加歌声在小房间、大房间或大厅的混响效果。

6. 设置日志文件

为保证日志内容的完整性，该版本在 AgoraRtcEngineConfig 中新增 logConfig 属性，在你初始化 AgoraRtcEngineKit 时可用于设置声网 SDK 输出的日志文件。详见如何设置日志文件。

自该版本起，声网不推荐使用 setLogFile、setLogFileSize 和 setLogFilter 方法设置日志文件。

7. 创建数据流

为了支持歌词同步、课件同步等场景，该版本废弃了原有的 createDataStream 方法，并使用新的同名方法替代，用于创建数据流，并设置数据流是否与发布到声网频道内的音频流同步以及接收到的数据是否有序。

改进

1. 原始音频数据

该版本补齐了 macOS 平台的原始音频数据接口。你可以从原始音频数据接口获取原始音频数据，并进行前处理或后处理，获取想要的播放效果。

  • setAudioFrameDelegate
  • onRecordAudioFrame
  • onPlaybackAudioFrame
  • onMixedAudioFrame
  • onPlaybackAudioFrameBeforeMixing

2. 远端音频统计

为方便监测通话中与音频有关的主观体验，该版本在 AgoraRtcRemoteAudioStats 中增加 qoeQuality 和 qualityChangedReason，报告接收远端音频时的体验质量以及体验质量较差的原因。

API 变更

新增

废弃

  • setDefaultMuteAllRemoteAudioStreams
  • setLogFile
  • setLogFileSize
  • setLogFilter
  • createDataStream

3.2.1 版

该版本于 2020 年 12 月 17 日发布，修复了如下问题：

  • IPv6 场景下的高概率崩溃问题。
  • Native 音频 SDK 的客户端与 Web 客户端互通时，Web 客户端持续报告 Client.on(disable-local-video)或 Client.on(mute-video) 回调。

3.2.0 版

该版本于 2020 年 11 月 30 日发布。

升级必看

1. 集成变更

自该版本起，SDK 包中新增以下文件：

  • Agorafdkaac.framework: Fraunhofer FDK AAC 动态库。
  • AgoraSoundTouch.framework: SoundTouch 动态库。

如果你将 SDK 升级到 v3.2.0 或更高版本，请务必参考下述步骤在集成 SDK 时添加上述动态库：

  1. 将上述文件拷贝至 AgoraRtcKit.framework 所在文件夹中。
  2. 打开 Xcode，进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单，点击 +，再点击 Add Other… 添加 Agorafdkaac.framework 和 AgoraSoundTouch.framework，并确保动态库的 Embed 属性为 Embed & Sign。

2. 云代理

该版本优化了声网云代理架构。如果你已经在使用云代理，为避免新 SDK 和老云代理的兼容性问题，请在升级 SDK 前联系技术支持。详见云代理。

3. 安全合规

声网已通过 ISO 27001、ISO 27017、ISO 27018 国际认证，为全球用户提供安全可靠的实时互动云服务。详见 ISO 证书。

同时，为支持传输层加密，该版本新增 TLS（Transport Layer Security）加密和 UDP（User Datagram Protocol）加密方式。

传输层加密导致以下指标受到影响：
  • SDK 包体积大小：数据详见《产品概述》。
  • 首帧出图时长：首帧出图时长（中位数）相比 v3.1.0 增加 0 ~ 70 ms。

    • 新增特性

    极速直播

    该版本新增 setClientRole 方法，支持设置观众的延时级别。你可以通过该方法在互动直播和极速直播之间切换：

    • 将观众的延时级别设为超低延时，使用互动直播。
    • 将观众的延时级别设为低延时，使用极速直播。

    详见极速直播产品概述。

    改进

    1. 会议场景

    为提升多人会议的音频体验，该版本在 setAudioProfile 方法中新增 AgoraAudioScenarioMeeting(8)。

    2. 美声与音效

    为提升美声与音效 API 的易用性，该版本废弃 setLocalVoiceChanger 和 setLocalVoiceReverbPreset，并新增如下方法替代：

    • setVoiceBeautifierPreset: 与 setLocalVoiceChanger 相比，该方法删除了小男孩等变声音效和空旷音效。
    • setAudioEffectPreset: 与 setLocalVoiceReverbPreset 相比，该方法新增了小男孩等变声音效、空旷音效、3D 人声音效和电音音效，并删除了摇滚和嘻哈音效。
    • setAudioEffectParameters: 对指定的音效选项进行更细节的设置。该版本支持的音效选项有 3D 人声和电音音效。

    3. 互动直播延时

    互动直播场景下，观众看直播的延时降低了约 500 ms。

    问题修复

    该版本修复了如下问题：

    • 修复了 AirPods 无声问题。
    • 修复了调用 enumerateDevices 时，SDK 不必要地请求麦克风权限。

    API 变更

    新增

    废弃

    • setLocalVoiceChanger
    • setLocalVoiceReverbPreset

    3.1.2 版

    该版本于 2020 年 9 月 15 日发布。

    该版本修复了推流失败的问题。

    3.1.1 版

    该版本于 2020 年 8 月 27 日发布。

    升级必看

    该版本修改了区域访问限制的区域码 AgoraAreaCode，最新区域码如下：

    • AgoraAreaCodeCN: 中国大陆。
    • AgoraAreaCodeNA: 北美区域。
    • AgoraAreaCodeEU: 欧洲区域。
    • AgoraAreaCodeAS: 除中国大陆以外的亚洲区域。
    • AgoraAreaCodeJP: 日本。
    • AgoraAreaCodeIN: 印度。
    • AgoraAreaCodeGLOB:（默认）全球。

    如你此前调用 sharedEngineWithConfig 方法时指定了访问区域，在由之前版本升级至该版本时，请确保使用正确的区域码。

    3.1.0 版

    该版本于 2020 年 8 月 11 日发布。

    新增特性

    1. 发布和订阅状态转换回调

    该版本新增以下回调方便你了解音频流当前的发布及订阅状态，有助于订阅和发布相关的数据统计：

    • didAudioPublishStateChange: 音频发布状态发生改变。
    • didAudioSubscribeStateChange: 音频订阅状态发生改变。

    2. 本地首帧发布回调

    为提示用户本地音频首帧已发布，该版本新增 firstLocalAudioFramePublished 回调。该回调取代 firstLocalAudioFrame 回调，我们推荐你不再使用 firstLocalAudioFrame 回调。

    3. 自定义数据上报

    该版本支持自定义数据上报。如需试用，请联系 sales@agora.io 开通并商定自定义数据格式。

    改进

    1. 指定访问区域完善

    该版本新增以下枚举值，在调用 sharedEngineWithConfig 创建 AgoraRtcEngineKit 实例时提供更多区域选择。指定访问区域后，集成了声网 SDK 的 app 会连接指定区域内的声网服务器。

    • AgoraIpAreaCode_JAPAN: 日本。
    • AgoraIpAreaCode_INDIA: 印度。

    2. 加密

    该版本新增 enableEncryption 方法，用于开启内置加密，并废弃原加密方法：

    • setEncryptionSecret
    • setEncryptionMode

    与原加密方法相比，该方法新增对国密 SM4 加密模式的支持，你可以根据需要选择合适的加密模式。

    3. 通话中质量透明

    该版本进一步扩充了 AgoraRtcLocalAudioStats 类和 AgoraRtcRemoteAudioStats 类的成员，提供更多音频质量相关数据。

    • AgoraRtcLocalAudioStats 类新增 txPacketLossRate，表示本端到声网边缘服务器的物理音频丢包率 (%)。
    • AgoraRtcRemoteAudioStats 类中新增 publishDuration，表示远端音频流的累计发布时长（毫秒）。

    4. 设置音频编码属性

    为提升音频性能，该版本对音频编码码率最大值进行如下优化：

    Profile 3.1.0 版本 3.1.0 版本之前
    AgoraAudioProfileDefault
  • 直播场景: 64 Kbps
  • 通信场景: 18 Kbps
    		•
  • 直播场景: 52 Kbps
  • 通信场景: 18 Kbps
    		•
    AgoraAudioProfileSpeechStandard 18 Kbps 18 Kbps
    AgoraAudioProfileMusicStandard 64 Kbps 48 Kbps
    AgoraAudioProfileMusicStandardStereo 80 Kbps 56 Kbps
    AgoraAudioProfileMusicHighQuality 96 Kbps 128 Kbps
    AgoraAudioProfileMusicHighQualityStereo 128 Kbps 192 Kbps

    5. 日志扩容

    该版本中，声网 SDK 日志文件的默认个数由 2 个增加至 5 个，单个日志文件的默认大小由 512 KB 扩大至 1024 KB。默认情况下，SDK 会生成 agorasdk.log、agorasdk_1.log、agorasdk_2.log、agorasdk_3.log、agorasdk_4.log 这 5 个日志文件。最新的日志永远写在 agorasdk.log 中。agorasdk.log写满后，SDK 会从 1-4 中删除修改时间最早的一个文件，然后将 agorasdk.log 重命名为该文件，并建立新的 agorasdk.log 写入最新的日志。

    6. 音频路由

    为支持在更多设备中播放音频，该版本在 AgoraAudioOutputRouting 枚举中新增 4 个枚举值，支持 USB 外围设备、HDMI 外围设备、DisplayPort 外围设备和 Apple AirPlay。

    问题修复

    该版本修复了特定场景下偶现因设备音频模块未启动，导致的本地录音无声。

    API 变更

    新增

    废弃

    • setEncryptionSecret
    • setEncryptionMode
    • firstLocalAudioFrame

    删除

    警告码: AgoraWarningCodeAdmImproperSettings(1053)

    3.0.1 版

    该版本于 2020 年 5 月 27 日发布。

    升级必看

    macOS 静态库升级动态库

    为提升开发体验，该版本将 SDK 由静态库升级为动态库，不再支持静态库。使用动态库可以提高库的安全等级，方便 app 上传至 App Store，且避免与第三方库产生不兼容等问题。

    如果你由之前版本的静态库升级为当前版本，需要重新集成，详见升级指南。

    新增特性

    1. 调整音乐文件音调

    为方便调整混音时音乐文件的播放音调，该版本新增 setAudioMixingPitch 方法。通过设置该方法的 pitch 参数，你可以升高或降低音乐文件的音调。该方法仅对音乐文件音调有效，对本地人声不生效。

    2. 变声与混响

    为提高用户的音频体验，该版本在 setLocalVoiceChanger 和 setLocalVoiceReverbPreset 中分别新增以下枚举值：

    • 新增了以 AgoraAudioVoiceBeauty 为前缀和以 AgoraAudioGeneralBeautyVoice 为前缀的枚举值，分别实现美音或语聊美声功能。
    • 新增了以 AgoraAudioReverbPresetFx 为前缀的枚举值和 AgoraAudioReverbPresetVirtualStereo，分别实现增强版混响效果和虚拟立体声效果。

    你可以查看进阶功能变声与混响了解使用方法和注意事项。

    3. 远端音频数据后处理多频道支持 (C++)

    在多频道场景下，为方便后处理各频道的远端音频数据，该版本在 IAudioFrameObserver 类中新增 isMultipleChannelFrameWanted 和 onPlaybackAudioFrameBeforeMixingEx。

    成功注册音频观测器后，如果你将 isMultipleChannelFrameWanted 的返回值设为 true，就可以通过上述回调获取多个频道对应的音频数据。在多频道场景下，我们建议你将返回值设为 true。

    问题修复

    • 修复了混音相关问题
    • 修复了 App ID 和 Token 校验相关问题

    API 变更

    该版本新增以下 API：

    3.0.0.2 版

    该版本于 2020 年 4 月 22 日发布。

    新增特性

    设置区域访问限制

    该版本新增 sharedEngineWithConfig 方法，支持在创建 AgoraRtcEngineKit 实例时指定服务器的访问区域。该功能为高级设置，适用于有访问安全限制的场景。目前支持的区域有中国大陆、北美、欧洲、亚洲（中国大陆除外）和全球（默认）。

    指定访问区域后，集成了声网 SDK 的 app 在指定区域使用时，正常情况下会连接指定区域的声网服务器；在非指定区域使用时，会从所在区域和指定区域的服务器地址中，择优选择服务器建立连接。

    问题修复

    该版本修复了音频无声、进频道后蓝牙设备断开、无法频道等问题。

    API 变更

    新增

    sharedEngineWithConfig

    3.0.0 版

    该版本于 2020 年 3 月 4 日发布。

    在该版本对通信场景采用了全新的系统架构，并升级了通信和直播场景下的 last mile 网络策略。在带宽不足时，新的网络策略能充分利用上下行有限带宽提升有效码率，从而增强弱网对抗能力，极大提升了弱网情况下通信和直播场景的终端用户体验。

    由于通信场景采用了新的系统架构，为保证新老版本通信用户的互通兼容，我们使用了回退机制。如果频道内有老版本通信用户加入，则当前版本 (3.0.0) 的终端用户会回退成老版本通信。一旦回退，频道内所有用户都无法享受新版本带来的体验提升。因此我们强烈推荐同步升级所有终端用户到当前版本。

    同时，我们对本地服务端录制进行了升级发布。为确保享受全新架构和网络策略优化带来的好处，使用本地服务端录制的客户，请务必同步升级本地服务端录制 SDK 至 3.0.0 版本。

    新增特性、改进与问题修复详见下文。

    升级必看

    1. 静态库更名与新增动态库

    为与其他平台保持一致，该版本将 SDK 的库名由 AgoraRtcEngineKit 变更为 AgoraRtcKit。如果你由老版本的 SDK 升级至该版本，请务必重新导入类。详细步骤见《快速开始》中的导入类章节。

    同时，为提升开发体验，该版本新增动态库支持。你可以在静态库和动态库之间任选一个进行集成，其中动态库的包名为 Agora_Native_SDK_for_macOS_v3_0_0_VOICE_Dynamic。

    使用动态库可以提高库的安全等级，方便 app 上传至 App Store，且避免与第三方库产生不兼容等问题。如果选择动态库，则需要重新进行集成并导入类。该步骤大约需要 5 分钟。详见《快速开始》中的集成 SDK 和导入类章节。

    下表展示分别使用动态库和静态库生成 ipa 文件过程中各文件体积的差异：
    库类型 ipa 体积 (M) 解压后体积 (M) Frameworks 文件夹体积 (M) 二进制文件体积 (M) Frameworks 文件夹 + 二进制文件总体积 (M)
    动态库 27 56.6 44 2.4 46.4
    静态库 26.5 55.3 30.1 15.1 45.2
    使用动态库集成时，SDK 不再存放于二进制文件中，而是作为一个独立的库存放在 Frameworks 文件夹中。与使用静态库集成相比，二进制文件体积减少了 12.7 M，Frameworks 文件夹体积增加了 13.9 M。

    新增特性

    1. 多频道管理

    为方便用户在同一时间加入多个频道，该版本新增了 AgoraRtcChannel 和 AgoraRtcChannelDelegate 类。通过创建多个 AgoraRtcChannel 对象，用户可以加入各 AgoraRtcChannel 对象对应的频道中，实现多频道功能。

    加入多个频道后，用户可以同时接收多个频道的流，但只能同时在一个频道内发流。该功能适用于用户需要同时接收多个频道的流，或频繁切换频道发流的场景。详细的集成步骤和注意事项，请参考加入多频道。

    2. 调节本地播放的指定远端用户音量

    该版本新增 adjustUserPlaybackSignalVolume 方法，用以调节本地用户听到的指定远端用户的音量。通话或直播过程中，你可以多次调用该方法，来调节多个远端用户在本地播放的音量，或对某个远端用户在本地播放的音量调节多次。

    改进

    1. 音频编码属性

    为满足更高音质需求，该版本调整了直播场景下 AgoraAudioProfileDefault(0) 对应的音频编码属性，详见下表：

    SDK 版本 AgoraAudioProfileDefault(0)
    3.0.0 48 KHz 采样率，音乐编码，单声道，编码码率最大值为 52 Kbps。
    3.0.0 之前 32 KHz 采样率，音乐编码，单声道，编码码率最大值为 44 Kbps。

    2. 质量透明

    为方便开发者获取更多通话统计信息，该版本在 AgoraChannelStats 类中新增 gatewayRtt、memoryAppUsageRatio、memoryTotalUsageRatio 和 memoryAppUsageInKbytes 成员，方便更好地监控通话的质量和通话过程中的内存变动。

    3. 其他提升

    该版本自动开启直播场景下 Native SDK 与 Web SDK 的互通，并废弃原有的 enableWebSdkInteroperability 方法。

    问题修复

    • 修复了混音、音频录制、音频编码、回声等音频问题。
    • 修复了特定场景下偶现的 app 崩溃、日志文件、推流不稳定等问题。

    API 变更

    行为变更

    该版本修改了 macOS 设备连接耳机或蓝牙时的音频路由。修改后的语音路由与 macOS 设备管理器中显示的一致。

    新增

    废弃

    2.9.1 版

    自 2021 年 12 月 8 日起，声网启动对早于 3.0.0 版的音频 SDK、视频 SDK 的退休流程。详见部分服务下架计划。

    该版本于 2019 年 9 月 19 日发布。新增特性与修复问题列表详见下文。

    新增特性

    人声检测

    为判断本地用户是否说话，该版本在启用说话者音量提示 enableAudioVolumeIndication 方法中新增 bool 型的 report_vad 参数。启用该参数后，你会在 reportAudioVolumeIndicationOfSpeakers 回调报告的 AgoraRtcAudioVolumeInfo 结构体中获取本地用户的人声状态。

    改进

    设置客户端录音采样率

    为方便用户设置客户端录音的采样率，该版本废弃了原有的 startAudioRecording 方法，并使用新的同名方法进行取代。新的方法下，录音采样率可设为 16、32、44.1 或 48 kHz。原方法仅支持固定的 32 kHz 采样率，该版本继续保留原方法但我们不推荐使用。

    API 变更

    为提升用户体验，声网 SDK 在该版本中对 API 进行了如下变动：

    新增

    废弃

    • startAudioRecording

    2.9.0 版

    该版本于 2019 年 8 月 16 日发布。新增特性与修复问题列表详见下文。

    升级必看

    1. 旁路推流

    该版本起，声网删除如下接口：

    • configPublisher

    如果你的 App 使用上述接口实现旁路推流功能，请确保将 Native SDK 升级至最新版本，并改用如下接口实现推流：

    新的推流实现方法，详见旁路推流。

    2. 关闭/开启本地音频采集

    为提高通信场景下，本地用户关闭麦克风后听到的音质，该版本在 enableLocalAudio(true) 后，将系统音量修改为媒体音量。调用 enableLocalAudio(false) 后，系统音量自动切换为通话音量。

    新增特性

    1. 快速切换频道

    为方便直播频道中的观众用户快速切换到其他频道，该版本新增 switchChannelByToken 方法。和先调 leaveChannel，再调 joinChannelByToken 相比，该方法能实现更快的频道切换。调用 switchChannelByToken 方法切换到其他直播频道后，本地会先收到离开原频道的回调 didLeaveChannelWithStats，再收到成功加入新频道的回调 didJoinChannel。

    2. 跨频道媒体流转发

    跨频道媒体流转发，指将主播的媒体流转发至其他直播频道，实现主播跨频道与其他主播实时互动的场景。该版本新增如下接口，通过将源频道中的媒体流转发至目标频道，实现跨直播间连麦功能：

    在跨频道媒体流转发过程中，SDK 会通过 channelMediaRelayStateDidChange 和 didReceiveChannelMediaRelayEvent 回调报告媒体流转发的状态和事件。

    该场景的实现方法、API 调用时序、示例代码及开发注意事项，请参考 跨直播间连麦 指南。

    3. 本地及远端音频状态

    为方便用户了解本地及远端的音频状态，该版本新增 localAudioStateChange 和 remoteAudioStateChangedOfUid 回调。新的回调下，本地及远端音频有如下状态：

    • 本地音频：Stopped(0)、Recording(1)、Encoding(2) 和 Failed(3)。状态为 Failed(3) 时，你可以通过 error 参数中返回的错误码定位及排查问题。
    • 远端音频：Stopped(0)、Starting(1)、Decoding(2)、Frozen(3) 和 Failed(4)。你可以在 reason 参数中了解引起远端音频状态发生改变的原因。

    4. 本地音频数据

    为方便更好地了解通话质量，获取更多质量相关数据，该版本新增 localAudioStats 回调，通过 numChannels、sentSampleRate、sentBitrate 参数报告本地音频统计信息。

    5. 远端音频帧拉取

    为提升音频播放体验，该版本新增如下接口，支持使用拉取的方式获取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染，获取想要的音频效果。

    该方法和 onPlaybackAudioFrame 回调相比，区别在于：

    • onPlaybackAudioFrame：SDK 每 10 毫秒通过回调将音频数据传输给 App。如果 App 处理延时，可能会导致音频播放抖动。
    • pullPlaybackAudioFrameRawData / pullPlaybackAudioFrameSampleBufferByLengthInByte：App 主动拉取音频数据。通过设置音频数据，SDK 可以调整缓存，帮助 App 处理延时，从而有效避免音频播放抖动。

    改进

    1. 通话中质量透明

    该版本进一步扩充了 AgoraChannelStats 类的成员：

    • AgoraChannelStats 类：累计发送音频/视频字节数及累计接收音频/视频字节数

    2. 其他改进

    • 优化了 GameStreaming 场景下的音频质量。
    • 优化了通信场景下用户关闭麦克风后听到的音质。

    问题修复

    音频

    • 修复了与 Web 互通时听声辨位过程中出现的声音失真的问题。
    • 修复了测试麦克风时出现的崩溃问题。

    其他

    • 修复了偶现的旁路推流串流的问题。

    API 变更

    为提升用户体验，声网 SDK 在该版本中对 API 进行了如下变动：

    新增

    废弃

    删除

    • configPublisher

    2.8.0 版

    该版本于 2019 年 7 月 8 日发布。新增特性与修复问题列表详见下文。

    新增特性

    1. 全平台支持 String 型的用户 ID

    很多 App 使用 String 类型的用户 ID。为降低开发成本，声网新增支持 String 型的 User account，方便用户通过如下接口直接使用 App 账号加入声网频道：

    对于其他接口，声网沿用 Int 型的 UID。声网 Engine 会维护 UID 和 User account 映射表，你可以随时通过 String user account 获取 UID，或者通过 UID 获取 String user account，无需自己维护映射表。

    为保证通信质量，频道内所有用户需使用同一数据类型的用户 ID，即频道内的所有用户 ID应同为 Int 型或同为 String 型。

    Note：

    • 同一频道内，Int 型的 User ID 和 String 型的 User account 不可混用。目前支持 String 型 User account 的 SDK 如下：

      • Native SDK：v2.8.0 及之后版本
      • Web SDK：v2.5.0 及之后版本

      如果你的频道内有不支持 String 型 User account 的用户，则只能使用 Int 型的 User ID。

    • 如果你使用该版本的 Native SDK 将用户 ID升级至 String 型 User account，请确保所有终端用户同步升级。

    • 如果使用 String 型的 User account，请确保你的服务端用户生成 Token 的脚本已升级至最新版本。如果使用 String 型 User account 加入频道，请确保使用该 User account 或其对应的 Int 型 UID 来生成 Token。你可以调用 getUserInfoByUserAccount 来获取 User account 所对应的 UID。

    2. 音频卡顿回调

    为监控通话过程中的音频传输质量，方便开发者客观体验通信质量，该版本在远端音频统计数据 AgoraRtcRemoteAudioStats 类中新增 totalFrozenTime 和 frozenRate 成员，报告远端用户在加入频道后发生音频的卡顿时长及卡顿率。

    同时，该版本在 AgoraRtcRemoteAudioStats 类中还新增 numChannels、receivedSampleRate 和 receivedBitrate 成员。

    改进

    为方便开发者统计掉线率，该版本在 connectionChangedToState 回调的 AgoraConnectionChangedReason 参数中添加 AgoraConnectionChangedKeepAliveTimeout(14) 成员，表示 SDK 与服务器连接保活超时，引起 SDK 连接状态发生改变。

    修复问题

    • 特定场景下偶现的崩溃问题。

    API 变更

    为提升用户体验，声网在 v2.8.0 版本中对 API 进行了如下变动：

    新增

    废弃

    2.4.1 版

    该版本于 2019 年 6 月 12 日发布。

    该 SDK 首次发版。你可以参考以下文档集成 SDK，实现相应的实时音频功能：

    • 快速集成
    • 校验用户权限
    • 检测通话质量
    • 调整通话音量
    • 播放音效/音乐混音
    • 变声与混响
    • 旁路推流
    • 音频设备测试与切换
    • 云代理服务

    如果你是由之前版本的 macOS 完整包升级到当前的纯音频包，可参考 macOS 完整包发版说明了解音频的相关改进。