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

发版说明

更新时间 2023/08/21 08:05:25

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

已知问题

macOS Monterey 12 兼容性

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

iOS 15 兼容性

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

Rosetta 转译问题

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

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

3.7.1 版

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

新增特性

设置本地代理

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

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

超分辨率

该版本废弃 EnableRemoteSuperResolution 方法，并新增同名方法，用于开启超分辨率功能。即对接收到的某个远端用户的视频宽和高均扩大为 2 倍像素。

相比废弃方法，新方法中增加 mode 参数。该参数可设为如下值:

  • MANUAL_MODE(0): 表示对你指定的远端用户进行超分辨率处理。
  • AUTO_MODE: 表示对频道内最大的渲染窗口所对应的远端用户进行超分辨率处理。
使用超分辨率前，请确保已集成如下动态库：
  • Android: libagora_super_resolution_extension.so
  • iOS: AgoraSuperResolutionExtension.xcframework
  • macOS: AgoraSuperResolutionExtension.xcframework
  • Windows: libagora_super_resolution_extension.dll
其他注意事项详见 EnableRemoteSuperResolution 文档。

改进

跨频道媒体流转发

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

问题修复

该版本修复了如下问题：

  • 虽然远端用户未改变音频状态，但本地用户在断网重连后会收到 OnRemoteAudioStateChangedHandler(2,6) 回调。
  • 在网络时延过大或路由器不响应 ICMP 包的情况下，OnRtcStatsHandler 回调报告的 gatewayRtt 不准确。
  • 对于共享屏幕的用户，OnNetworkQualityHandler 回调报告的上行网络质量不准确。
  • 偶现用户第一次加频道用时较长。
  • （Android，iOS）偶现崩溃。
  • （Android，iOS） 本地用户使用屏幕共享功能分享第三方应用播放的音频时，远端用户听到回声。
  • （Android）在三星 Galaxy S20+、Note10+ 等特定机型上，采集音量过小。
  • （Android）本地用户开启美颜后，切换前后摄像头时，偶现远端用户看本地用户的视频画面闪现上下颠倒。
  • （iOS）用户接收到的视频画面出现从暗到亮的变化。
  • （iOS）偶现屏幕共享自动结束。
  • （iOS）用户禁止麦克风权限后，OnLocalAudioStateChangedHandler 回调报告的本地音频出错原因与实际不符。
  • （iOS）调用 PlayEffect 或 StartAudioMixing 播放 8 位 PCM 编码的 WAV 格式音频时，偶现崩溃。
  • （macOS）在使用集成显卡的设备上开启屏幕共享时，共享的画面呈现红色、闪烁。
  • （macOS）本地用户开启屏幕共享后，偶现远端用户看到屏幕共享视频卡顿。
  • （macOS）偶现屏幕共享的画面闪烁。
  • （macOS）通过 EnumerateDevices 方法枚举系统中的视频采集设备时，偶现返回的 deviceName 为空。
  • （Windows）用户加入频道后偶现应用卡死。
  • （Windows）本地用户开启屏幕共享后，偶现远端用户几乎听不到本地用户的人声。
  • （Windows）本地用户开启屏幕共享且共享内容包含红色图案时，远端用户看到共享的该红色图案为绿色。

API 变更

新增

  • SetLocalAccessPoint
  • OnProxyConnectedHandler 中新增支持 localProxyIp 参数
  • PROXY_TYPE 中新增 NONE_PROXY_TYPE(0) 和 LOCAL_PROXY_TYPE(3)
  • EnableRemoteSuperResolution [2/2]
  • SUPER_RESOLUTION_STATE_REASON 中新增 SR_STATE_REASON_INSUFFICIENT_PERFORMANCE(4)
  • VIRTUAL_BACKGROUND_SOURCE_STATE_REASON 中新增 VIRTUAL_BACKGROUND_SOURCE_STATE_REASON_INSUFFICIENT_PERFORMANCE(4)

废弃

  • EnableRemoteSuperResolution [1/2]

3.7.0.3 版

该版本基于 3.7.0.1 版开发，于 2022 年 6 月 22 日发布。

该版本修复了如下问题：

  • 在网络时延过大或路由器不响应 ICMP 包的情况下，OnRtcStatsHandler 回调报告的 gatewayRtt 不准确。
  • 对于共享屏幕的用户，OnNetworkQualityHandler 回调报告的上行网络质量不准确。
  • 偶现用户第一次加频道用时较长。
  • 虽然远端用户未改变音频状态，但本地用户在断网重连后会收到 OnRemoteAudioStateChangedHandler(2,6) 回调。
  • （Android，iOS）偶现崩溃。
  • （Android）在三星 Galaxy S20+、Note10+ 等特定机型上，采集音量过小。
  • （Android）本地用户开启美颜后，切换前后摄像头时，偶现远端用户看本地用户的视频画面闪现上下颠倒。
  • （iOS）用户接收到的视频画面出现从暗到亮的变化。
  • （iOS）用户禁止麦克风权限后，OnLocalAudioStateChangedHandler 回调报告的本地音频出错原因与实际不符。
  • （iOS）调用 PlayEffect 或 StartAudioMixing 播放 8 位 PCM 编码的 WAV 格式音频时，偶现崩溃。
  • （macOS）在使用集成显卡的设备上开启屏幕共享时，共享的画面呈现红色、闪烁。
  • （macOS）本地用户开启屏幕共享后，偶现远端用户看到屏幕共享视频卡顿。
  • （macOS）通过 EnumerateDevices 方法枚举系统中的视频采集设备时，偶现返回的 deviceName 为空。
  • （Windows）本地用户开启屏幕共享后，偶现远端用户几乎听不到本地用户的人声。
  • （Windows）用户加入频道后偶现卡死。
  • （Windows）本地用户开启屏幕共享且共享内容包含红色图案时，远端用户看到共享的该红色图案为绿色。

3.7.0.1 版

该版本于 2022 年 5 月 23 日发版。

出于安全合规的要求，该版本默认删除 usesClearTextTraffic 参数。删除后，如果需要在 Android 平台调用 StartAudioMixing 播放 HTTP 格式的在线音乐文件，则需要在项目 AndroidManifest.xml 文件中添加该参数。详见 StartAudioMixing。

3.7.0 版

该版本于 2022 年 4 月 22 日发版。

升级必看

屏幕共享

该版本对 onScreenCaptureInfoUpdated 回调报告的一系列字段进行了更名：

  • cardType 更名为 graphicsCardType
  • FILT_WINDOW_ERROR 更名为 EXCLUDE_WINDOW_ERROR
  • FILT_WINDOW_ERROR_FAIL 更名为 EXCLUDE_WINDOW_ERROR_FAIL
  • FILT_WINDOW_ERROR_NONE 更名为 EXCLUDE_WINDOW_ERROR_NONE

日志路径（macOS）

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

新增特性

视频增强

继基础美颜后，声网新增支持更多视频增强功能：

  • 视频降噪：该功能可以降低视频噪声，提升视频画质。你可以通过 SetVideoDenoiserOptions 方法设置开/关视频降噪和视频降噪效果选项。
  • 暗光增强：该功能可在光线亮度偏低（如背光、阴天、暗场景）和亮度不均匀的环境下自适应调整视频画面的亮度值，恢复或凸显图像的细节信息，提升视频图像的整体视觉效果。你可以通过 SetLowlightEnhanceOptions 方法设置开/关暗光增强和暗光增强效果选项。
  • 色彩增强：该功能可智能调节饱和度和对比度等视频特性，提升视频色彩丰富度和色彩还原度，使视频画面更生动。你可以通过 SetColorEnhanceOptions 方法设置开/关色彩增强和色彩增强效果选项。
视频增强功能对设备性能有一定要求。开启视频增强后，如果设备出现严重发烫等问题，请将视频增强效果选项修改为消耗性能较少的等级或关闭视频增强功能。

Wi-Fi 加速

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

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

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

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

视频截图上传

为满足对视频内容监管的需求，该版本新增 EnableContentInspect 方法，支持开启视频截图上传。成功开启视频截图上传后，SDK 会根据你在该方法中设置的视频截图上传模块和频率对本地用户发送的视频进行截图、上传。截图完成后，声网服务器会以 HTTPS 请求的形式通知你的服务器，并将所有截图发送至你指定的第三方云存储。

开启视频截图上传前，请确保已开通声网视频截图上传服务并集成相关的动态库。

虚拟声卡（macOS）

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

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

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

空间音效

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

如有需要，请联系 sales@shengwang.cn。

屏幕共享（macOS/Windows）

该版本对屏幕共享新增两个功能：

  • 通过 SetScreenCaptureScenario 方法设置屏幕共享场景，如共享文档、视频等。SDK 支持根据你设置的场景调整共享的画质与体验。
  • （macOS）通过 ScreenCaptureParameters 中的 enableHighLight、hightLightWidth、highLightColor 属性对共享的窗口或屏幕设置描边和描边的宽度、颜色。

本地语音音调

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

远端首帧出图回调

该版本在 AgoraChannel 类中新增 OnFirstRemoteVideoFrameHandler 回调，以在多频道场景下向本地用户报告远端用户的首帧视频已渲染。你还可以从该回调中获取远端用户 ID、视频宽度 (px)、高度 (px)、首帧出图时间 (ms)。

切换用户角色失败回调

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

网络连接发生改变的原因

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

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

摄像头控制

该版本新增全套的摄像头控制方法。

改进

频道能力提升

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

如有需要，请联系 sales@shengwang.cn。

虚拟背景

测试结果和用户反馈显示，虚拟背景功能在多种复杂背景环境和多种人物姿态下均提升了实际效果。因此，自该版本起，虚拟背景由 Beta 功能转变为正式功能。

新版 AI 降噪

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

云代理

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

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

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

音频设备检测

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

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

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

    • 加入频道前调用，SDK 触发 OnVolumeIndicationHandler 和 OnAudioDeviceTestVolumeIndicationHandler 回调。两种回调报告的音量信息相同。如果你将 SDK 升级到 3.7.0 或之后版本，建议你使用 OnAudioDeviceTestVolumeIndicationHandler 回调。
    • 加入频道后调用，SDK 触发 OnAudioDeviceTestVolumeIndicationHandler 回调。
加入频道后调用 StartAudioRecordingDeviceTest、StartAudioPlaybackDeviceTest 和 StartAudioDeviceLoopbackTest 方法，只能检测当前正在使用的音频设备。

音频录制

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

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

屏幕共享（macOS）

该版本优化了屏幕采集方式，提升了屏幕采集帧率上限。

该优化仅适用于如下条件：

  • 使用 StartScreenCaptureByDisplayId 共享全屏，且未使用 excludeWindowList 屏蔽窗口。
  • 设备系统高于 10.11。
  • 设备机型为 2012 和以后 MacBook Air，2012 和以后 MacBook Pro，2015 和以后 MacBook。

例如，在符合上述条件的情况下，使用 4K 屏进行屏幕共享，当设置采集分辨率为 720P 时，采集帧率可设为 30 fps。

播放音乐文件优化

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

音频文件格式（iOS/macOS）

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

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

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

playEffect 优化

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

音频体验优化（iOS/macOS/Windows）

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

传输升级

该版本升级了传输协议和算法，增强了弱网对抗能力。同时，优化了多人视频场景的可伸缩视频编码能力，提升了视频体验。

问题修复

该版本修复了如下问题：

  • (iOS )该版本修复了 app 离开频道并退后台一段时间后，再切回前台时低概率性无法重新加入频道的问题。
  • (iOS) 特定场景下，本地用户从桌面切回应用后，可能看远端用户画面模糊。
  • (macOS) 偶现远端用户看不到屏幕共享或看到共享的屏幕闪现黑屏。
  • (macOS 和 Windows)使用 Push 方式自定义视频源时，偶现用户画面的分辨率持续变化。
  • (Android) 特定场景下，使用红米 4A 手机直播时出现滋啦杂声。
  • (macOS) 使用 WPS 应用打开幻灯片，调用 StartScreenCaptureByWindowId 开启对 WPS 应用窗口的共享后，将幻灯片从普通模式切换到演示模式时窗口共享失败，将幻灯片从演示模式切换回普通模式时窗口共享也失败。
  • (Windows) 本地用户处于特定的混响环境下，远端用户可能听本地用户有回声。
  • (iOS) 通过 StartAudioMixing 播放特定的 WAV 音频文件，播放一段时间后会出现无声。
  • (iOS 和 macOS) 高抖动网络下，音频卡顿。
  • (iOS) 弱网环境下，调用 StartAudioMixing 成功后，时隔 3 秒才收到 OnAudioMixingStateChangedHandler 回调。
  • (iOS) 特定场景下，通过 AddVideoWatermark 添加水印，水印颜色与原色不同。
  • (iOS) 偶现崩溃。

API 变更

新增

  • SetVideoDenoiserOptions
  • SetLowLightEnhanceOptions
  • SetColorEnhanceOptions
  • SetScreenCaptureScenario
  • EnableLocalVoicePitchCallback
  • IsCameraZoomSupported
  • IsCameraTorchSupported
  • IsCameraFocusSuppprted
  • IsCameraExposurePositionSupported
  • IsCameraAutoFocusFaceModeEnabled
  • SetCameraZoomFactor
  • GetCameraMaxZoomFactor
  • SetCameraFocusPositionInPreview
  • SetCameraExposurePosition
  • SetCameraTorchOn
  • SetCameraAutoFocusFaceModeEnabled
  • OnAudioDeviceTestVolumeIndicationHandler
  • OnLocalVoicePitchInHzHandler
  • OnClientRoleChangeFailedHandler
  • OnCameraFocusAreaChangedHandler
  • OnCameraExposureAreaChangedHandler
  • AgoraChannel 中的 OnFirstRemoteVideoFrameHandler
  • AudioRecordingConfiguration 中的 recordingChannel
  • ScreenCaptureParameters 中的 enableHighLight, highLightWidth, 和 highLightColor in
  • CONNECTION_CHANGED_REASON_TYPE 中的 CONNECTION_CHANGED_SAME_UID_LOGIN(19) 和 CONNECTION_CHANGED_TOO_MANY_BROADCASTERS(20)
  • AudioRecordingConfiguration.recordingQuality 中的 AUDIO_RECORDING_QUALITY_ULTRA_HIGH(3)
  • OnProxyConnectedHandler
  • TCP_PROXY(2) in CLOUD_PROXY_TYPE

修改

  • OnScreenCaptureInfoUpdatedHandler 回调报告的字段名
  • StartAudioRecordingDeviceTest、StartAudioPlaybackDeviceTest、StartAudioDeviceLoopbackTest 的调用时序限制
  • CLOUD_PROXY_TYPE 中的 NONE_PROXY(0) 的行为

3.6.1.1 版

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

升级必看

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

为准确报告加入频道失败的原因，自该版本起，在如下情况，SDK 返回的错误码由 -5(ERR_REFUSED) 更改为 -17(ERR_JOIN_CHANNEL_REJECTED)：

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

2. 旁路推流

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

  • StartRtmpStreamWithoutTranscoding: 开始非转码推流。与旧推流方法 AddPublishStreamUrl(false) 作用相同。
  • StartRtmpStreamWithTranscoding: 开始 CDN 直播推流并设置转码属性。与依次调用旧推流方法 SetLiveTranscoding、AddPublishStreamUrl(true) 的作用相同。
  • UpdateRtmpTranscoding: 更新转码属性。与非首次调用旧推流方法 SetLiveTranscoding 的作用相同。
  • StopRtmpStream: 结束 CDN 直播推流。与旧推流方法 RemovePublishStreamUrl 作用相同。
该版本废弃 AddPublishStreamUrl、SetLiveTranscoding、RemovePublishStreamUrl 这三个旧推流方法，声网推荐你使用新的推流方法，并参考旁路推流更新你的业务代码逻辑。

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

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

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

    • 将 RTMP_STREAM_PUBLISH_ERROR 改名为 RTMP_STREAM_PUBLISH_ERROR_TYPE，并在 RTMP_STREAM_PUBLISH_ERROR_TYPE 错误码中新增如下：

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

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

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

  • 转码推流时，添加多张水印、背景图片：通过在 LiveTranscoding 结构体中新增 watermarkCount、backgroundImageCount 实现。

  • 转码推流时，设置每张水印、背景图片的图层编号和透明度：通过在 RtcImage 结构体中新增 zOrder 和 alpha 实现。

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

3. 跟随系统默认音频设备 (Windows, macOS)

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

  • GetAudioPlaybackDefaultDevice：获取系统默认的音频播放设备。

  • GetDefaultAudioRecordingDevice：获取系统默认的音频采集设备。

  • FollowSystemPlaybackDevice：设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。

  • FollowSystemRecordingDevice：设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备。

    在 Windows 平台，SDK 初始化后默认使用系统默认的音频设备来播放和采集音频。该版本优化了系统默认音频设备发生变化时，SDK 的默认处理逻辑，具体如下：

  • v3.6.1.1 之前，SDK 仅在以下情况跟随系统默认设备变化：

    • 用户插入音频设备，导致系统默认的音频设备切换为新插入的音频设备。
    • 用户拔出或禁用系统默认的音频设备，且该设备为 SDK 当前使用的音频设备。

  • v3.6.1.1 及之后，SDK 始终跟随系统默认设备变化。如果无需跟随，你可以调用 FollowSystemPlaybackDevice(false) 和 FollowSystemRecordingDevice(false)。

4. 蓝牙规范选择 (iOS)

为确保与蓝牙耳机的连接，自该版本起，当通信场景下的用户或直播场景下的主播使用蓝牙耳机时，SDK 会检测设备是否支持蓝牙免提规范（Hands-Free Profile, HFP）并根据检测结果选择蓝牙规范，具体如下：

  • 在支持 HFP 的设备上，SDK 依然使用蓝牙免提规范（Hands-Free Profile, HFP），通过蓝牙耳机采集和播放音频。
  • 在不支持 HFP 的设备上，SDK 改为使用蓝牙立体声音频传输规范（Advance Audio Distribution Profile, A2DP）协议，通过设备的麦克风采集、蓝牙耳机播放音频。

新增特性

1. 背景虚化

为丰富虚拟背景的效果，该版本新增支持用户调用 EnableVirtualBackground 开启虚拟背景时设置背景虚化。你需要将自定义的背景图类型设为 BACKGROUND_BLUR，并根据用户希望的背景虚化程度设置 blur_degree。

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

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

  • PauseAllChannelMediaRelay：暂停向所有目标频道转发媒体流。
  • ResumeAllChannelMediaRelay：恢复向所有目标频道转发媒体流。
  • RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS(12)：成功暂停向目标频道转发媒体流。
  • RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED(13)：暂停向目标频道转发媒体流失败。
  • RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS(14)：成功恢复向目标频道转发媒体流。
  • RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED(15)：恢复向目标频道转发媒体流失败。

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

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

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

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

4. 音乐文件高级设置

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

  • SetAudioMixingPlaybackSpeed: 设置当前音乐文件的播放速度。声网推荐取值范围为 [50,400]，100 表示原始速度。
  • GetAudioTrackCount: 获取当前音乐文件的音轨数量。
  • SelectAudioTrack: 指定当前音乐文件的播放音轨。指定音轨的索引取值范围为 [0, GetAudioTrackCount())。
  • SetAudioMixingDualMonoMode: 设置当前音乐文件的声道模式为原始模式、左声道模式、右声道模式或混合模式。

5. 获取音频文件信息

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

6. 音视频录制

为方便用户在客户端录制本地音视频，该版本新增 MediaRecorder 类，支持录制以下内容：

  • 本地麦克风采集且经 SDK 编码为 AAC 格式的音频。
  • 本地摄像头采集且经 SDK 编码的视频。

录制生成的文件保存在用户本地。

成功初始化 IRtcEngine 对象后，你可以调用 MediaRecorder 类中的如下方法和回调实现本地音视频录制功能：

  • GetMediaRecorder：注册 MediaRecorderObserver 并获取 MediaRecorder 对象。
  • StartRecording：设置录制的内容、时长、生成文件的格式、回调间隔，并开启本地音视频录制。
  • StopRecording：停止本地音视频录制。
  • initMediaRecorderObserver：注册 MediaRecorder 观测器。
  • OnRecorderStateChangedHandler：录制状态发生改变回调。
  • OnRecorderInfoUpdatedHandler：录制信息更新回调。
在通信频道场景下，该功能与 3.0.1 之前版本的 SDK 不兼容。

7. 视频截图

该版本新增 TakeSnapshot 方法，支持对指定用户的视频进行截图，生成 JPG 格式图片，并保存至指定的路径。成功调用该方法后，SDK 触发 OnSnapshotTakenHandler 回调报告截图是否成功和获取截图的详情。

8. 音视频通话回路测试

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

相比 StartEchoTest [2/3]，StartEchoTest [3/3] 支持测试视频设备，可保障测试的安全性，不支持设置返回测试结果的时间间隔。

9. 超分辨率（Beta） (Android, iOS)

为有效地提升本地用户看到的远端视频画面的分辨率，该版本新增支持超分辨率功能。你可以调用 EnableRemoteSuperResolution 开启超分辨率。SDK 会触发 OnUserSuperResolutionEnabledHandler 回调报告是否已成功开启该功能。如果未成功开启，请通过 reason 排查问题。

使用超分辨率前，请确保已集成相关的动态库，且设备性能、远端用户人数、远端视频原始分辨率均符合要求。详见 EnableRemoteSuperResolution 文档。

10. 打开闪光灯 (Android, iOS)

为支持在 Android 平台上调用 C++ API 打开设备闪光灯，该版本在 C++ 中新增如下 API：

  • IsCameraTorchSupported：检查设备是否支持打开闪光灯。
  • SetCameraTorchOn：设置是否打开闪光灯。

11. 音画同步

同一用户可能使用两个设备分别发送音频流和视频流，为保证接收端听到和看到的音频和视频的时间同步性，该版本新增 SetAVSyncSource 方法。你可以在视频发送端调用该方法，并传入音频发送端的频道名、用户 ID，SDK 会以发送的音频流的时间戳为基准进行自动调节发送的视频流，以保证即使在两个发送端的上行网络情况不一致（如分别使用 Wi-Fi 和 4G 网络）的情况下，也能让接收端听到和看到的音频和视频同步。

改进

1. 音频设备出错

该版本在 LOCAL_AUDIO_STREAM_ERROR 中新增如下错误码：

  • LOCAL_AUDIO_STREAM_ERROR_RECORD_INVALID_ID(9): 报告音频采集设备的 ID 无效。
  • LOCAL_AUDIO_STREAM_ERROR_PLAYOUT_INVALID_ID(10): 报告音频播放设备的 ID 无效。

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

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

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

3. 屏幕共享

  • 屏幕共享场景下，用户会因为硬件不支持而无法在共享屏幕中通过 excludeWindowList 屏蔽指定窗口。该版本新增 OnScreenCaptureInfoUpdatedHandler 回调，会在屏蔽指定窗口失败时触发，向你报告失败的错误码 errCode和用户的显卡类型 cardType。(Windows)

  • 该版本新增 GetScreenCaptureManager 方法供你获取所有可用于共享的屏幕和窗口的对象列表。用户可通过列表中的缩略图直观选择共享某个显示器的屏幕或共享某个窗口。(Windows, macOS)

  • 此前，你需要调用 StartScreenCaptureByScreenRect 通过显示屏在虚拟屏幕上的 Rectangle 坐标共享屏幕。自该版本起，你还可以直接调用 StartScreenCaptureByDisplayId 通过屏幕 ID 开启屏幕共享。(Windows, macOS)

如果用户设备外接其他显示屏，为避免屏幕共享出现问题，请使用 StartScreenCaptureByDisplayId 开启共享，不要使用 StartScreenCaptureByScreenRect。

4. 本地视频出错 (Windows, macOS)

为方便问题排查，该版本在 LOCAL_VIDEO_STREAM_ERROR 中新增如下错误码：

  • LOCAL_VIDEO_STREAM_ERROR_DEVICE_INVALID_ID(10): SDK 无法在视频设备列表中找到该视频设备。请检查视频设备 ID 是否有效。
  • LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_OCCLUDED(13): 待共享的窗口被其他窗口遮挡住，被遮挡住的部分在共享时会被 SDK 涂黑。
  • LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_NOT_SUPPORTED(20): SDK 不支持共享该类型的窗口。

5. 性能改进

通过优化 FEC（Forward Error Correction）编解码，小幅降低视频场景下的 CPU 占用率。

6. 体验改进

通过优化拥塞控制算法，提升弱网环境下视频清晰度和流畅度。

7. 基础美颜

该版本更新了声网基础美颜算法，提升了你通过 SetBeautyEffectOptions 方法开启的基础美颜效果。为平衡美颜效果，该版本将 lighteningLevel（美白程度）的默认值从 0.7 改为 0.6，并在 BeautyOptions 结构体中新增 sharpnessLevel 支持设置锐化程度。

自该版本起，调用 SetBeautyEffectOptions 前，请确保已集成 libagora_video_process_extension.dll 动态库。否则，你无法体验新的声网基础美颜算法带来的基础美颜效果和锐度调节功能，只能体验原来的声网基础美颜算法带来的基础美颜效果。

8. 适配 OpenSL (Android)

该版本适配 OpenSL，以降低音频延时；同时，添加黑名单机制，在部分不支持 OpenSL 的机型上关闭 OpenSL，并开启 Java adm，提高音频功能的稳定性。

9. 其他改进

该版本还进行了如下改进：

  • 使用 Mac 设备的远端用户因调用 LeaveChannel 或网络中断等原因而离开频道后，本地用户看到远端画面停留在最后一帧，而不再是远端视图直接消失。

  • 持续优化虚拟背景的人像边缘效果。

  • 在 CPU 占用率高的情况下，提升了使用声卡采集音频时的音频体验。

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

  • 对屏幕共享进行了画质、延迟、性能优化。(Windows, macOS)

  • 窗口共享功能适配共享更多类型的应用窗口。(Windows)

  • 在自采集 Texture 格式的视频时，增加硬件编码失败回退软件编码的机制，提升视频功能的可用性。(Android)

  • 将你在 macOS 平台上使用 C++ API GetScreenCaptureSources 获取的 sourceId 由 NSNumber指针改为取指针地址的值所转化出的 unsigned int，以减少集成难度。(macOS)

  • 支持 S/PDIF（Sony/Philips Digital Interface）的音频播放设备。(Windows)

  • 为改善使用蓝牙耳机时的音质，该版本优化了 SDK 选择蓝牙规范和音量类型的逻辑：(Android, iOS)

    • 蓝牙规范：自该版本起，SDK 使用的蓝牙规范仅受用户角色影响：

      • 如果通信场景下的用户或直播场景下的主播使用蓝牙耳机，则蓝牙耳机通过蓝牙免提规范（Hands-Free Profile, HFP）采集和播放音频。
      • 如果直播场景下的观众使用蓝牙耳机，则蓝牙耳机通过蓝牙立体声音频传输规范（Advance Audio Distribution Profile, A2DP）播放音频。

    • 音量类型：该版本规范了音量类型。用户使用蓝牙耳机时，SDK 使用的音量类型如下：

      音频应用场景 通信场景下的用户或直播场景下的主播 直播场景下的观众
      DEFAULT 通话音量 媒体音量
      CHATROOM_GAMING 通话音量 通话音量
      GAME_STREAMING 通话音量 媒体音量
      CHATROOM_ENTERTAINMENT 通话音量 通话音量
      EDUCATION 通话音量 媒体音量
      SHOWROOM 通话音量 媒体音量
      MEETING 通话音量 媒体音量

修复问题

该版本修复了如下问题：

  • 对带端口号的旁路推流地址解析异常而导致的推流失败。

  • 使用原始视频数据时，SDK 会在捕捉到本地待渲染的视频帧时异常触发 OnRenderVideoFrameHandler 回调。

  • 使用原始视频数据时，偶现崩溃。

  • 成功注册原始视频数据观测器后，app 在 OnCaptureVideoFrameHandler 回调中进行耗时操作时，远端用户看本地用户的视频出现卡顿。

  • GAME_STREAMING 场景下，偶现因音乐检测不准确导致的回声或噪声。

  • 远端用户在几秒内依次调用 EnableLocalVideo(false)、EnableLocalVideo(true) 关、开本地视频采集或依次调用 MuteLocalVideoStream(true)、MuteLocalVideoStream(false) 停止、恢复发送本地视频后，本地用户看远端用户偶现短暂黑屏。

  • 本地用户调用 MuteAllRemoteAudioStreams，收到 OnRemoteAudioStateChangedHandler(REMOTE_AUDIO_REASON_LOCAL_MUTED) 15 秒后，错误地收到了 OnRemoteAudioStateChangedHandler(REMOTE_AUDIO_REASON_REMOTE_MUTED)。

  • 自 3.4.5 版本起，连续多次调用 JoinChannel 方法时，返回值不准确。

  • 特定场景下，主播使用特定低端机型时，偶现观众看主播视频卡顿。

  • 特定场景下，发送端使用特定的小米和红米机型时，偶现接收端看到视频画面出现马赛克方格。

  • 发送端使用特定的安卓模拟器时，本地视频或接收端看到的视频画面异常。

  • 加入频道前调用 SetExternalAudioSource 不生效。

  • 在频道内调用 EnableLocalAudio(false) 后，SDK 额外触发 OnLocalAudioStateChangedHandler 回调报告 LOCAL_AUDIO_STREAM_STATE_CAPTURING(1)。

  • 用户在高丢包的弱网环境下加入频道，视频码率无法爬升。

  • 特定弱网条件下，视频码率断崖式下降所导致的视频清晰度和流畅度明显下降问题。

  • 本地用户调用 EnableDualStreamMode(false) 后，当该用户从使用 SetVideoSource 自采集 SCREEN 类型的外部视频切换到 SDK 采集，本地会发送视频双流。

  • 开启媒体流加密后，偶现远端用户接收到的视频卡顿。

  • 在某些 Android 机型上调用 StartAudioMixing 时，远端用户听到的人声和伴奏有轻微的不同步。

  • 在此前发布的 3.5.0.3 版 SDK 上，本地用户使用 Push 方式的音频自采集时，远端用户无法听到本地用户。(Windows, Android)

  • 用户共享 QQ 浏览器窗口并切换浏览器 Tab 后，窗口共享停止。(Windows)

  • 同时连接蓝牙耳机和有线耳机，在多次插拔有线耳机后，SDK 不触发 OnAudioRouteChangedHandler 回调。(Android)

  • 插拔音频设备时，SDK 重复触发 OnAudioDeviceStateChangedHandler 回调。(Windows)

  • 使用光纤音箱时出现回声。(Windows)

  • 使用特定 NVIDIA 和 Intel 组合的双显卡，屏幕共享黑屏。(Windows)

  • 部分设备上 Windows 版本识别错误问题。(Windows)

  • 本地用户共享指定窗口时，本地用户发现该窗口被隐藏，远端用户看不到共享的窗口。(Windows)

  • 共享 Foxmail 窗口失败。(Windows)

  • 在部分设备上本地用户调用 EnableLoopbackRecording 开启声卡采集，远端用户听到音频被播放两次。(Windows)

  • 本地用户共享某些应用窗口后，将其他应用窗口前置且覆盖当前共享窗口区域，远端用户看到共享窗口中存在黑色遮挡。(Windows)

  • 本地用户使用 MediaIO 方式的视频自采集时，远端用户接收到的视频画面出现红色闪烁。(Windows)

  • 在搭载 Windows 7 系统的特定机型上，出现崩溃。(Windows)

  • 调用 UpdateScreenCaptureParameters 更新屏幕共享参数配置时，windowFocus 不生效。（Windows, macOS）

  • 加入频道再立即离开频道后，调用 StartAudioDeviceLoopbackTest 开始音频设备回路测试，OnAudioVolumeIndicationHandler 回调报告的 AudioVolumeInfo 数组内容错误。(Windows)

  • 特定机型上，开启虚拟背景功能偶现崩溃。(Android)

  • 特定机型上，使用 OpenSL 偶现杂音问题。(Android)

  • SDK 检测到蓝牙配置异常时触发的蓝牙重启和关闭蓝牙的提示。(Android)

  • 播放原唱歌曲时，调用 SetAudioMixingPitch 调整音调会导致播放的歌曲从原唱切换为伴奏。(Android, iOS)

  • 在 EDUCATION 音频应用场景下，调用 EnableLocalAudio 开启、关闭本地语音采集时，偶现的音量不稳定问题。(Android)

  • 在部分小米机型上调用 SetEnableSpeakerphone 后，无法通过设备的音量按钮调整音量大小。(Android

  • 在部分机型上调用 SetEnableSpeakerphone 时，主线程出现 1～2 秒的卡顿。(Android)

  • 使用 SetLocalVoiceChanger 和 SetLocalVoicePitch 时，偶现 SoundTouch 开源库引起的崩溃。(Android)

  • 使用自采集和外部耳返库时，在加入频道前开启耳返无效。(Android)

  • 在三星部分机型上，调用 AdjustRecordingSignalVolume(0) 失效。(Android)

  • 特定场景下，偶现更新 CDN 推流转码布局失败。(Android)

  • 使用集成了 SDK 的 app 进行实时音视频互动，在接听系统电话之后切换回该 app，该 app 的音频路由发生改变。例如，在该 app 中使用扬声器播放音频，然后使用听筒接听系统电话，在切换回该 app 时音频路由会变成听筒。(Android)

  • 音频属性为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5) 的用户和使用其他音频属性的用户通话时，后者大概率会听到滋啦杂声。(Android)

  • 在部分机型上，使用前置摄像头采集 353 × 288 分辨率的视频时，采集到的视频画面拉伸变形。(iOS)

  • 头文件中重复声明 OnUserMutedAudioHandler、OnUserEnableVideoHandler、OnUserEnableLocalVideoHandler、OnFirstRemoteVideoFrameHandler函数。 (iOS, macOS)

  • 调用 StartAudioMixing 成功播放音乐后，多次调用 SetAudioMixingPosition 设置音乐文件的播放位置，音乐文件大概率会从头播放。(iOS)

  • 开启视频镜像模式后偶现的崩溃。(iOS)

  • 在 Xcode 中打开 Bitcode 设置并集成 AgoraVideoProcessExtension.xcframework 动态库后，应用上传 Apple Store 报错。(iOS)

  • 偶现因系统问题无法正常获取摄像头设备名而导致的摄像头开启失败和视频采集失败。(iOS)

  • 调用 StartAudioMixing 无法播放以 “ipod-library://” 开头的本地 iTunes 音乐文件。(iOS)

  • 在 AUDIO_SCENARIO_CHATROOM_GAMING 的音频场景下，频道内用户将角色由观众切换为主播的瞬间，该用户听滋啦杂音。(iOS)

  • 未播放音频文件就调用 PauseAudioMixing，之后再调用 StartAudioMixing 播放音频文件，播放失败。(iOS)

  • 音频场景下偶现崩溃。(Android, iOS)

  • 在部分低端 iOS 设备上，app 在屏幕共享时退后台后，因占用内存超出限制被系统强制关闭。(iOS)

  • 调用 SetAudioSessionOperationRestriction 后，偶现的远端音频无声。(iOS)

  • 频道内主播将用户角色切换为观众，再切换回主播后，观众听该主播的声音带有变声效果。(iOS)

  • 用户使用第三方音乐播放器播放音乐并设置音频场景为 AUDIO_SCENARIO_CHATROOM_GAMING 后，加入频道会中断第三方音乐播放器播放的音乐。(iOS)

  • 本地用户屏幕共享时，远端用户无法看到共享的视频画面。(iOS)

  • 远端用户看到本地用户共享的屏幕画面闪烁。(iOS, macOS)

  • 屏幕共享且 captureMouseCursor 不为 false 时，内存泄露。 (macOS)

  • 共享全屏窗口后，UpdateScreenCaptureRegion 失效。 (macOS)

  • 在部分机型上，使用扬声器播放音频，当扬声器音量设为最大值时，偶现回声。 (macOS)

  • 用户首次加入频道时偶现回声。 (macOS)

  • 本地用户窗口共享时，偶现远端用户看到共享的视频画面短暂黑屏。 (macOS)

  • 偶现 Web 端无法听见 Native 端。 (macOS)

API 变更

新增

VirtualBackgroundSource 结构体中新增 blur_degree 属性和 BACKGROUND_BLUR_DEGREE 枚举

修改

  • 将枚举RTMP_STREAM_PUBLISH_ERROR 改名为 RTMP_STREAM_PUBLISH_ERROR_TYPE
  • 将 lighteningLevel 的默认值从 0.7 改为 0.6

废弃

  • PushAudioFrame (audioFrame)
  • GetAudioMixingDuration

3.5.0.3 版

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

升级必看

音频路由行为变更

在 Android 上，为提升用户体验，该版本优化了如下 SDK 行为：

  • 当 SDK 使用媒体音量时，音频路由受如下影响：

  • 3.5.0.3 之前，SDK 无法设置音频路由为听筒。

  • 3.5.0.3 及之后，SDK 可以设置音频路由为听筒，但同时 SDK 使用的音量类型会变成通话音量。如果将音频路由再次切换回扬声器，则音量类型会恢复为媒体音量。

    参考如何区分媒体音量和通话音量了解 SDK 使用媒体音量的场景。

  • 如果连接了多个外置音频设备，当用户移除当前播放设备时，音频路由受如下影响：

    • 3.5.0.3 之前，音频不会通过任何路由播放，造成无声问题。
    • 3.5.0.3 及之后，音频路由会按如下优先级设置：倒数第二个连接的外置设备 > ... > 第一个连接的外置设备 > SetEnableSpeakerphone > SetDefaultAudioRouteToSpeakerphone > SDK 默认的音频路由。

改进

1. 视频画质

该版本对采集和接收的视频画质进行了如下改进：

  • 通过对色彩范围的适配，提升采集和接收的视频对比度，以改善画面泛白问题。
  • 在 Windows、Android、iOS上，通过对色彩空间的适配，提升采集和接收的视频色彩丰富度，进一步还原视频色彩。
  • 在 iOS 上，自动开启最佳的视频采集策略，使采集的视频画质（分辨率、帧率、色彩范围等）最优。该改进仅针对采集分辨率不高于 1080P 的部分视频。
  • 在 iOS上，默认开启摄像头自动对焦并动态调整采集行为，以改善画面过曝问题。

2. 虚拟背景（beta）

  • 在 Windows 上，该版本优化了虚拟背景的人像边缘效果。

  • 在 Android 和 iOS 上，新增 EnableVirtualBackground 方法，支持你开启虚拟背景，将用户的背景设为纯色或 PNG、JPG 格式的图片。同时，你可以通过 OnVirtualBackgroundSourceEnabledHandler 回调了解虚拟背景是否成功开启和相应的出错原因。

    使用虚拟背景前，请确保已集成相关的动态库，且设备性能和用户场景符合要求。详见 EnableVirtualBackground 文档 。

3. 其他改进

该版本还进行了如下改进：

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

  • 改善了视频自渲染场景下的出帧平滑度。

  • 在 Android 上，降低了高分辨率（720P 及更高）场景下 CPU 占用率和端到端视频延时。

问题修复

  • 本地网络环境较差时，SDK 报告的远端用户的下行网络质量 （rxQuality）不准确。
  • 调用 MuteLocalAudioStream(true) 停止发布本地音频后，用户第一次加入频道可以听到远端用户，但退出频道后再次加入频道偶现无法听到远端用户。
  • 在 Windows 上，使用 Push 方式自定义视频源的用户接收远端流时，偶现远端音画不同步。
  • 在 Andriod 上，特定场景下，偶现更新旁路推流转码布局失败。
  • 在 iOS 上偶现的崩溃问题。
  • 在 iOS 上，会议场景下，远端用户在频道内开启本地音频采集后，偶现本地用户听远端用户有回声。
  • 在 iOS 上，设置输出视频为 ORIENTATION_MODE_FIXED_PORTRAIT 模式时，分辨率宽高设置颠倒导致的大头问题。
  • 在 macOS 上，特定音频应用场景下，用户先关闭扬声器播放，再加入频道，扬声器被自动开启。
  • 在 macOS 上，调用 RegisterAudioRawDataObserver 注册原始音频数据回调，并调用 EnableLoopbackRecording 开启声卡采集后，播放本地音频文件出现杂音。
  • 在 iOS 和 macOS 上，OnRtcStatsHandler 回调报告的 memoryTotalUsageRatio 的值不准确。
  • 在 Windows、Android、iOS上，远端用户调用 EnableLoopbackRecording 后，偶现本地用户听到自己的回声。

API 变更

修改

3.4.6 版

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

改进

在 Android 和 iOS 上，为提升人脸检测结果的准确性，自该版本起，SDK 在检测到人脸消失后会立即触发 OnFacePositionChangedHandler 回调。

问题修复

该版本修复了如下问题：

  • 在 iOS 上，特定场景下，SDK 初始化时偶现崩溃。
  • 在 iOS 上，调用 StartAudioMixing 时传入经过百分号编码后的 URL，对应的在线音频文件播放失败。
  • 在 macOS 上，无法监听摄像头的热插拔。
  • 在 macOS 上，连接 UltraStudio Recorder 3G 采集设备后，无法通过 UltraStudio Recorder 3G 采集音频。
  • 在 M1 Mac 上，通过 My Mac (Designed for iPad) 方式在 Xcode 12 上运行 app 失败。
  • 特定的 Android 4.4 TV 机型上，开启摄像头失败。
  • 在 Android 上，使用 Type-C 耳机时声音小的问题。

3.4.5 版

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

升级必看

1. 支持 GCM2 加密

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

  • 在 ENCRYPTION_MODE 中新增 AES_128_GCM2 和 AES_256_GCM2 加密模式。新的 GCM 加密模式使用了安全性更高的密钥派生函数，支持设置密钥和盐。
  • 在 EncryptionConfig 中新增 encryptionKdfSalt 成员，用于为 AES_128_GCM2 和 AES_256_GCM2 加密模式设置盐。

此外，该版本将默认的加密模式由 AES_128_XTS 修改为 AES_128_GCM2。如果你原来使用了默认的加密模式，将 SDK 升级到 v3.4.5 之后，请务必调用 EnableEncryption 并将 ENCRYPTION_MODE 设置为 AES_128_XTS。

更多介绍见媒体流加密。

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

2. 媒体流发布行为变更

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

  • 废弃 Publish 和 Unpublish，并新增 MuteLocalAudioStream 和 MuteLocalVideoStream 作为替代。你可以分别设置音频流和视频流的发布状态。

  • 在 ChannelMediaOptions 中新增 publishLocalAudio 和 publishLocalVideo 成员。你可以在加入频道时设置音视频流的发布状态。

  • 调用 SetClientRole(BROADCASTER) 后，本地用户默认发布音视频流。

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

  • IRtcEngine 类的 MuteLocalAudioStream 和 MuteLocalVideoStream 对通过 AgoraChannel 类创建的频道不生效，你需要改用 AgoraChannel 类的 MuteLocalAudioStream 和 MuteLocalVideoStream。
  • 通过带 options 参数的 JoinChannel 加入频道时，你可以设置音视频流的发布状态。
  • 如果使用带 options 参数的 JoinChannel 加入频道，MuteLocalAudioStream 或 MuteLocalVideoStream 只有在加入频道后调用才生效。

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

新增特性

1. 虚拟背景（beta）

在 Windows 和 macOS 上，为满足用户对自定义虚拟背景的需求，该版本新增 EnableVirtualBackground 方法，支持你开启虚拟背景，将用户的背景设为纯色或 PNG、JPG 格式的图片。同时，你可以通过 OnVirtualBackgroundSourceEnabledHandler 回调了解虚拟背景是否成功开启和相应的出错原因。

改进

1. macOS Monterey 12 和 iOS 15 适配

该版本对 macOS Monterey 12 和 iOS 15 进行了兼容性适配。

2. 性能优化

在 Windows 上，声网对该版本 SDK 进行内部线程优化，低端机上 CPU 占用率降低了约 20%。

3. 旁路推流

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

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

4. 媒体设备状态回调

为更准确地报告媒体设备的状态，该版本优化了 OnAudioDeviceStateChangedHandler 和 OnVideoDeviceStateChangedHandler 回调的 deviceState 参数。

在 Windows 上：

  • 将 MEDIA_DEVICE_STATE_ACTIVE (1) 的含义从“设备处于空闲状态”改为“设备正在使用”。

  • 新增 MEDIA_DEVICE_STATE_IDLE (0)，报告设备就绪。

在 macOS 上：

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

5. 音乐文件状态

在 PauseAudioMixing 后调用 StartAudioMixing 时，该版本在报告 OnAudioMixingStateChangedHandler(AUDIO_MIXING_STATE_PLAYING, AUDIO_MIXING_REASON_STARTED_BY_USER) 状态之前新增了 OnAudioMixingStateChangedHandler(AUDIO_MIXING_STATE_STOPPED, AUDIO_MIXING_REASON_STOPPED_BY_USER) 状态，提示已停止播放音乐文件。

问题修复

该版本修复了如下问题：

  • 调用 StartAudioMixing 无法播放扩展名为 m4a 的 MP3 本地音乐文件。
  • 3.0.0+ 版本的用户离开有 3.0.0 之前版本的用户的通信频道，并切换频道场景为直播场景后，在加入下一个频道前切换用户角色为主播，但设置未生效。
  • 特定场景下，用户加入频道 10 分钟后偶现音频延迟。
  • 在弱网环境下，调用 StartAudioMixing 播放在线音乐文件时，偶现 SDK 响应时间过长而引起卡顿。
  • 在 Windows 上，音频场景为 AUDIO_SCENARIO_CHATROOM_GAMING 时，本地用户通过系统播放器播放视频、开启屏幕共享与声卡采集后，远端用户听到播放的视频声音有杂音。
  • 弱网环境下，偶现用户无法切换角色。
  • 在 Android 上，特定场景下，无法打印 PCM dump 文件。
  • 在 Android 上，使用第三方耳返库导致的崩溃。
  • 在部分 Android 机型上，硬件编码问题导致的黑屏。
  • 在 Android 上，在弱网环境下，频繁调用 StartAudioMixing 播放在线音乐文件时，偶现 ANR 弹窗。
  • 在部分 Android 设备上，连接蓝牙耳机后，声音依旧通过扬声器播放。
  • 在 Android 上，特定场景下切换音频路由到蓝牙，偶现蓝牙设备采集失效。
  • 特定网络环境下，主播使用小米手机进行纹理格式的视频自采集时，频道内其他用户看主播黑屏。
  • 在部分 Vivo 机型上偶现的崩溃。
  • 在 iOS 上，应用运行在 M1 芯片设备上时，偶现用户画面上下颠倒。
  • 在 MacBook Air 系列的部分低端机上，客户端音频录制启动时间超过 5 秒时，音频设备模块（ADM）会无限重启。
  • 在 macOS 上，用户在频道内插拔音视频设备时，SDK 没有触发媒体设备状态变化回调。

API 变更

新增

修改

废弃

  • AgoraChannel 类的 Publish 和 Unpublish

3.4.2 版

该版本于 2021 年 5 月发布。

升级必看

集成变更

  1. WGC 库

在 Windows 上，该版本新增与窗口共享相关的 libagora-wgc.dll 动态库。如果你将 SDK 升级到 v3.4.2 或更高版本，请务必在集成 SDK 时添加该库。

  1. 插件列表

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

行为变更

  1. 音乐文件播放状态

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

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

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

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

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

新增特性

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

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

2. 音效文件播放进度

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

  • PlayEffect[2/2]: 通过 startPos 参数，在播放音效文件时设置播放位置。
  • SetEffectPosition: 在播放音效文件后，设置音效文件的播放位置。
  • GetEffectDuration: 获取本地音效文件的总时长。
  • GetEffectCurrentPosition: 获取音效文件的播放进度。

同时，该版本废弃 PlayEffect[1/2]，请使用 PlayEffect[2/2] 替代。

改进

1. 视频编码

声网 SDK 允许你通过 degradationPreference 设置带宽受限时本地视频编码降级偏好，如降低视频帧率保障视频质量，降低视频质量保障视频帧率。自该版本起，degradationPreference 新增支持设为 MAINTAIN_BALANCED，弱网下会降低视频帧率和视频质量，以在流畅性和视频质量之间取得平衡，适用于流畅性和画质均优先的场景，如一对一通话、一对一教学、多人会议。

2. 窗口共享

该版本起对窗口共享进行如下优化：

  • 在 Windows 10 1809 及之后版本的系统上，StartScreenCaptureByWindowId 支持共享大部分 UWP 应用窗口和采用 DirectX 渲染的窗口。此时，共享的窗口有黄色描边，且 captureMouseCursor(false) 不生效。
  • 在 Windows 10 1809 之前版本的系统上，通过 StartScreenCaptureByWindowId 共享指定窗口画面时，被其他窗口遮挡的区域被涂黑。

3. 音乐文件播放进度

为方便控制音乐文件的播放进度，该版本进行如下优化：

  • 废弃 StartAudioMixing 并新增同名方法替代。新方法允许你通过 startPos 参数在播放音乐文件时设置播放位置。
  • 废弃 GetAudioMixingDuration 并新增同名方法替代。新方法允许你通过 filePath 参数在播放本地音乐文件前获取该音乐文件总时长。

4. AirPlay 回调

该版本新增支持在 iOS 设备中触发 OnAudioRouteChangedHandler 回调并报告 AUDIO_ROUTE_AIRPLAY。当用户在 iOS 设备上使用 Apple AirPlay 播放音频时，SDK 会触发该回调。

5. 客户端录音

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

该版本还新增了错误码 -160。如果你在音乐文件播放完成前再次调用 StartAudioRecording[3/3]，SDK 会报告该错误码。

6. 媒体设备出错

为方便用户了解本地音视频出错的原因，该版本进行如下优化：

  • 在 LOCAL_VIDEO_STREAM_ERROR 中新增错误码 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(8)，报告无法找到本地视频采集设备。

  • 对 Windows 平台，在 LOCAL_AUDIO_STREAM_ERROR 中新增如下错误码：

    • LOCAL_AUDIO_STREAM_ERROR_NO_RECORDING_DEVICE(6): 报告无法找到本地音频采集设备。
    • LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE(7): 报告无法找到本地音频播放设备。

7. URI 支持

在 Android 上，为符合 Google Play Store 的要求，该版本支持通过 URI 访问本地文件。如需调用 StartAudioMixing、GetAudioMixingDuration、PreloadEffect、PlayEffect、 GetEffectDuration 或 AddVideoWatermark，声网推荐你按如下步骤访问本地文件：

  1. 使用 Storage Access Framework 获取本地文件的 URI。
  2. 调用 Uri.toString 将 URI 转换为字符串。
  3. 将转换的字符串传入 filePath 或 watermarkUrl 参数。

问题修复

该版本修复了如下问题：

  • 在特定的基础变声场景下，出现崩溃。
  • 极端弱网情况下，Unity 用户看 Web 主播花屏。
  • 调用 EnableSoundPositionIndication(true) 后 OnVolumeIndicationHandler 回调的音量信息不准确。
  • 在 Windows 上，集成 libagora_ai_denoise_extension.dll 后偶现崩溃。
  • 在 Windows 10 特定机型上共享文件资源管理器窗口时，远端看到的窗口标题栏颜色异常。
  • Mac 上使用神奇效果最小化共享的窗口时，远端用户看到扭曲画面的问题。
  • 在 iOS 上，长时间在后台的应用回到前台时，偶现用户无法加入频道。
  • 在 Android 和 iOS 上，远端用户切换前后摄像头时，本地用户看到远端画面闪现颠倒。
  • 在 Android 上，音频采样率超出 4.8 kHz 时引起的崩溃。
  • 在 Android 上，特定场景下接收到的自定义视频帧画面旋转。

API 变更

新增

修改

废弃

  • GetAudioMixingDuration[1/2]
  • StartAudioRecording[2/3]
  • PlayEffect[1/2]
  • StartAudioMixing[1/2]
  • AUDIO_MIXING_ERROR_TYPE

3.3.1 版

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

升级必看

1. 集成变更

该版本新增如下库。

目标平台 声网基础计算库 AI 降噪库（可裁剪）
Android libagora-core.so libagora_ai_denoise_extension.so
iOS AgoraCore.framework AgoraAIDenoiseExtension.framework
macOS AgoraCore.framework AgoraAIDenoiseExtension.framework
Windows libagora-core.dll libagora_ai_denoise_extension.dll

2. 行为变更

该版本废弃了 SetDefaultMuteAllRemoteAudioStreams 和 SetDefaultMuteAllRemoteVideoStreams，并修改了 Mute 相关方法的如下行为：

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

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

新增特性

1. 原生支持 M1 芯片

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

2. 频道媒体选项

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

3. 云代理

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

4. AI 降噪

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

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

5. 歌唱美声

在歌唱场景中，为美化歌声并添加混响效果，该版本新增 SetVoiceBeautifierParameters，并在 VOICE_BEAUTIFIER_PRESET 中添加 SINGING_BEAUTIFIER 枚举值。

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

6. 基础变声

该版本新增 SetVoiceConversionPreset 方法改变用户的声音。你可以把男声变得低沉、稳重，把女声变得甜美、中性。

7. 设置日志文件

为保证日志内容的完整性，该版本在 RtcEngineConfig 中新增 logConfig 成员变量，在你初始化 IRtcEngine 时可用于设置声网 SDK 输出的日志文件。

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

8. 采集画质

为更好地控制摄像头采集的画质，该版本新增支持自定义采集分辨率并监听采集异常：

  • 自定义采集分辨率：调用 SetCameraCapturerConfiguration 方法，将采集偏好设为 CAPTURER_OUTPUT_PREFERENCE_MANUAL(3) 并设置采集视频的宽高。
  • 监听采集异常：
    • 采集的画质亮度异常：通过 OnLocalVideoStatsHandler 回调的 captureBrightnessLevel 监听。
    • 摄像头无法输出采集视频：通过 OnLocalVideoStateChangedHandler(LOCAL_VIDEO_STREAM_STATE_FAILED, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)回调监听。
    • 摄像头重复输出采集视频：通过 OnLocalVideoStateChangedHandler(LOCAL_VIDEO_STREAM_STATE_CAPTURING, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)回调监听。

9. 创建数据流

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

改进

1. AES-GCM 加密模式

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

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

2. 远端音频统计

为监测通话中与音频相关的主观体验，该版本在 OnRemoteAudioStatsHandler 中增加如下成员：

  • qoeQuality: 报告接收远端音频时的体验质量。
  • qualityChangedReason: 报告接收远端音频时体验质量较差的原因。
  • mosValue: 报告声网实时音频 MOS（平均主观意见分）评估系统对接收到的远端音频流的质量评分。

问题修复

该版本修复了如下问题：

  • 开启听声辨位后，无法通过 OnVolumeIndicationHandler 回调获取远端用户音量。
  • 部分设备在短时间内连续编码关键帧时，偶现视频硬件编码器工作异常。
  • 特定机型上，设备被插入耳机后，采集音频失败。
  • Android 10 设备上偶现的采集本地音频失败的问题。
  • 偶现本地用户无法播放远端音频。
  • 360 安全大脑（网购模式）自动拦截程序运行。

API 变更

新增

废弃

  • SetDefaultMuteAllRemoteVideoStreams
  • SetDefaultMuteAllRemoteAudioStreams
  • SetLogFile
  • SetLogFileSize
  • SetLogFilter
  • CreateDataStream

3.2.1 版

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

升级必看

1. 集成变更

自该版本起，SDK 包中新增以下动态库：

  • Fraunhofer FDK AAC 动态库
  • mpg123 动态库
  • SoundTouch 动态库
  • FFmpeg 动态库

各平台对应新增的文件如下：

平台 文件
Android
  • libagora-fdkaac.so
  • libagora-mpg123.so
  • libagora-soundtouch.so
  • libagora-ffmpeg.so
    		•
    iOS
  • Agorafdkaac.framework
  • AgoraSoundTouch.framework
  • Agoraffmpeg.framework
    		•
    macOS
  • Agorafdkaac.framework
  • AgoraSoundTouch.framework
  • Agoraffmpeg.framework
    		•
    Windows
  • libagora-fdkaac.dll
  • libagora-mpg123.dll
  • libagora-soundtouch.dll
  • libagora-ffmpeg.dll
    		•

    如果你将 SDK 升级到 v3.2.1，请务必参考快速开始在你的项目中添加上述文件。

    2. 云代理

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

    3. 安全合规

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

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

    传输层加密导致 SDK 包体积大小受到影响，数据详见《产品概述》。

    新增特性

    1. 极速直播

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

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

    详见极速直播产品概述。

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

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

    • OnAudioPublishStateChangedHandler: 音频发布状态发生改变。
    • OnVideoPublishStateChangedHandler: 视频发布状态发生改变。
    • OnAudioSubscribeStateChangedHandler: 音频订阅状态发生改变。
    • OnVideoSubscribeStateChangedHandler: 视频订阅状态发生改变。

    3. 本地首帧发布回调

    为提示用户本地音视频首帧已发布，该版本新增如下回调：

    • OnFirstLocalAudioFramePublishedHandler：已发布本地音频首帧回调。该回调取代 OnFirstLocalAudioFrameHandler 回调，我们建议你不再使用 OnFirstLocalAudioFrameHandler 回调。
    • OnFirstLocalVideoFramePublishedHandler：已发布本地视频首帧回调。

    4. 自定义数据上报

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

    改进

    1. 指定访问区域完善

    该版本修改了区域访问限制的区域码（AREA_CODE），并新增日本和印度的区域码。最新区域码如下：

    • AREA_CODE_CN: 中国大陆。
    • AREA_CODE_NA: 北美区域。
    • AREA_CODE_EU: 欧洲区域。
    • AREA_CODE_AS: 除中国大陆以外的亚洲区域。
    • AREA_CODE_JP: 日本。
    • AREA_CODE_IN: 印度。
    • AREA_CODE_GLOB:（默认）全球。

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

    2. 会议场景

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

    3. 美声与音效

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

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

    4. CDN 直播推流

    该版本新增 OnRtmpStreamingEventHandler 回调，报告 CDN 直播推流过程中发生的事件，如未成功添加背景图或水印。

    5. 加密

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

    • SetEncryptionSecret
    • SetEncryptionMode

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

    6. 通话中质量透明

    该版本进一步扩充了 LocalAudioStats 类、LocalVideoStats 类、RemoteVideoStats 类和 RemoteAudioStats 类的成员，提供更多音视频质量相关数据。

    • LocalAudioStats 类新增 txPacketLossRate，表示本端到声网边缘服务器的物理音频丢包率 (%)。

    • LocalVideoStats 类新增：

      • txPacketLossRate: 本端到声网边缘服务器的物理视频丢包率 (%)。
      • captureFrameRate: 本地视频采集帧率 (fps)。

    • RemoteAudioStats 和 RemoteVideoStats 类中新增 publishDuration，表示远端音频流和视频流的累计发布时长（毫秒）。

    7. 设置音频编码属性

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

    Profile 3.2.1 版本 3.2.1 版本之前
    AUDIO_PROFILE_DEFAULT 直播场景: 64 Kbps通信场景: Windows: 16 KbpsAndroid/iOS/macOS: 18 Kbps 直播场景: 52 Kbps通信场景:Windows: 16 KbpsAndroid/iOS/macOS: 18 Kbps
    AUDIO_PROFILE_SPEECH_STANDARD 18 Kbps 18 Kbps
    AUDIO_PROFILE_MUSIC_STANDARD 64 Kbps 48 Kbps
    AUDIO_PROFILE_MUSIC_STANDARD_STEREO 80 Kbps 56 Kbps
    AUDIO_PROFILE_MUSIC_HIGH_QUALITY 96 Kbps 128 Kbps
    AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO 128 Kbps 192 Kbps

    8. 日志扩容

    该版本中，声网 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 写入最新的日志。

    9. 美颜

    该版本支持在 macOS 中调用 SetBeautyEffectOptions 设置对比度、亮度、平滑度等参数，达到美白、磨皮、红润肤色等美颜效果。

    10. 音频路由

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

    11. OPPO 耳返优化

    该版本在 OPPO 如下机型上降低了耳返延时：

    • Reno4 Pro 5G
    • Reno4 5G

    12. 优化弱网环境下的视频体验

    • 自该版本起，弱网环境下会自动降低视频分辨率，以进一步优化视频流畅度。
    • 优化了网络状态变化过程中的视频画质，保证画质不模糊。

    13. 本地采集视频画质

    在 iOS 设备上，为提升本地采集的视频画质，该版本对摄像头采集本地视频进行如下优化：

    • 优化后置摄像头自动对焦功能。
    • 改善强光场景下图像局部过曝问题，该改善仅对分辨率不低于 960 × 540 的视频有效。

    问题修复

    该版本修复了如下问题：

    音频

    • 调用 SetAudioMixingPitch 方法时，部分参数不生效。
    • 在 iOS 设备上，断开蓝牙设备时，偶现音频卡顿。
    • 在 macOS 设备上，特定场景下偶现因设备音频模块未启动，导致的本地采集无声。

    视频

    • 发送端使用 vivo X30 时，接收端出现黑屏。
    • 在 iOS 设备上，远端用户退出频道时，本地用户看远端视频黑屏。
    • 在 macOS 设备上，开启其他视频应用时，SDK 无法开启本地摄像头。

    SDK

    • 在 Android 设备上，离开频道时偶现崩溃。
    • Android 6 及以上且 CPU 为 x86 架构的手机出现崩溃。
    • 在 iOS 设备上，多频道场景中，用户切换频道发言后，退出频道时偶现崩溃。

    API 变更

    新增

    废弃

    • SetLocalVoiceChanger
    • SetLocalVoiceReverbPreset
    • SetEncryptionSecret
    • SetEncryptionMode
    • OnFirstLocalAudioFrameHandler

    3.0.1 版

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

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

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

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

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

    升级必看

    1. 静态库升级动态库（macOS 和 iOS）

    该版本将 iOS 和 macOS 的静态库升级为动态库，且库名由 AgoraRtcEngineKit 变更为 AgoraRtcKit。如果你由老版本的 SDK 升级至该版本，请务必在 Xcode 中重新导入 AgoraRtcKit.framework，并将该库的 Embed 属性设置为 Embed & Sign。

    如果你集成了加密库 AgoraRtcCryptoLoader.framework，也需要重新导入库并将其 Embed 属性设置为 Embed & Sign。

    2. 枚举更名

    该版本将设置用户角色的 CLIENT_ROLE 枚举类更名为 CLIENT_ROLE_TYPE，并对其包含的枚举进行了如下修改：

    • BROADCASTER 更名为 CLIENT_ROLE_BROADCASTER
    • AUDIENCE 更名为 CLIENT_ROLE_AUDIENCE

    3. 通信场景上行默认不开启视频小流

    从该版本起，声网在通信场景下，默认不开启视频小流。如需启用，请在成功加入频道后，调用 EnableDualStreamMode(true) 方法启用视频双流模式。在多人视频通信场景下，我们建议你开启视频双流。

    新增特性

    1. 设置区域访问限制

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

    2. 多频道管理

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

    该版本还新增了 SetMultiChannelWant 为当前引擎开启多频道状态，和 SetForMultiChannelUser 在多频道中渲染本地和远端视图。

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

    3. 调整音乐文件音调

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

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

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

    5. 美声和音效

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

    • 在 VOICE_CHANGER_PRESET 枚举中新增了以 VOICE_BEAUTY 为前缀和以 GENERAL_BEAUTY_VOICE 为前缀的枚举值，分别实现音色变换或语聊美声功能。
    • 在 AUDIO_REVERB_PRESET 枚举中新增了以 AUDIO_REVERB_FX 为前缀的枚举值和 AUDIO_VIRTUAL_STEREO，分别实现变声音效、新版曲风音效、新版空间塑造和虚拟立体声效果。

    6. 人脸检测

    该版本在 Android 和 iOS 平台新增人脸检测功能。通过 EnableFaceDetection 方法开启人脸检测后，SDK 会实时触发 OnFacePositionChangedHandler 回调，向本地用户报告检测出的一系列结果，包括人脸距设备屏幕的距离。该功能可用于提醒用户注意用眼卫生，和屏幕保持一定距离。

    改进

    1. 音频编码属性

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

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

    2. 质量透明

    为方便开发者获取更多通话统计信息，该版本在 RtcStats 类中新增如下成员，方便更好地监控通话的质量和通话过程中的内存变动：

    • gatewayRtt
    • memoryAppUsageRatio
    • memoryTotalUsageRatio
    • memoryAppUsageInKbytes

    在 iOS 上，为避免 iOS 14 设备中出现本地网络权限弹窗提示，gatewayRtt 参数默认关闭。详见 FAQ。 如果你不介意弹窗提示，且需启用该功能，请联系技术支持。

    3. 屏幕共享

    为支持更多屏幕共享使用场景，该版本新增支持调用 StartScreenCaptureByWindowId 方法时共享通用 Windows 平台（UWP）应用窗口。

    4. 美颜

    该版本新增 SetBeautyEffectOptions 对 Windows 平台的支持，你可以调用该接口设置对比度、亮度、平滑度等参数，达到美白、磨皮、红润肤色等美颜效果。

    5. 其他提升

    • 该版本在 VIDEO_PIXEL_FORMAT 中新增 VIDEO_PIXEL_RGBA，你可以将自采集的 RGBA 视频数据传递给 SDK。
    • 该版本自动开启直播场景下 Native SDK 与 Web SDK 的互通，并废弃原有的 EnableWebSdkInteroperability 方法。

    问题修复

    • 修复了混音、Loopback 测试异常、音频录制、音频编码、回声等音频问题。
    • 修复了 OnVideoSizeChangedHandler 回调无响应、 VideoFrame 中 buffer 一直为空、水印、视频画面比例、画质模糊、视频不能全屏、连麦用户屏幕共享黑屏、屏幕共享黑边等视频问题。
    • 修复了特定场景下偶现的崩溃、日志文件、推流不稳定等问题。
    • 修复了通信场景下，调用 SetRemoteSubscribeFallbackOption 方法也生效的问题。
    • 修复了一对一通信场景下，下行音视频弱网下会回退为纯音频的问题。
    • 修复了 SendStreamMessage 和 SetLiveTranscoding 中 TranscodingUser 不支持数组的问题。
    • 修复了 OnClientRoleChangedHandler 回调多次、App ID 和 Token 校验、日志目录乱码等问题。

    API 变更

    新增

    更名

    枚举类 CLIENT_ROLE 更名为 CLIENT_ROLE_TYPE。其包含的枚举 BROADCASTER 和 AUDIENCE 更名为 CLIENT_ROLE_BROADCASTER 和 CLIENT_ROLE_AUDIENCE。

    废弃

    2.9.2 版

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

    该版本于 2020 年 2 月 17 日发布。

    • 该版本修复了 Android 设备上的部分异常。
    • 该版本修复了 Windows 平台下，使用 Editor 调试模式时偶现的卡死问题。

    2.9.1 版

    声网 Unity SDK 广泛应用于游戏、教育、AR、VR 等场景。

    该版本于 2019 年 12 月 23 日发布。功能特性及相关文档详见下文。

    功能特性

    1. 多平台支持

    该版本支持在 iOS、Android、macOS 和 Windows (x86/x86-64) 平台中集成。

    2. 支持与 Web 互通

    该版本提供 EnableWebSdkInteroperability 方法，用于打开直播场景下与声网 Web SDK 的互通。

    3. 视频渲染方式

    该版本支持多样的视频渲染方式，你可以在 Unity 菜单中选择 Auto Graphics API 下任意的视频渲染模式。

    4. 多线程渲染

    该版本支持多线程渲染，你可以在 Unity 菜单中选择 Multithreaded Rendering 启用该功能。

    5. 原始音视频数据

    该版本支持原始音频数据和 RGBA 格式的原始视频数据，你可以获取原始音视频数据并自行处理。详见原始视频数据。

    6. 音视频自采集

    该版本提供音视频自采集的接口，你可以配置外部音视频源及推送音视频数据。详见自定义视频采集和渲染。

    7. 加密

    该版本支持加密功能，你可以对音视频流进行加密。下表展示移动端的加密库信息，若希望减小 SDK 体积且不使用加密功能，你可以把加密库移除。

    平台 加密库
    Android libagora-crypto.so
    iOS
    • AgoraRtcCryptoLoader.framework
    • libcrypto.a

    8. 云代理服务

    支持使用云代理服务，方便部署企业防火墙的用户正常使用声网的服务，详见使用云代理服务。

    相关文档

    你可以参考以下文档集成 SDK，实现相应的实时音视频功能：

    声网提供了开源的 Unity GitHub Sample，你也可以前往下载并体验。