发版说明

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

3.7.2.1 版

该版本基于 Android 平台 3.7.2 版声网 RTC SDK 开发，于 2022 年 11 月 11 日发布。

该版本修复了升级到 3.7.2 版本后偶现的 App 崩溃问题。

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。

改进

1. 虚拟背景

考虑到用户的图片可能破损，例如，用户下载的图片不完整，用户设备病毒损坏了图片，该版本在虚拟背景功能中增加了对破损图片的兼容，支持将部分破损图片设为虚拟背景。

2. 蓝牙权限

受 Android 12.0 系统限制，你需要在集成时额外添加 BLUETOOTH_CONNECT 权限，否则使用 Android 12.0 或以上设备的用户可能无法正常使用蓝牙。为简化集成步骤，减少应用对权限的依赖，该版本适配 Android 12.0 蓝牙场景，使你的应用不再依赖 BLUETOOTH_CONNECT 权限。

问题修复

该版本修复了如下问题：

• 部分网络情况下，SDK 不支持报告端到端丢包率。
• 调用 enableFaceDetection 开启本地人脸检测后，偶现 onFacePositionChanged 回调报告的数据为空。
• 多次调用 playEffect 播放音效，每次设置的 soundId 值递增，且每次均未调用 stopEffect 或 stopAllEffects 停止播放音效时，必现崩溃。
• 调用 setAudioMixingPosition 设置音乐文件的播放位置在 36 分钟或之后的位置时，音乐会从头开始播放，而非从指定的位置开始播放。
• 虚拟节拍器工作异常，例如不支持 MP3 格式的音频，播放的节拍不符合预期。
• 通信模式下，使用蓝牙耳机进行通话的用户退出频道后，重新进入频道时，声音通过扬声器播放，而非蓝牙耳机。

3.7.1 版

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

升级必看

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

新增特性

1. 设置本地代理

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

改进

1. 超分辨率（Beta）

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

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

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

2. 跨频道媒体流转发

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

问题修复

该版本修复了如下问题：

• 偶现崩溃。
• 在三星 Galaxy S20+、Note10+ 等特定机型上，采集音量过小。
• 本地用户开启美颜后，切换前后摄像头时，偶现远端用户看本地用户的视频画面闪现上下颠倒。
• 虽然远端用户未改变音频状态，但本地用户在断网重连后会收到 onRemoteAudioStateChanged(2,6) 回调。
• 在网络时延过大或路由器不响应 ICMP 包的情况下，onRtcStats 回调报告的 gatewayRtt 不准确。
• 对于共享屏幕的用户，onNetworkQuality 回调报告的上行网络质量不准确。
• 偶现用户第一次加频道用时较长。
• 本地用户使用屏幕共享功能分享第三方应用播放的音频时，远端用户听到回声。

API 变更

新增

• setLocalAccessPoint
• onProxyConnected 中新增支持 localProxyIp 参数
• PROXY_TYPE 中新增 NONE_PROXY_TYPE(0) 和 LOCAL_PROXY_TYPE(3)
• enableRemoteSuperResolution
• SR_STATE_REASON_INSUFFICIENT_PERFORMANCE(4)
• VBS_STATE_REASON_INSUFFICIENT_PERFORMANCE(4)

废弃

• enableRemoteSuperResolution

3.7.0.2 版

该版本于 2022 年 6 月 6 日发布。

该版本修复了如下问题：

• 集成屏幕共享插件 AgoraScreenShareExtension 并将 targetSdkVersion 设为 31 后，编译或运行项目失败。
• 频道内 Web 端发送 H.264 视频流时，Native 端看到 Web 端视频卡顿。

3.7.0.1 版

该版本于 2022 年 5 月 9 日发布，修复了部分机型上偶现的回声和兼容性问题。

3.7.0 版

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

升级必看

1. JND 库集成变更

自 3.7.0 版起，SDK 默认静态编译 JND 库，不再提供插件的方式。如果你已集成 JND 插件，升级至 3.7.0 版时请在项目依赖中删除 JND 插件并重新编译项目。JND 插件的介绍可参考插件列表。

2. 动态库对应的 implementation 字段变更

通过 Maven Central 集成 Android SDK 时，你可以修改 /Gradle Scripts/build.gradle(Module: .app) 文件中的 dependencies 中的 implementation 字段，以指定需要集成的动态库。详见减少 App 体积。

为使同一动态库在视频 SDK 和音频 SDK 中使用相同的 implementation 字段，该版本对下列动态库的 implementation 字段做了变更：

动态库	implementation 字段 （3.6.2 版）	implementation 字段  （3.7.0 及之后版）
AI 降噪插件： libagora_ai_denoise_extension.so	视频 SDK：io.agora.rtc:full-ains 音频 SDK：io.agora.rtc:voice-ains	io.agora.rtc::ains
全格式音频解码插件：libagora_full_audio_format_extension.so	视频 SDK：io.agora.rtc:full-full-audio-format 音频 SDK：io.agora.rtc:voice-full-audio-format	io.agora.rtc:full-audio-format

新增特性

1. 空间音效

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

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

2. 屏幕共享

该版本新增 startScreenCapture、stopScreenCapture、updateScreenCaptureParameters 方法，支持在该平台开启屏幕共享。屏幕共享的实现方法请参考屏幕共享。

3. 本地语音音调

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

4. 远端首帧出图回调

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

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

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

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

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

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

改进

1. 频道能力提升

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

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

2. 虚拟背景

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

3. 新版 AI 降噪

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

4. playEffect 优化

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

5. 传输升级

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

API 变更

新增

• startScreenCapture
• stopScreenCapture
• updateScreenCaptureParameters
• enableLocalVoicePitchCallback
• onLocalVoicePitchInHz
• IRtcChannelEventHandler 类中新增 onFirstRemoteVideoFrame
• CONNECTION_CHANGED_SAME_UID_LOGIN(19) 和 CONNECTION_CHANGED_TOO_MANY_BROADCASTERS(20)
• 错误码中新增:
  • ERR_SCREEN_CAPTURE_SYSTEM_NOT_SUPPORTED(2)
  • ERR_SCREEN_CAPTURE_SYSTEM_AUDIO_NOT_SUPPORTED(3)
  • ERR_SCREEN_CAPTURE_PERMISSION_DENIED(16)

废弃

• 警告码 WARN_SET_CLIENT_ROLE_NOT_AUTHORIZED，改用 onClientRoleChangeFailed 回调报告的 reason

3.6.2 版

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

新增特性

1. 使用 Maven Central 时删除插件

插件指可选集成到项目文件的动态库。自该版本起，通过 Maven Central 集成 Android SDK 时，声网支持你通过修改 /Gradle Scripts/build.gradle(Module: .app) 文件中的 dependencies，指定集成你需要的动态库，以排除你不需要使用的插件，从而减少集成 SDK 后的应用体积。示例代码和 dependencies 中 implementation 字段详情请参考减少 App 体积。

2. 视频增强

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

• 视频降噪：该功能可以降低视频噪声，提升视频画质。你可以通过 setVideoDenoiserOptions 方法设置开/关视频降噪和视频降噪效果选项。
• 暗光增强：该功能可在光线亮度偏低（如背光、阴天、暗场景）和亮度不均匀的环境下自适应调整视频画面的亮度值，恢复或凸显图像的细节信息，提升视频图像的整体视觉效果。你可以通过 setLowLightEnhanceOptions 方法设置开/关暗光增强和暗光增强效果选项。
• 色彩增强：该功能可智能调节饱和度和对比度等视频特性，提升视频色彩丰富度和色彩还原度，使视频画面更生动。你可以通过 setColorEnhanceOptions 方法设置开/关色彩增强和色彩增强效果选项。

3. Wi-Fi 加速

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

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

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

4. 视频截图上传

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

5. 动态加载 .so 文件

该版本新增 setAgoraLibPath 方法，用于设置 .so 文件的存储目录。成功调用该方法后，SDK 会在 app 运行时根据你指定的目录动态加载 .so 文件，从而减小 app 的安装包体积。具体实现步骤详见减少 App 体积。

6. 传入原生 TextureView

该版本新增支持直接使用 Android 系统原生 TextureView。你可以向 VideoCanvas.view 直接传入原生 TextureView，不必再通过调用 CreateTextureView 得到 TextureView 对象后再传入 VideoCanvas.view。设置 VideoCanvas 后，你就可以调用 setupLocalVideo 和 setupRemoteVideo 来初始化本地和远端用户视图。

改进

1. 云代理

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

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

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

2. 音频录制

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

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

3. 播放音乐文件优化

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

• 减少播放音频文件时的卡顿和无声问题。
• 通过 getAudioFileInfo 获取的音频时长更加准确。
• 支持更多的音频文件格式。详见声网 SDK 支持播放哪些格式的音频文件。

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

问题修复

该版本修复了特定场景下，使用红米 4A 手机直播时出现滋啦杂声的问题。

API 变更

新增

• setVideoDenoiserOptions
• setLowLightEnhanceOptions
• setColorEnhanceOptions
• enableWirelessAccelerate
• onWlAccMessage
• onWlAccStats
• enableContentInspect
• onContentInspectResult
• setAgoraLibPath
• AudioRecordingConfiguration 中新增 recordingChannel
• AudioRecordingConfiguration.recordingQuality 中新增 AUDIO_RECORDING_QUALITY_ULTRA_HIGH(3)
• onProxyConnected
• TRANSPORT_TYPE_TCP_PROXY(2)

修改

• TRANSPORT_TYPE_NONE_PROXY(0) 的行为

3.6.1.1 版

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

3.6.1 版

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

改进

该版本进行如下改进：

• 使用 Mac 设备的远端用户因调用 leaveChannel 或网络中断等原因而离开频道后，本地用户看到远端画面停留在最后一帧，而不再是远端视图直接消失。
• 在自采集 Texture 格式的视频时，增加硬件编码失败回退软件编码的机制，提升视频功能的可用性。

问题修复

该版本修复了如下问题：

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

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

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

• 偶现崩溃。

3.6.0.1 版

该版本于 2021 年 12 月 10 日发布，修复了 3.6.0 版将动态库 libagora_fdkaac.so 错误地更名为 libagora_fdkaac_extension.so 的问题。

3.6.0 版

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

升级必看

旁路推流

为降低旁路推流集成难度，该版本优化了推流 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_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 结构体中新增 addWatermark、addBackgroundImage 实现。

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

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

新增特性

音画同步

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

改进

1. 基础美颜

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

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

2. 首帧出图

该版本缩短了弱网环境下首帧出图时间，提升用户视频体验。

问题修复

该版本修复了如下问题：

• SDK 检测到蓝牙配置异常时触发的蓝牙重启和关闭蓝牙的提示。
• 开启媒体流加密后，偶现远端用户接收到的视频卡顿。
• 播放原唱歌曲时，调用 setAudioMixingPitch 调整音调会导致播放的歌曲从原唱切换为伴奏。
• 在 EDUCATION 音频应用场景下，调用 enableLocalAudio 开启、关闭本地语音采集时，偶现的音量不稳定问题。

API 变更

新增

• startRtmpStreamWithoutTranscoding

• startRtmpStreamWithTranscoding

• updateRtmpTranscoding

• stopRtmpStream

• onRtmpStreamingStateChanged 的 state 参数中新增 RTMP_STREAM_PUBLISH_STATE_DISCONNECTING(5)

• onRtmpStreamingStateChanged 的 errCode 参数中新增如下：

  • RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER(11)
  • RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM(13)
  • RTMP_STREAM_PUBLISH_ERROR_NET_DOWN(14)
  • RTMP_STREAM_PUBLISH_ERROR_INVALID_APPID(15)

• onRtmpStreamingEvent 的 error 参数中新增如下：

  • RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT(3)
  • RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN(4)

• 在 LiveTranscoding 类中新增如下：

  • addWatermark
  • removeWatermark
  • getWatermarkList
  • addBackgroundImage
  • removeBackgroundImage
  • getBackgroundImageList

• 在 AgoraImage 类中新增 zOrder 和 alpha

• 在 AudioCodecProfileType 中新增 HE_AAC_V2

• setAVSyncSource

• 在 BeautyOptions 类中新增 sharpnessLevel

修改

将 lighteningLevel 的默认值从 0.7 改为 0.6

3.5.2 版

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

升级必看

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

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

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

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

新增特性

1. 音视频录制

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

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

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

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

• getMediaRecorder：注册回调并获取 AgoraMediaRecorder 对象。
• startRecording：设置录制的内容、时长、生成文件的格式、回调间隔，并开启本地音视频录制。
• stopRecording：停止本地音视频录制。
• release：释放 AgoraMediaRecorder 对象。
• onRecorderStateChanged：录制状态发生改变回调。
• onRecorderInfoUpdated：录制信息更新回调。

2. 视频截图

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

3. 音视频通话回路测试

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

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

改进

1. 性能改进

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

2. 体验改进

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

问题修复

该版本修复了如下问题：

• 用户在高丢包的弱网环境下加入频道，视频码率无法爬升。
• 特定弱网条件下，视频码率断崖式下降所导致的视频清晰度和流畅度明显下降问题。
• 在某些 Android 机型上调用 startAudioMixing 时，远端用户听到的人声和伴奏有轻微的不同步。
• 本地用户调用 enableDualStreamMode(false) 后，当该用户从使用 setVideoSource 自采集 SCREEN 类型的外部视频切换到 SDK 采集，本地会发送视频双流。

API 变更

该版本新增如下：

• startEchoTest [3/3]

• getMediaRecorder

• onRecorderStateChanged

• onRecorderInfoUpdated

• startRecording

• stopRecording

• release

• takeSnapshot

• onSnapshotTaken

3.5.1 版

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

新增特性

1. 超分辨率（Beta）

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

2. 背景虚化

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

3. 打开闪光灯

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

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

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

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

• 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 会触发 onChannelMediaRelayEvent 回调，并在回调中报告是否成功暂停或恢复媒体流转发。

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

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

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

6. 音乐文件高级设置

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

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

7. 获取音频文件信息

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

改进

1. 适配 OpenSL

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

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

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

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

3. 其他改进

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

• 持续优化虚拟背景的人像边缘效果。
• 提升了开启 AI 降噪后使用部分蓝牙耳机时的音频体验。

问题修复

该版本修复了如下问题：

• GAME_STREAMING 场景下，偶现因音乐检测不准确导致的回声或噪声。
• 远端用户在几秒内依次调用 enableLocalVideo(false)、enableLocalVideo(true) 关、开本地视频采集或依次调用 muteLocalVideoStream(true)、muteLocalVideoStream(false) 停止、恢复发送本地视频后，本地用户看远端用户偶现短暂黑屏。
• 特定场景下，偶现更新旁路推流转码布局失败。
• 本地用户调用 muteAllRemoteAudioStreams，收到 onRemoteAudioStateChanged (REMOTE_AUDIO_REASON_LOCAL_MUTED) 15 秒后，错误地收到了 onRemoteAudioStateChanged (REMOTE_AUDIO_REASON_REMOTE_MUTED)。
• 使用集成了 SDK 的 app 进行实时音视频互动，在接听系统电话之后切换回该 app，该 app 的音频路由发生改变。例如，在该 app 中使用扬声器播放音频，然后使用听筒接听系统电话，在切换回该 app 时音频路由会变成听筒。
• 音频场景下偶现崩溃。
• 自 3.4.5 版本起，连续多次调用 joinChannel 方法时，返回值不准确。
• 音频属性为 MUSIC_HIGH_QUALITY_STEREO (5) 的用户和使用其他音频属性的用户通话时，后者大概率会听到滋啦杂声。
• 特定场景下，主播使用特定低端机型时，偶现观众看主播视频卡顿。
• 特定场景下，发送端使用特定的小米和红米机型时，偶现接收端看到视频画面出现马赛克方格。
• 发送端使用特定的安卓模拟器时，本地视频或接收端看到的视频画面异常。
• 加入频道前调用 setExternalAudioSource 不生效。
• 同时连接蓝牙耳机和有线耳机，在多次插拔有线耳机后，SDK 不触发 onAudioRouteChanged 回调。
• 在频道内调用 enableLocalAudio(false) 后，SDK 额外触发 onLocalAudioStateChanged 回调报告 LOCAL_AUDIO_STREAM_STATE_CAPTURING(1)。

API 变更

新增

• enableRemoteSuperResolution
• onUserSuperResolutionEnabled
• isCameraTorchSupported (C++)
• setCameraTorchOn (C++)
• VirtualBackgroundSource 结构体中新增 blur_degree 属性和 BLUR_DEGREE 枚举
• backgroundSourceType 枚举中新增 BACKGROUND_BLUR
• pushExternalAudioFrame [2/2]
• setExternalAudioSourceVolume
• setAudioMixingPlaybackSpeed
• getAudioTrackCount
• selectAudioTrack
• setAudioMixingDualMonoMode
• pauseAllChannelMediaRelay
• resumeAllChannelMediaRelay
• 以下 RELAY_EVENT 枚举：
  • RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS
  • RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED
  • RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS
  • RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED
• getAudioFileInfo
• onRequestAudioFileInfo
• NETWORK_TYPE_MOBILE_5G(6)

废弃

• pushExternalAudioFrame [1/2]
• getAudioMixingDuration

3.5.0.4 版

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

改进

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

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

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

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

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

问题修复

该版本修复了如下问题：

• 使用原始视频数据时，SDK 会在捕捉到本地待渲染的视频帧时异常触发 onRenderVideoFrame 和 onRenderVideoFrameEx 回调。
• 使用原始视频数据时，偶现崩溃。
• 在部分小米机型上调用 setEnableSpeakerphone 后，无法通过设备的音量按钮调整音量大小。
• 在部分机型上调用 setEnableSpeakerphone 时，主线程出现 1～2 秒的卡顿。
• 使用 setLocalVoiceChanger 和 setLocalVoicePitch 时，偶现 SoundTouch 开源库引起的崩溃。
• 使用自采集和外部耳返库时，在加入频道前开启耳返无效。
• 成功注册原始视频数据观测器后，app 在 onCaptureVideoFrame 回调中进行耗时操作时，远端用户看本地用户的视频出现卡顿。
• 在三星部分机型上，调用 adjustRecordingSignalVolume(0) 失效。
• 成功注册原始视频数据观测器并设置 getObservedFramePosition 的返回值为 POSITION_PRE_ENCODER (1 << 2) 后，SDK 会异常触发与设置的观测位置不符的 onCaptureVideoFrame 回调。
• 在此前发布的 3.5.x 版 SDK 上，本地用户使用 Push 方式的音频自采集时，远端用户无法听到本地用户。

3.5.0.3 版

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

3.5.0.2 版

该版本于 2021 年 8 月 11 日发布，修复了特定场景下调用 setupLocalVideo 或 setupRemoteVideo 初始化本地或远端视图时出现的黑屏问题。例如：

• 先调用 setupLocalVideo(null) 或 setupRemoteVideo(null) 关闭本地或远端视图，再调用 setupLocalVideo 或 setupRemoteVideo 初始化本地或远端视图。
• 在 onRemoteVideoStateChanged 回调中调用 setupRemoteVideo 初始化远端视图。

3.5.0.1 版

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

未调用 setupLocalVideo 和 setupRemoteVideo 时，注册原始视频数据观测器无法收到 onRenderVideoFrame 回调。

3.5.0 版

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

升级必看

1. 新增 mavenCentral 集成方式

自该版本起，声网新增支持将 SDK 包发布到 mavenCentral。关于使用 mavenCentral 集成，详见集成 SDK。

2. 音频路由行为变更

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

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

  • 3.5.0 之前，SDK 无法设置音频路由为听筒。
  • 3.5.0 及之后，SDK 可以设置音频路由为听筒，但同时 SDK 使用的音量类型会变成通话音量。如果将音频路由再次切换回扬声器，则音量类型会恢复为媒体音量。
  参考如何区分媒体音量和通话音量了解 SDK 使用媒体音量的场景。

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

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

更多介绍见设置音频路由。

新增特性

虚拟背景（beta）

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

改进

1. 视频画质

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

• 通过对色彩范围的适配，提升采集和接收的视频对比度，以改善画面泛白问题。
• 通过对色彩空间的适配，提升采集和接收的视频色彩丰富度，进一步还原视频色彩。

2. 其他改进

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

• 降低了高分辨率（720P 及更高）场景下 CPU 占用率和端到端视频延时。
• 在开启 AGC 的场景下，缩短降噪收敛的时间，从而降低噪声忽大忽小的波动。
• 改善了视频自渲染场景下的出帧平滑度。

问题修复

该版本修复了如下问题：

• 特定场景下，偶现更新旁路推流转码布局失败。
• 远端用户调用 enableLoopbackRecording 后，偶现本地用户听到自己的回声。
• 调用 muteLocalAudioStream(true) 停止发布本地音频后，用户第一次加入频道可以听到远端用户，但退出频道后再次加入频道偶现无法听到远端用户。
• 本地网络环境较差时，SDK 报告的远端用户的下行网络质量 （rxQuality）不准确。

API 变更

新增

• enableVirtualBackground
• onVirtualBackgroundSourceEnabled

修改

• setEnableSpeakerphone
• setDefaultAudioRouteToSpeakerphone

3.4.6 版

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

改进

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

问题修复

该版本修复了如下问题：

• 特定的 Android 4.4 TV 机型上，开启摄像头失败。
• 使用 Type-C 耳机时声音小的问题。
• 在特定 Android 机型上运行项目时出现 interface xxx is not visible from class loader 报错。

3.4.5 版

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

升级必看

1. 支持 GCM2 加密

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

• 在 EncryptionMode 中新增 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 并将 EncryptionMode 设置为 AES_128_XTS。

更多介绍见媒体流加密。

2. 媒体流发布行为变更

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

• 废弃 publish 和 unpublish，并新增 muteLocalAudioStream 和 muteLocalVideoStream 作为替代。你可以分别设置音频流和视频流的发布状态。
• 在 ChannelMediaOptions 中新增 publishLocalAudio 和 publishLocalVideo 成员，默认值为 true。你可以在加入频道时设置音视频流的发布状态。如果用户已在一个频道中发流，则不论用户是主播还是观众，都需要在加入其他频道时设置 publishLocalAudio 和 publishLocalVideo 为 false。否则，加入频道会失败。
• 调用 setClientRole(BROADCASTER) 后，本地用户默认发布音视频流，无需再调用 publish。

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

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

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

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

3. 原始音频数据

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

• 将以下回调中 samples 参数的数据类型由 byte[] 改为 DirectByteBuffer：
  • onRecordFrame
  • onPlaybackFrame
  • onPlaybackFrameBeforeMixing
  • onMixedFrame
  • onPlaybackFrameBeforeMixingEx

当你通过 JNI 调用 C++ 接口获取原始音频数据时，可以减少拷贝操作。

• 将上述 on 系列回调中的 samples, numOfSamples, bytesPerSample, channels 和 samplesPerSec 参数封装为 AudioFrame 类，简化回调接口，增强 API 扩展性。

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

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

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

4. startAudioMixing 变更

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

新增特性

原始视频数据和本地视频编码数据

为降低设备性能消耗和跨平台使用 C++ API 的开发难度，该版本在 Android 平台新增如下 API 供你实现原始视频数据观测器和本地视频编码数据观测器。你可以用其实现各种自定义功能，如录制视频、截图、美颜。

• 原始视频数据观测器：
  • registerVideoFrameObserver: 注册原始视频数据观测器。
  • onCaptureVideoFrame: 获取本地采集的视频数据。
  • onPreEncodeVideoFrame: 获取本地编码前的视频数据。
  • onRenderVideoFrame: 获取接收到的远端视频数据。
  • getVideoFormatPreference: 设置 SDK 输出的原始视频数据格式。
  • getRotationApplied: 设置是否旋转 SDK 输出的原始视频数据。
  • getMirrorApplied: 设置是否镜像 SDK 输出的原始视频数据。
  • getObservedFramePosition: 设置视频观测位置。
  • isMultipleChannelFrameWanted: 设置 SDK 是否输出多个频道内接收到的远端视频数据。
  • onRenderVideoFrameEx: 获取多个频道内接收到的远端视频数据。
• 本地视频编码数据观测器：
  • registerVideoEncodedFrameObserver: 注册本地视频编码数据观测器。
  • onVideoEncodedFrame: 获取本地视频编码数据。

改进

1. 旁路推流

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

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

2. 音乐文件状态

在 pauseAudioMixing 后调用 startAudioMixing 时，该版本在报告 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY,AUDIO_MIXING_REASON_STARTED_BY_USER) 状态之前新增了 onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_STOPPED,AUDIO_MIXING_REASON_STOPPED_BY_USER) 状态，提示已停止播放音乐文件。

3. 音频设备出错

为方便获取系统电话对音频采集的影响，该版本在 LOCAL_AUDIO_STREAM_ERROR 中新增 LOCAL_AUDIO_STREAM_ERROR_INTERRUPTED (8)，报告音频采集被系统电话中断。

问题修复

该版本修复了如下问题：

• 在弱网环境下，调用 startAudioMixing 播放在线音乐文件时，偶现 SDK 响应时间过长而引起卡顿。
• 在弱网环境下，频繁调用 startAudioMixing 播放在线音乐文件时，偶现 ANR 弹窗。
• 在部分 Android 设备上，连接蓝牙耳机后，声音依旧通过扬声器播放。
• 特定场景下切换音频路由到蓝牙，偶现蓝牙设备采集失效。
• 弱网环境下，偶现用户无法切换角色。
• 特定网络环境下，主播使用小米手机进行纹理格式的视频自采集时，频道内其他用户看主播黑屏。

API 变更

新增

• RTMP_STREAM_PUBLISH_ERROR 中新增 RTMP_STREAM_UNPUBLISH_ERROR_OK (100)
• RTMP_STREAMING_EVENT 中新增 RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE (2)
• EncryptionMode 中新增 AES_128_GCM2 (7) 和 AES_256_GCM2 (8)
• EncryptionConfig 中新增 encryptionKdfSalt
• RtcChannel 中新增 muteLocalAudioStream 和 muteLocalVideoStream
• ChannelMediaOptions 中新增 publishLocalAudio 和 publishLocalVideo
• LOCAL_AUDIO_STREAM_ERROR 中新增 LOCAL_AUDIO_STREAM_ERROR_INTERRUPTED (8)
• registerVideoFrameObserver
• onCaptureVideoFrame
• onPreEncodeVideoFrame
• onRenderVideoFrame
• getVideoFormatPreference
• getRotationApplied
• getMirrorApplied
• getObservedFramePosition
• isMultipleChannelFrameWanted
• onRenderVideoFrameEx
• registerVideoEncodedFrameObserver
• onVideoEncodedFrame
• IAudioFrameObserver 类中新增：
  • getObservedAudioFramePosition
  • getRecordAudioParams
  • getMixedAudioParams
  • getPlaybackAudioParams

修改

• 修改 IAudioFrameObserver 类中的如下回调：
  • onRecordFrame
  • onPlaybackFrame
  • onPlaybackFrameBeforeMixing
  • onMixedFrame
  • onPlaybackFrameBeforeMixingEx
  • startAudioMixing

废弃

• RtcChannel 类的 publish 和 unpublish

3.4.3 版

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

• 特定场景下，无法打印 PCM dump 文件。
• 使用第三方耳返库导致的崩溃。
• 在部分 Android 机型上，硬件编码问题导致的黑屏。
• 在部分 Vivo 机型上偶现的崩溃。
• 调用 startAudioMixing 无法播放扩展名为 m4a 的 MP3 本地音乐文件。
• 3.0.0+ 版本的用户离开有 3.0.0 之前版本的用户的通信频道，并切换频道场景为直播场景后，在加入下一个频道前切换用户角色为主播，但设置未生效。
• 特定场景下，用户加入频道 10 分钟后偶现音频延迟。

3.4.2 版

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

改进

为符合 Google Play Store 的要求，该版本支持通过 URI 访问本地文件。如需调用 startAudioMixing、getAudioMixingDuration、preloadEffect、playEffect、 getEffectDuration 或 addVideoWatermark，声网推荐你按如下步骤访问本地文件：

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

问题修复

该版本修复了 3.4.0、3.4.1 版本与 3.0.0 之前版本的互通问题：

• 通信场景下，3.4.0 或 3.4.1 版本的 Native 用户看 3.0.0 之前版本的 Native 用户时，出现卡顿。
• 直播场景下，3.4.0 或 3.4.1 版本的 Native 用户看 3.0.0 之前版本的 Windows 或 macOS 用户时，出现卡顿。

3.4.1 版

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

• 在特定的基础变声场景下，出现崩溃。
• 极端弱网情况下，Native 用户看 Web 主播花屏。

3.4.0 版

该版本于 4 月 16 日发布。

升级必看

集成变更

1. SDK 包发布平台

由于 JCenter 即将关闭，自该版本起，声网停止将 SDK 包发布到 JCenter，改为发布到 JitPack。关于使用 JitPack 集成，详见集成 SDK。

2. 插件列表

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

行为变更

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

• 将 errorCode 参数修改为 reason 参数。

• 废弃如下常量并改用以 AUDIO_MIXING_REASON 为前缀的相关常量替代：

  • MEDIA_ENGINE_AUDIO_ERROR_MIXING_OPEN
  • MEDIA_ENGINE_AUDIO_ERROR_MIXING_TOO_FREQUENT
  • MEDIA_ENGINE_AUDIO_EVENT_MIXING_INTERRUPTED_EOF

  通过以 AUDIO_MIXING_REASON 为前缀的常量，你可以获取播放开始、暂停、停止或失败的原因。

• 修改 MEDIA_ENGINE_AUDIO_EVENT_MIXING 的部分逻辑。例如，循环播放音乐时，播放完成或开始播放都会触发 MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY 状态。

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

新增特性

1. 虚拟节拍器

为满足在线教学等场景对节拍器的需求，该版本新增如下方法：

• startRhythmPlayer：开启虚拟节拍器。
• stopRhythmPlayer：关闭虚拟节拍器。
• configRhythmPlayer：在开启虚拟节拍器后，重新配置虚拟节拍器。

2. 音效文件播放进度

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

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

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

改进

1. 视频编码

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

2. 原始视频数据（C++)

getRotationApplied 和 getMirrorApplied 可将原始视频数据作旋转、镜像处理。为提升用户体验，该版本将这些回调函数支持处理的视频数据格式由 RGBA 拓展到 RGBA 和 YUV 420。

3. 音乐文件播放进度

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

4. 客户端录音

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

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

5. 媒体设备出错

为方便用户了解本地视频出错原因，该版本在 LOCAL_VIDEO_STREAM_ERROR 中新增错误码 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(8)，报告无法找到本地视频采集设备。

问题修复

该版本修复了如下问题：

• 特定场景下，通过 getMirrorApplied 设置镜像后，视频画面出现上下颠倒。
• 用户无法通过 onPreEncodeVideoFrame 获取 RGBA 格式的视频数据。
• 用户无法通过 getMirrorApplied 和 getRotationApplied 处理本地编码前的视频数据。
• 音频采样率超出 4.8 kHz 时引起的崩溃。
• 调用 enableSoundPositionIndication(true) 后 onAudioVolumeIndication 回调的音量信息不准确。
• 远端用户切换前后摄像头时，本地用户看到远端画面闪现颠倒。

API 变更

新增

• getAudioMixingDuration[2/2]
• startAudioRecording[3/3]
• getEffectDuration
• setEffectPosition
• getEffectCurrentPosition
• playEffect[3/3]
• startAudioMixing[2/2]
• LOCAL_VIDEO_STREAM_ERROR 中新增 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(8)
• 错误码: ERR_ALREADY_IN_RECORDING(160)

修改

• onAudioMixingStateChanged

废弃

• getAudioMixingDuration[1/2]
• startAudioRecording[2/3]
• playEffect[1/2]
• startAudioMixing[1/2]
• 以下常量：
  • MEDIA_ENGINE_AUDIO_ERROR_MIXING_OPEN
  • MEDIA_ENGINE_AUDIO_ERROR_MIXING_TOO_FREQUENT
  • MEDIA_ENGINE_AUDIO_EVENT_MIXING_INTERRUPTED_EOF

3.3.2 版

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

• Mac 上使用神奇效果最小化共享的窗口时，远端用户看到扭曲的画面。
• 特定场景下，接收到的自定义视频帧画面旋转。

3.3.1 版

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

新增特性

基础变声

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

改进

1. AES-GCM 加密模式

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

• AES_128_GCM: 128 位 AES 加密，GCM 模式。
• AES_256_GCM: 256 位 AES 加密，GCM 模式。

2. 远端音频统计

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

问题修复

该版本修复了如下问题：

• 开启听声辨位后，无法通过 onAudioVolumeIndication 回调获取远端用户音量。
• 部分设备在短时间内连续编码关键帧时，偶现视频硬件编码器工作异常。

API 变更

新增

• setVoiceConversionPreset
• encryptionMode 中新增 AES_128_GCM 和 AES_256_GCM
• onRemoteAudioStats 中新增 mosValue

3.3.0 版

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

升级必看

1. 集成变更

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

2. 订阅行为变更

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

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

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

3. 人声状态行为变更

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

新增特性

1. 频道媒体选项

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

2. 云代理

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

3. AI 降噪

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

4. 歌唱美声

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

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

5. 设置日志文件

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

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

6. 采集画质

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

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

7. 创建数据流

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

改进

1. 原始音频数据

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

• onPlaybackFrameBeforeMixing
• onMixedFrame
• isMultipleChannelFrameWanted
• onPlaybackFrameBeforeMixingEx

2. 远端音频统计

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

问题修复

• 特定机型上，设备被插入耳机后，采集音频失败。
• Android 10 设备上偶现的采集本地音频失败的问题。
• 通过 MediaIO 方式自定义 Texture 格式的视频源时，偶现视频渲染异常。

API 变更

新增

• setVoiceBeautifierParameters
• SINGING_BEAUTIFIER 枚举值
• enableDeepLearningDenoise
• joinChannel[2/2]
• switchChannel[2/2]
• createDataStream
• RtcEngineConfig 类中新增 mLogConfig 成员变量
• onPlaybackFrameBeforeMixing
• onMixedFrame
• isMultipleChannelFrameWanted
• onPlaybackFrameBeforeMixingEx
• RemoteAudioStats 类中新增 qoeQuality 和 qualityChangedReason 成员变量
• setCloudProxy
• LocalVideoStats 类中新增 captureBrightnessLevel 成员变量
• CameraCapturerConfiguration类中新增 width 和 height 成员变量
• CAPTURER_OUTPUT_PREFERENCE enum 中新增 CAPTURER_OUTPUT_PREFERENCE_MANUAL(3)
• 错误码：ERR_MODULE_NOT_FOUND(157)

修改

• onAudioMixingStateChanged

废弃

• setDefaultMuteAllRemoteVideoStreams
• setDefaultMuteAllRemoteAudioStreams
• setLogFile
• setLogFileSize
• setLogFilter
• createDataStream

3.2.1 版

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

• IPv6 场景下的高概率崩溃问题。
• 调用 enableEncryption 后，onFirstLocalVideoFramePublished 回调无法被触发。

3.2.0 版

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

升级必看

1. 集成变更

SDK 包变更

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

• libagora-fdkaac.so: Fraunhofer FDK AAC 动态库。
• libagora-mpg123.so: mpg123 动态库。
• libagora-soundtouch.so: SoundTouch 动态库。
• libagora-ffmpeg.so: FFmpeg 动态库。

如果你将 SDK 升级到 v3.2.0 或更高版本，请务必将上述文件拷贝至 libagora-rtc-sdk.so 所在文件夹中。

此外，该版本将 SDK 包中的 libagora-crypto.so 文件合并入 libagora-rtc-sdk.so 文件中。集成 libagora-rtc-sdk.so 后，你可以直接使用内置加密功能。

拼写更正

该版本更正了 API 拼写错误，将 USER_PRIORITY_NORANL 修改为 USER_PRIORITY_NORMAL。

2. 云代理

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

3. 安全合规

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

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

新增特性

极速直播

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

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

详见极速直播产品概述。

改进

1. 会议场景

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

2. 美声与音效

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

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

3. 互动直播延时

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

4. CDN 转码推流

该版本在 LiveTranscoding 类中新增 videoCodecType 属性，支持设置转码输出视频流的编解码类型为 H.264 或 H.265。

问题修复

音频

• 该版本修复了用户使用小米音箱进行通话时偶现的录音问题。

视频

• 修复了发送端使用 vivo X30 时，接收端出现黑屏的问题。
• 修复了发送端使用 Android TV 频繁进、出频道时，接收端偶现黑屏的问题。

API 变更

新增

• setClientRole
• setAudioEffectPreset
• setVoiceBeautifierPreset
• setAudioEffectParameters
• AUDIO_SCENARIO_TYPE enum 中新增 AUDIO_SCENARIO_MEETING(8)
• LiveTranscoding 类中新增 videoCodecType 属性

废弃

• setLocalVoiceChanger
• setLocalVoiceReverbPreset
• getSmoothRenderingEnabled（C++）

3.1.3 版

该版本于 2020 年 10 月 13 发布，修复了离开频道时偶现的崩溃问题。

3.1.2 版

该版本于 2020 年 9 月 14 日发布。该版本修复了如下问题：

• 使用 MediaIO 方式切换视频源时画面会卡住。
• onFirstLocalVideoFrame 和 onFirstRemoteVideoFrame 回调的触发时机不准确。

3.1.1 版

该版本于 2020 年 8 月 27 日发布。该版本修改了区域访问限制的区域码 AreaCode，最新区域码如下：

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

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

3.1.0 版

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

新增特性

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

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

• onAudioPublishStateChanged: 音频发布状态发生改变。
• onVideoPublishStateChanged: 视频发布状态发生改变。
• onAudioSubscribeStateChanged: 音频订阅状态发生改变。
• onVideoSubscribeStateChanged: 视频订阅状态发生改变。

2. 本地首帧发布回调

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

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

3. TextureView 支持

为支持用户在屏幕共享等场景下对视频画面进行缩放、旋转和平移操作，该版本新增 CreateTextureView 方法，向你返回 Android 系统的 TextureView。请根据实际场景并参考 API 文档，在 CreateRendererView 和 CreateTextureView 之中选择一种使用。

4. 自定义数据上报

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

改进

1. 指定访问区域完善

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

• AREA_CODE_JAPAN: 日本。
• AREA_CODE_INDIA: 印度。

2. 屏幕共享

为提升屏幕共享的用户体验，该版本在 IVideoSource 类中新增以下回调：

• getCaptureType: 指定自采集的视频源类型。
• getContentHint: 指定自采集屏幕共享视频的内容类型。

3. CDN 直播推流

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

4. 加密

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

• setEncryptionSecret
• setEncryptionMode

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

5. 通话中质量透明

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

• LocalAudioStats 类新增 txPacketLossRate，表示本端到声网边缘服务器的物理音频丢包率 (%)。
• LocalVideoStats 类新增：
  • txPacketLossRate: 本端到声网边缘服务器的物理视频丢包率 (%)。
  • captureFrameRate: 本地视频采集帧率 (fps)。
• RemoteAudioStats 和 RemoteVideoStats 类中新增 publishDuration，表示远端音频流和视频流的累计发布时长（毫秒）。

6. 设置音频编码属性

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

Profile	3.1.0 版本	3.1.0 版本之前
AUDIO_PROFILE_DEFAULT	直播场景: 64 Kbps 通信场景: 18 Kbps	直播场景: 52 Kbps 通信场景: 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

7. 日志扩容

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

8. OPPO 耳返优化

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

• Reno4 Pro 5G
• Reno4 5G

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

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

10. 其他改进

• 降低了音频延时。
• 降低了远端用户音频首帧解码时间。

问题修复

该版本修复了如下问题：

• 调用 setAudioMixingPitch 方法时，部分参数不生效。
• 特定场景下视频画面模糊。
• 视频自采集场景下，app 偶现崩溃。

API 变更

新增

• onAudioPublishStateChanged
• onVideoPublishStateChanged
• onAudioSubscribeStateChanged
• onVideoSubscribeStateChanged
• onFirstLocalAudioFramePublished
• onFirstLocalVideoFramePublished
• CreateTextureView
• enableEncryption
• LocalAudioStats 类中新增 txPacketLossRate
• LocalVideoStats 类中新增 txPacketLossRate 和 captureFrameRate
• RemoteAudioStats 和 RemoteVideoStats 类中新增 publishDuration
• IVideoSource 类中新增 getCaptureType 和 getContentHint 回调
• onRtmpStreamingEvent
• 错误码: ERR_NO_SERVER_RESOURCES(103)
• 警告码:
  • WARN_ADM_RECORD_IS_OCCUPIED(1033)
  • WARN_ADM_RECORD_ABNORMAL_FREQUENCY(1021)
  • WARN_ADM_PLAYOUT_ABNORMAL_FREQUENCY(1020)
  • WARN_APM_RESIDUAL_ECHO(1053)

废弃

• setEncryptionSecret
• setEncryptionMode
• onFirstLocalAudioFrame

3.0.1.1 版

该版本于 2020 年 6 月 18 日发布。主要修复如下问题：

• Android 6 及以上且 CPU 为 x86 架构的手机出现崩溃。
• registerVideoRenderFactory 方法（已废弃）导致的崩溃。
• 美颜功能不生效。
• 特定场景下视频自采集不生效。

3.0.1 版

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

升级必看

视频观测位置 (C++)

自 v3.0.1 起，如果你想要获取 onPreEncodeVideoFrame 回调中的视频数据，除实现该回调外，还需要在 getObservedFramePosition 中将 POSITION_PRE_ENCODER (1 << 2) 设置为观测位置。

新增特性

1. 调整音乐文件音调

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

2. 变声与混响

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

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

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

3. 人脸检测

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

4. 全屏显示视频

为提高用户观看视频的体验，该版本在视频显示模式中新增 RENDER_MODE_FILL 模式。设置该模式后，视频尺寸会进行缩放和拉伸直至充满显示视图。你可以在调用以下方法设置用户视图时选择该显示模式：

• setupLocalVideo
• setupRemoteVideo
• setLocalRenderMode
• setRemoteRenderMode

5. 自渲染远端视图多频道支持

在多频道场景下，为方便通过 RtcChannel 类加入频道的用户使用视频自渲染功能，该版本在 RtcChannel 类新增 setRemoteVideoRenderer 方法。

6. 远端音视频数据后处理多频道支持

在多频道场景下，为方便后处理各频道的远端音视频数据，该版本新增如下 C++ 接口：

• IAudioFrameObserver 类中新增 isMultipleChannelFrameWanted 和 onPlaybackAudioFrameBeforeMixingEx。
• IVideoFrameObserver 类中新增 isMultipleChannelFrameWanted 和 onRenderVideoFrameEx。

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

改进

设置视频观测位置 (C++)

成功注册视频观测器后，你可以在视频处理的各节点观测并获取想要的视频数据，如本地采集的视频数据，接收的远端视频数据等。为降低设备耗能，该版本允许自定义视频观测位置。你可以通过修改 getObservedFramePosition 的返回值，设置只观测以下某个或多个位置的视频数据：

• 本地采集的视频数据
• 接收远端发送的视频数据
• 本地编码前的视频数据

其他改进

• 该版本基于华为 EMUI 10 版本以上的手机，实现了耳返低延时。
• 该版本优化了通话时的音频效果。频道中多个用户同时讲话时，不会减弱任何一方的音频效果。
• 该版本降低了对设备整体 CPU 的占用。

问题修复

• 修复了 onRemoteAudioStateChanged 回调不准、音频无声、混音、声音卡顿等问题。
• 修复了偶现的黑屏问题。
• 修复了通话无法正常结束、onClientRoleChanged 回调多次、偶现崩溃、上麦逻辑、加密互通等问题。

API 变更

新增

• setAudioMixingPitch
• 以 VOICE_BEAUTY 为前缀、以 GENERAL_BEAUTY_VOICE 为前缀和以 AUDIO_REVERB_FX 为前缀的枚举值，以及 AUDIO_VIRTUAL_STEREO 枚举值
• enableFaceDetection
• onFacePositionChanged
• RENDER_MODE_FILL
• RtcChannel 中新增 setRemoteVideoRenderer
• RemoteAudioStats 中新增 totalActiveTime
• RemoteVideoStats 中新增 totalActiveTime

3.0.0.2 版

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

新增特性

设置区域访问限制

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

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

问题修复

该版本修复了音频无声的问题。

API 变更

新增

create

3.0.0 版

该版本于 2020 年 3 月 4 日发布。并于 2020 年 3 月 24 日修复了偶现的音频无声、混音、onClientRoleChanged 回调多次、崩溃等问题。

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

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

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

升级必看

1. 通信场景默认不开启视频双流

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

2. 日志默认保存路径改变

为避免权限问题，该版本默认日志路径由 /storage/emulated/0/<package name>/ 变更为 /storage/emulated/0/Android/data/<package name>/files/。

新增特性

1. 多频道管理

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

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

2. 视频原始数据

为方便开发者获取传输各阶段的视频原始数据，满足更多场景需求，该版本在 IVideoFrameObserver 类中新增如下 C++ 回调接口：

• onPreEncodeVideoFrame：获取前处理后、编码前的本地视频原始数据。该方法适用于有视频前处理需求的开发场景。
• getSmoothRenderingEnabled：设置是否对获取的视频数据进行平滑处理。平滑处理后的视频帧，出帧时间间隔会更均匀，因此视频自渲染的体验更好。

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

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

4. 媒体播放器组件

为丰富直播玩法，声网发布了媒体播放器组件，支持主播在直播过程中，播放本地或在线媒体资源，并同步分享给频道内所有用户。详情请参考《媒体播放器组件发版说明》。

改进

1. 音频编码属性

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

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

2. 镜像模式

为提升视频镜像的使用体验，该版本对以下接口进行了变动：

• 视频编码镜像：在 VideoEncoderConfiguration 结构体中，新增 mirrorMode 成员，方便设置本地视频编码的镜像模式，即远端看本地是否镜像。
• 视频渲染镜像：在 VideoCanvas 结构体中，新增 mirrorMode 成员，方便你在调用 setupLocalVideo 初始化本地视图时，设置本地看本地是否镜像，以及调用 setupRemoteVideo 初始化远端视图时，设置本地看远端是否镜像；同时在 setLocalRenderMode 和 setRemoteRenderMode 方法中新增 mirrorMode 参数，支持在通话中更新本地看本地，或本地看远端的镜像模式。

3. 质量透明

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

4. 其他提升

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

问题修复

• 修复了混音、音频录制、音频编码、回声等音频问题。
• 修复了水印、视频画面比例、画质模糊、视频不能全屏、屏幕共享黑边等视频问题。
• 修复了特定场景下偶现的 app 崩溃、日志文件、推流不稳定等问题。

API 变更

行为变更

• 该版本在调用 enableLocalAudio (false) 后，不会引起通话音量切换为媒体音量。
• 当设备连接耳机或蓝牙时，调用setEnableSpeakerPhone (true)，不会将语音路由切换到外放。

新增

• setLocalRenderMode
• setRemoteRenderMode
• VideoEncoderConfiguration 结构体新增 mirrorMode 成员
• VideoCanvas 结构体新增 channelId、mirrorMode 成员
• AudioVolumeInfo 结构体新增 channelId 成员
• RtcStats 结构体新增 gatewayRtt, memoryAppUsageRatio, memoryTotalUsageRatio, and memoryAppUsageInKbytes 成员
• createRtcChannel
• RtcChannel 类
• IRtcChannelEventHandler 类

废弃

• enableWebSdkInteroperability
• setLocalRenderMode¹，使用新的 setLocalRenderMode 取代
• setRemoteRenderMode¹，使用新的 setRemoteRenderMode 取代
• setLocalVideoMirrorMode，使用 setupLocalVideo 和 setupRemoteVideo 中的 mirrorMode 取代
• onStreamPublished 和 onStreamUnpublished，使用 onRtmpStreamingStateChanged 取代

2.9.4 版

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

该版本修复了 Android 设备上的部分异常。

2.9.3 版

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

该版本修复了如下问题：

• 通信场景下，调用 setRemoteSubscribeFallbackOption 方法也生效。
• 一对一通信场景下，下行音视频弱网下会回退为纯音频。
• 部分设备升级系统后，摄像头采集不到视频画面。

2.9.2 版

该版本于 2019 年 10 月 18 日发布。

该版本修复了部分 Android 设备上的崩溃问题。

2.9.1 版

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

新增特性

1. 人声检测

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

2. 摄像头采集方向
为方便用户在加入频道前选择使用前置或后置摄像头进行采集，该版本在 CameraCapturerConfiguration 类中新增 cameraDirection 成员变量。你可以通过 CAMERA_FRONT(1) 或 CAMERA_REAR(0) 选择使用前置或后置摄像头。

3. RGBA 视频原始数据
该版本新增支持 RGBA 格式的视频原始数据。你可以通过新增的 C++ 接口 getVideoFormatPreference，设置想要获取的视频原始数据的格式。

同时为提高开发体验，声网支持对 RGBA 格式的视频原始数据分别通过 C++ 接口 getRotationApplied 和 getMirrorApplied 接口进行旋转和镜像处理。

4. 删除指定事件句柄
在特定场景下，开发者不想再接收某些事件的回调。该版本新增 removeHandler 方法，你可以调用该方法删除不再需要的事件句柄。

改进

1. 直播水印
为提高直播水印的用户体验，解决视频方向模式为 ADAPTIVE 时，水印位置和方向可能和预期不符的问题，该版本废弃了原有的 addVideoWatermark 接口，并使用一个新的同名接口进行取代。同名接口下，声网使用 WatermarkOptions 类对水印进行设置，其中：

• visibleInPreview 成员设置本地预览是否能看见水印。
• positionInLandscapeMode/positionInPortraitMode 成员设置视频编码横屏/竖屏模式时的水印坐标。

同时，该版本对水印功能的性能进行了优化。和之前版本相比，该功能的 CPU 占用降低了 5% - 20%。

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

3. 错误码梳理
为提高用户体验，该版本对各平台的错误码 Error Code 进行了梳理。其中 Java 平台的 ErrorCode 类中，补齐如下错误码：

• ERR_ALREADY_IN_USE(19)
• ERR_WATERMARK_PATH(125)
• ERR_INVALID_USER_ACCOUNT(134)
• ERR_AUDIO_BT_SCO_FAILED(1030)
• ERR_ADM_NO_RECORDING_DEVICE(1359)
• ERR_VCM_UNKNOWN_ERROR(1600)
• ERR_VCM_ENCODER_INIT_ERROR(1601)
• ERR_VCM_ENCODER_ENCODE_ERROR(1602)
• ERR_VCM_ENCODER_SET_ERROR(1603)

各错误码的详细描述及排查办法，详见 Error Codes。

问题修复

音频

• 通信场景下，设备连接蓝牙后进行通话。退出通话后使用 YouTube 蓝牙无声。
• 通信场景下，设备连接蓝牙时，调用 setEnableSpeakerphone 方法后行为与预期不符。
• 加入频道后，语音路由异常。
• 使用 Push 方式实现视频自采集时，app 崩溃。
• 偶现音频卡顿。
• 关掉蓝牙耳机后，音频不走外放，而走听筒。
• 进入频道后偶现回声。
• 直播场景下，特定场景偶现杂音。
• Android 10 设备上调用 startAudioMixing 方法播放在线音乐 URL 失败。

其他

• OpenSSL 版本过低。

API 变更

新增

• startAudioRecording
• addVideoWatermark
• getVideoFormatPreference
• getRotationApplied
• getMirrorApplied
• removeHandler
• enableAudioVolumeIndication，新增 report_vad 参数
• AudioVolumeInfo 类，新增 vad 成员
• CameraCapturerConfiguration 类，新增 cameraDirection 成员

废弃

• startAudioRecording
• addVideoWatermark

2.9.0 版

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

升级必看

1. 旁路推流

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

• configPublisher
• setVideoCompositingLayout
• clearVideoCompositingLayout

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

• setLiveTranscoding
• addPublishStreamUrl
• removePublishStreamUrl
• onRtmpStreamingStateChanged

新的推流实现方法，请参考旁路推流。

2. 远端视频状态

为方便用户了解远端视频状态，该版本删除了原有的 onRemoteVideoStateChanged 接口，并使用一个新的同名接口进行取代。新接口下， state 参数扩展为 STOPPED(0)、STARTING(1)、DECODING(2)、FROZEN(3) 和 FAILED(4)。同时，新接口还增加了 reason 参数，用以报告远端视频状态发生改变的原因。因此，如果你将 Native SDK 升级至该版本，请确保重新实现 onRemoteVideoStateChanged 接口。

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

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

新增特性

1. 快速切换频道

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

2. 跨频道媒体流转发

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

• startChannelMediaRelay
• updateChannelMediaRelay
• stopChannelMediaRelay

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

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

3. 本地及远端音频状态

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

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

4. 本地音频数据

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

5. 远端音频帧拉取

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

• setExternalAudioSink
• pullPlaybackAudioFrame

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

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

改进

1. 通话中质量透明

该版本进一步扩充了 RtcStats、LocalVideoStats 和 RemoteVideoStats 类的成员。各类新增成员如下：

• RtcStats 类：累计发送音频/视频字节数及累计接收音频/视频字节数
• LocalVideoStats 类：本地视频的编码码率、宽高、发送帧数及编码类型
• RemoteVideoStats 类：远端视频在网络对抗后的丢包率

2. 直播视频质量提升

该版本改善了弱网条件下直播视频卡顿问题，提升了画面清晰度，优化了网络极端丢包情况下的直播画面流畅度。

3. 其他改进

• 优化了耳返延迟。
• 优化了 Game Streaming 模式下的音频质量。
• 优化了通信场景下用户关闭麦克风后听到的音质。

问题修复

音频

• 修复了与 Web 互通时听声辨位过程中出现的声音失真的问题。
• 修复了主播下主播将耳返音量设置为 0 后，远端听不到主播声音的问题。
• 修复了特殊场景下调用 startAudioMixing 播放音乐文件失败的问题。
• 修复了特殊机型上语音路由无法切换到蓝牙的问题。
• 修复了使用音频裸数据功能时的崩溃问题。
• 修复了断开蓝牙设备后，语音路由与默认设置不符的问题。

视频

• 修复了直播下视频自采集时偶现的崩溃问题。
• 修复了特殊场景下远端观众看主播画面黑屏的问题。

其他

• 修复了偶现的旁路推流串流的问题。
• 修复了特殊机型上偶现的加入频道后崩溃的问题。

API 变更

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

新增

• setExternalAudioSink
• pullPlaybackAudioFrame
• onLocalAudioStateChanged
• onRemoteAudioStateChanged
• onRemoteVideoStateChanged
• onLocalAudioStats
• switchChannel
• startChannelMediaRelay
• updateChannelMediaRelay
• stopChannelMediaRelay
• onChannelMediaRelayStateChanged
• onChannelMediaRelayEvent
• RtcStats 类新增 txAudioBytes，txVideoBytes，rxAudioBytes 和 rxVideoBytes 成员
• LocalVideoStats 类新增 encodedBitrate，encodedFrameWidth，encodedFrameHeight，encodedFrameCount 和 codedType 成员
• RemoteVideoStats 类新增 packetLossRate 成员

废弃

• onMicrophoneEnabled，请改用 onLocalAudioStateChanged 的 LOCAL_AUDIO_STREAM_STATE_CHANGED(0) 或 LOCAL_AUDIO_STREAM_STATE_RECORDING(1)。
• onRemoteAudioTransportStats，请改用 onRemoteAudioStats。
• onRemoteVideoTransportStats，请改用 onRemoteVideoStats。

删除

• configPublisher
• setVideoCompositingLayout
• clearVideoCompositingLayout
• onRemoteVideoStateChanged

2.8.2 版

该版本于 2019 年 8 月 1 日发布。修复了与 Web SDK 的互通问题。

2.8.1 版

该版本于 2019 年 7 月 20 日发布。新增特性详见下文。

新增特性

• 支持 x86-64 位系统。
• 支持 Android Q 系统。

2.8.0 版

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

新增特性

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

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

• registerLocalUserAccount
• joinChannelWithUserAccount

对于其他接口，声网沿用 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. 音视频卡顿回调

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

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

改进

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

修复问题

音频

• 修复了特定场景下偶现的音频卡顿的问题。

视频

• 修复了停止接收视频流后再恢复接收，视频流变为小流，且恢复为大流时间过慢的问题。

其他

• 修复了指定的 Log 输出文件夹不存在时，没有生成日志文件，且默认日志文件中断的问题。

API 变更

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

新增

• registerLocalUserAccount
• joinChannelWithUserAccount
• getUserInfoByUid
• getUserInfoByUserAccount
• onLocalUserRegistered
• onUserInfoUpdated
• RemoteAudioStats 类中新增 numChannels，receivedSampleRate，receivedBitrate，totalFrozenTime 和 frozenRate 成员
• RemoteVideoStats 类中新增 totalFrozenTime 和 frozenRate 成员

废弃

• LiveTranscoding 类中的 lowLatency 成员

2.4.1 版

该版本于 2019 年 6 月 12 日发布。新增特性、功能改进与修复问题列表详见下文。

升级必看

如下内容涉及 SDK 的行为变更。如果你是由之前版本的 SDK 升级至该版本，升级前请务必阅读。

1. 旁路推流

为提高推流服务的易用性，该版本对推流接口的参数设置进行了如下限制：

类/接口	参数限制
LiveTranscoding 类	videoFrameRate：设置转码推流的帧率，单位为 fps，取值范围为 [0, 30]，默认值为 15。如果设值超过 30，声网服务端会自动调整为 30 videoBitrate：设置转码推流的码率，单位为 Kbps，默认值为 400。用户可以根据 Video Profile 参考表中的码率值进行设置。如果设置的码率超出合理范围，服务端会在合理区间内对码率值进行自适应 videoCodecProfile：设置转码推流的视频编码规格，可设为 BASELINE、MAIN 或 HIGH。若设为其他值，服务端会改为默认值 HIGH width 和 height：设置转码推流的视频分辨率。width x height 的最小值不低于 16 x 16
AgoraImage 类	url：字符长度不得超过 1024 字节
addPublishStreamUrl	url：字符长度不得超过 1024 字节
removePublishStreamUrl	url：字符长度不得超过 1024 字节

同时，该版本在 LiveTranscoding 类中新增 audioCodecProfile 参数，支持设置音频编码的规格。默认规格为 LC-AAC。

此外，该版本还对 onStreamPublished 方法的 error 参数新增了五个错误码，方便快速定位与排查问题。

2、RemoteVideoStats 类参数更名

为更精准地表达远端视频流的统计信息，该版本将 RemoteVideoStats 类中的 receivedFrameRate 参数 更名为 rendererOutputFrameRate。

新增特性

1、添加媒体附属信息

常见的直播场景中，主播给观众分发商品链接、优惠券、在线答题等，能构建更为丰富的直播互动方式。为满足该部分社交类直播 App 开发者的需求，该版本新增 registerMediaMetadataObserver 接口以及 IMediaMetadataObserver 类，目前允许主播在发出的视频帧中添加 Metadata，发送媒体附属信息。

2、本地视频状态回调

为方便开发者了解本地视频状态，该版本新增 onLocalVideoStateChanged 回调。该回调下，本地视频有 STOPPED、CAPTURING、ENCODING 和 FAILED 四种状态。当本地视频状态为 FAILED 时，用户可以参考该回调 error 参数返回的错误码进行问题排查。该回调能帮助开发者辨别本地视频故障是由采集还是编码引起的。原有的 onCameraReady 和 onVideoStopped 回调在该版本废弃，我们不再推荐。

3、推流状态回调

为方便推流用户了解当前的推流状态，并在推流出错时了解原因排查问题，该版本新增 onRtmpStreamingStateChanged 回调。该回调下，推流有 IDLE、CONNECTING、RUNNING、RECOVERING 和 FAILURE 五种状态。当推流状态为 FAILURE 时，用户可以参考该回调 errCode 参数返回的错误码进行问题排查。原有的 onStreamPublished 和 onStreamUnpublished 回调仍可以使用，但我们不再推荐。

4、网络连接失败原因梳理

为方便开发者更好地排查网络连接相关故障，该版本梳理并整合了网络连接相关的错误码，在原有 onConnectionStateChanged 回调的 reason 参数中新增八个导致网络连接失败的原因。新增后，只要网络连接发生错误，SDK 都会返回该回调。同时该版本废弃了原有的警告码 WARN_LOOK_UP_CHANNEL_REJECTED(105) 和错误码 ERR_TOKEN_EXPIRED(109)、ERR_INVALID_TOKEN(110)。

5、本地网络连接类型回调

为方便用户了解本地网络的连接类型，该版本新增 onNetworkTypeChanged 回调。该回调下，本地网络连接有 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G 七种类型。当网络连接短暂中断时，该回调能帮助开发者辨别引起中断的原因是网络切换还是网络条件不好。

6、获取播放伴奏音量

为方便开发者获取伴奏的播放音量，排查音量相关问题，该版本新增 getAudioMixingPlayoutVolume 和 getAudioMixingPublishVolume 方法，用以分别获取音乐文件在本地和远端的播放音量。

7、精确回调远端音频首帧解码

为更精准地获取远端用户的出声时间，该版本新增 onFirstRemoteAudioDecoded 回调，用以向 App 层报告 SDK 已完成远端音频首帧解码。在远端用户加入频道后首次发送音频，或远端用户 15 秒不发音频后再次发送时，该回调均会被触发。该回调与 onFirstRemoteAudioFrame 的区别在于，onFirstRemoteAudioFrame 在收到首个音频包时触发，先于 onFirstRemoteAudioDecoded。

改进

1、在线音效叠加

为提高用户体验，构造丰富有趣的实时音视频场景，该版本新增支持同时播放多个在线音效文件。开发者可以通过多次调用 playEffect 方法，传入不同的在线音效文件的 URL，实现音效叠加。

2、质量透明

• 该版本在通话相关的统计信息 RtcStats 类中，新增 txPacketLossRate 和 rxPacketLossRate 参数，分别返回本地客户端到服务器和服务器到本地客户端的丢包率。

• 该版本对 LocalVideoStats 和 RemoteVideoStats 类作了如下变动，方便用户更精准地获取本地和远端视频流的统计信息：

  • LocalVideoStats：新增 encoderOutputFrameRate 和 rendererOutputFrameRate 参数
  • RemoteVideoStats：新增 decoderOutputFrameRate 参数，并将原有的 receivedFrameRate 参数更名为 rendererOutputFrameRate

3、美颜优化

为提升美颜效果，该版本结合主观测试的结果，对美颜选项 BeautyOptions 类中的各参数添加了默认值；同时，该版本优化了美颜算法的性能。声网实验室报告显示，优化后的算法下，GPU 消耗 和 CPU 消耗均有不同程度的下降，功耗优化约 30%。

4、其他改进

• 优化了AudioScenario 为 GAME_STREAMING 时的音质效果
• 优化了部分场景下语音和视频的延时
• SDK 包大小降低约 0.5 M
• 提高了用户修改视频属性的码率后，网络质量打分的准确性
• 默认启用音频质量通知回调。开发者无需调用 enableAudioQualityIndication 方法，也可以收到 onRemoteAudioStats 回调
• 提升了视频服务的稳定性
• 提升了推流服务的稳定性

问题修复

音频

• 修复了部分设备上插耳机后音频仍走外放的问题
• 修复了单主播模式下调用 startAudioMixing 播放伴奏时，音频无法通过蓝牙播放的问题
• 修复了直播场景下偶现的播放伴奏异常的问题

视频

• 修复了特殊场景下观众看到主播画面为黑屏的问题

其他

• 修复了用户退出频道后仍然收到 onNetworkQuality 回调的问题
• 修复了偶现的崩溃问题，提升了系统稳定性
• 修复了个别手机上出现的调用 joinChannel 后 App 闪退的问题

API 变更

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

全平台 C++ 接口行为一致

从该版本起，Native SDK 保证了各平台 C++ 接口的行为一致性，方便用户通过统一的 C++ 接口，在各平台保持业务逻辑一致。同时在 C++ 头文件的 IRtcEngine 类中实现了 RtcEngineParameters 类下的所有方法。各接口的适用范围及使用注意事项详见声网 C++ API Reference for All Platforms 首页。

新增

• getAudioMixingPlayoutVolume
• getAudioMixingPublishVolume
• onFirstRemoteAudioDecoded
• onLocalVideoStateChanged
• onNetworkTypeChanged
• onRtmpStreamingStateChanged
• registerMediaMetadataObserver
• IMetadataObserver 类
• LiveTranscoding 类新增参数 audioCodecProfile
• RtcStats 类新增参数 txPacketLossRate 和 rxPacketLossRate
• LocalVideoStats 类新增参数 encoderOutputFrameRate 和 rendererOutputFrameRate
• RemoteVideoStats 类新增参数 decoderOutputFrameRate 和 rendererOutputFrameRate（替换 receivedFrameRate）

废弃

• enableAudioQualityIndication
• onCameraReady，请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_CAPTURING(1)
• onVideoStopped，请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_STOPPED(0)
• 警告码 WARN_LOOKUP_CHANNEL_REJECTED(105)，请改用 onConnectionStateChanged 回调中的 CONNECTION_CHANGED_REJECTED_BY_SERVER(10)
• 错误码 ERR_TOKEN_EXPIRED(109)，请改用 onConnectionStateChanged 回调中的 CONNECTION_CHANGED_TOKEN_EXPIRED(9)
• 错误码 ERR_INVALID_TOKEN(110)，请改用 onConnectionStateChanged 回调中的 CONNECTION_CHANGED_INVALID_TOKEN(8)
• 错误码 ERR_START_CAMERA(1003)，请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE(4)

2.4.0 版及之前

2.4.0 版

该版本于 2019 年 4 月 1 日发布。新增特性、功能改进与修复问题列表详见下文。

新增特性

1. 美颜

常见的视频社交、在线教育和连麦直播等场景中，用户普遍希望有基础的美颜功能。该版本新增接口 setBeautyEffectOptions，用户可以调用该接口设置对比度、亮度、平滑度等参数，达到美白、磨皮、红润肤色等美颜效果。详情请参考美颜。

2. 变声和混响

在语音聊天室场景中添加变声和混响效果，能有效增强社交的趣味性。该版本在原有音效设置接口的基础上，新增 setLocalVoiceChanger 和 setLocalVoiceReverbPreset 方法，开发者无需手动设置音效参数，直接选择想要的本地语音变声或混响效果。详情请参考变声与混响。

3. 听声辨位

该版本新增 enableSoundPositionIndication 和 setRemoteVoicePosition 方法，支持本地用户听声辨位。用户需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声，然后在 setRemoteVoicePosition 中设置远端用户声音出现的位置，通过左右耳听到的声音差异，对远端用户的声音产生方位感。在多人在线游戏场景，如射击游戏中，该功能可以增加游戏角色的方位感，模拟真实场景。

4. 通话前 Last-mile 网络探测

在通话前进行 Last-mile 网络探测，可以有效帮助本地用户判断和预测上行网络质量是否良好。该版本新增通话前 Last-mile 网络探测接口 startLastmileProbeTest、stopLastmileProbeTest 及 onLastmileProbeResult，向用户反馈开始通话前上下行网络的带宽、丢包、网络抖动和往返时延数据。

5. 设置用户媒体流优先级

该版本新增接口 setRemoteUserPriority 用于设置远端用户媒体流的优先级。该方法可以与 setRemoteSubscribeFallbackOption 搭配使用。如果开启了订阅流回退选项，弱网下 SDK 会优先保证高优先级用户收到的流的质量。

6. 音乐文件播放状态

该版本为播放音乐文件新增回调 onAudioMixingStateChanged，方便用户获知音乐文件的播放状态（成功/失败），以及播放出错的原因。同时新增一个警告码 701，当播放音乐文件时，本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL 时，均会触发该警告码。

7. 设置日志文件大小

声网 SDK 有 2 个日志文件，每个文件默认大小为 512 KB。为解决该大小无法满足部分用户需求的问题，该版本新增接口 setLogFileSize，用于设置 SDK 输出的日志文件大小。

8. 云代理服务

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

功能改进

1. 质量测试与透明

• 该版本在原有的 startEchoTest 中新增参数 intervalInSeconds，用于设置返回测试结果的时间间隔。
• 该版本在本地视频流统计信息 LocalVideoStats 类中新增 targetBitrate，targetFrameRate，qualityAdaptIndication 三个参数，分别反映目标码率、目标帧率与和上次返回的本地视频流统计信息相比，本地视频质量的自适应情况。

2. 视频偏好设置

一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本提供如下功能让用户选择视频偏好：

• 弱网下画质或流畅偏好设置。该版本在视频编码属性 VideoEncoderConfiguration 类中新增 2 个参数 minFrameRate 和 degradationPrefer，分别用于设置最低视频编码帧率，以及带宽受限时编码帧率的偏好。这两个参数需要搭配使用，详情请参考设置视频属性。

• 采集时预览或性能偏好设置。该版本新增接口 setCameraCapturerConfiguration，通过设置摄像头采集偏好，用户可以根据实际场景选择优先保证设备性能还是视频质量。具体场景及参数选择，请参考 API 文档。

3. 核心质量改进

• 降低了音频延时
• 提升了视频质量和稳定性
• 缩短了远端视频出图时间
• 优化了耳返延迟和回声抑制

问题修复

音频相关

• 修复了调用 enableLocalAudio 接口导致的蓝牙断开的问题
• 新增支持中文字符音乐
• 修复了高音声音变弱的问题
• 修复了偶现的声音快放问题
• 修复了部分设备无法调节音量的问题

视频相关

• 通过增加 renderMode 的默认值，修复了用户在没有设置的情况 下，窗口和画面比例不符合引发的拉伸问题
• 部分低性能设备上出现的播放视频卡住的问题
• 优化了 SDK 出图时间

其他

• 统一了 Android 和 iOS 平台上 SDK 判断远端用户掉线的时间
• 修复了转码推流场景下，SEI 信息与媒体流不同步的问题

API 整理

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

新增

• setBeautyEffectOptions
• setLocalVoiceChanger
• setLocalVoiceReverbPreset
• enableSoundPositionIndication
• setRemoteVoicePosition
• startLastmileProbeTest
• stopLastmileProbeTest
• setRemoteUserPriority
• startEchoTest
• setCameraCapturerConfiguration
• setLogFileSize
• onAudioMixingStateChanged
• onLastmileProbeResult

废弃

• startEchoTest
• setVideoQualityParameters

其他

VideoEncoderConfiguration 类中的 frameRate 参数由 enum 型修改为 int 型。

2.3.3 版

该版本于 2019 年 1 月 24 日发布。修复问题详见下文。

问题修复

• 修复了 onNetworkQuality 回调不准确的问题。
• 修复了特定场景下华为 P9 上偶发的崩溃问题。

2.3.2 版

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

升级必看

2.3.2 整体提升直播场景下视频弱网抗丢包能力，提高流畅度，降低卡顿率。升级前，请了解以下版本兼容性:

• Native SDK 版本不能低于 1.11.0
• Web SDK（若互通）版本不能低于 2.1.0

新增功能

1. 对兴趣点自动曝光

为提升视频采集质量，该版本新增如下接口，支持对兴趣点自动曝光功能。开发者可以将需要自动曝光的区域位置发送给声网 SDK，摄像头会基于该区域自动曝光。

• isCameraExposurePositionSupported：检查设备是否支持摄像头曝光
• setCameraExposurePosition：设置摄像头曝光区域
• onCameraExposureAreaChanged：摄像头曝光区域已更改

2. 提升直播清晰度

声网 SDK 会根据网络条件进行码率自适应。为满足用户在直播场景下对视频清晰度的要求，该版本在 setVideoEncoderConfiguration 接口中新增 minBitrate 参数，强制视频编码器输出高质量图片。如果将参数设为高于默认值，在网络状况不佳情况下可能会导致网络丢包，并影响视频播放的流畅度。因此如非对画质有特殊需求，声网建议不要修改该参数的值。

3. 控制音乐文件的播放音量

为方便用户控制混音音乐文件在本地及远端的播放音量，该版本在已有 adjustAudioMixingVolume 的基础上新增 adjustAudioMixingPlayoutVolume 和 adjustAudioMixingPublishVolume 接口，用于分别控制混音音乐文件在本地和远端的播放音量。

添加新的方法后，原有的 adjustPlaybackSignalVolume 由控制人声和音乐的音量改为仅控制人声的音量。因此，如果要静音本地播放，需同时设置 adjustPlaybackSignalVolume(0) 和 adjustAudioMixingPlayoutVolume(0)。

该版本梳理了用户在音频采集到播放过程中可能会需要调整音量的场景，及各场景对应的 API，供用户参考使用。详见官网文档调整通话音量。

改进

1. 提供更透明的质量数据统计

为提升质量透明的用户体验，该版本废弃了原有的 onAudioQuality 回调，并新增 onRemoteAudioStats 回调进行取代。和原来的接口相比，新接口使用更为综合的算法，通过引入音频丢帧率、端到端的音频延迟、接收端网络抖动的缓冲延迟等参数，使回调结果更贴近用户感受。同时，该版本优化了 onNetworkQuality 的算法，对上下行网络质量采用不同的计算方法，使评分更精准。

• onRemoteAudioStats：通话中远端音频流的统计信息回调。用于替换 onAudioQuality
• onNetworkQuality：通话中每个用户的网络上下行 Last mile 质量报告回调

声网 SDK 计划在下一个版本对如下 API 进行进一步改进：

• onLastmileQuality：通话前网络上下行 Last mile 质量报告回调

该版本对数据统计相关回调进行了统一梳理，相关回调及算法详见通话中数据统计。

2. 改进获取 SDK 网络连接状态的生成策略

为提升 SDK 使用数据统计的准确性和合理性，该版本新增如下接口，用以获取 SDK 的网络连接状态，以及连接状态发生改变的原因。

• getConnectionState ：获取 SDK 的网络连接状态
• onConnectionStateChanged：SDK 的网络连接状态已改变回调

该版本废弃了原有的 onConnectionInterrupted 和 onConnectionBanned 回调。

在新的接口下，SDK 共有 5 种连接状态：未连接、正在连接、已连接、正在重新建立连接和连接失败。当连接状态发生改变时，都会触发 onConnectionStateChanged 回调。当条件满足时，原有的 onConnectionInterrupted 和 onConnectionBanned 回调也会触发，但声网不再推荐使用。

3. 优化打分反馈机制

为方便用户（开发者）收集最终用户（应用程序使用者）对使用应用进行通话或直播的反馈，该版本将 rate 接口中的打分范围缩小为 1 - 5，减少最终用户的打分干扰。声网建议在应用程序中集成该接口，方便应用程序收集用户反馈。

4. 其他改进

• 优化了直播场景下视频弱网抗丢包能力
• 加快了严重拥塞状态视频的恢复速度
• 提升了推流稳定性
• 优化了 SDK 在 Android 6.0 以上设备上的性能
• 优化了 API 的调用线程
• 增加了重新检测耳机插入和蓝牙设备连接的代码
• 降低了音频延时
• 新增了对锤子手机摄像头的适配

问题修复

SDK 相关：

• 修复了 SDK 在部分模拟器（夜神、mumu 等）上的崩溃问题
• 修复了 Android 6.0 以上 x86 so 重定位导致的崩溃问题

音频相关：

• 修复了设备在连接蓝牙的状态下，退出频道后，音频不走蓝牙的问题
• 修复了调用 startAudioMixing 播放音乐文件时出现的崩溃问题
• 修复了麦克风在禁用的状态下，设备插上耳机后，禁用失效的问题
• 修复了华为 Mate 20X 上出现的应用切至后台，使用其他应用时出现的远端听不到本地说话的问题
• 修复了 Pixel 2 设备上出现的回声问题
• 修复了外放条件下，上下麦、系统电话打断、进退频道等多种场景下，出现的无法调节外放音量的问题
• 修复了应用从后台切回前台时，出现的出声音慢的问题

视频相关：

• 修复了 x86 设备上自采集图像时硬件编码器的相关问题
• 修复了视频自采集时的偶现问题

API 整理

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

新增

• isCameraExposurePositionSupported
• setCameraExposurePosition
• getConnectionState
• adjustAudioMixingPlayoutVolume
• adjustAudioMixingPublishVolume
• onConnectionStateChanged
• onCameraExposureAreaChanged
• onRemoteAudioStats

废弃

• onAudioQuality
• onConnectionInterrupted
• onConnectionBanned

2.3.1 版

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

新增功能

关闭/重新开启本地语音功能

应用程序在加入频道时，语音功能是默认打开的。为满足用户只接收而不发送音频流的需求，该版本新增 enableLocalAudio 接口，方便应用程序在进入频道后关闭或重新开启本地语音功能。关闭本地语音功能后，应用程序会收到 onMicrophoneEnabled 回调，并停止采集本地音频流。该方法不影响接收和播放远端音频流。

该功能与 muteLocalAudioStream 的区别在于前者不采集不发送，而后者是采集但不发送。

改进

• 提升了 SDK 与 Android 设备上视频编码器的适配度。

问题修复

• 修复了直播场景下，多次上下麦后某些 Android 设备上偶现的崩溃问题。
• 修复了切换前后摄像头过程中偶现的崩溃问题。
• 修复了通信场景下，一对一通话过程中，一端关闭视频后再打开，另一端出图较慢的问题。
• 修复了直播场景下，观众端因统计有误出现的延迟的问题。
• 修复了某些 Android 设备上偶现的无法渲染视频的问题。
• 修复了某些 Android 设备上偶现的视频卡顿的问题。
• 修复了某些 Android 设备上偶现的退出频道时，如果频道内还有人在说话，会听到声音且声音破音的问题。
• 修复了采集到的视频裸数据中，视频帧的时间戳不按帧更新的问题。

2.3.0 版

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

声网 SDK 在 v2.3.0 版本中，全面提升了视频功能的稳定性及可用性，保证了更加可靠的实时通信。同时音视频质量也得到进一步提高。 视频方面，通过优化编码性能，增强了弱网对抗能力，减少卡顿时间，提升视频流畅度；音频方面，采用深度学习算法，改进了通话中的音频质量。

升级必看

• 为满足场景中视频旋转的需要，提升自定义视频源画质，该版本引入 setVideoEncoderConfiguration 替换原 setVideoProfile 接口。 setVideoProfile 接口仍可用，但不再推荐。

  • 直播场景下支持 Adaptive Mode，当发送端画面旋转时不再剪切画面，避免播放端画面出现“大头”或缩放模糊的现象。

  • 自采集场景中，可以根据输入视频帧的宽和高，动态调整输出视频帧的宽和高，尽可能避免剪切，并提供更多的图像信息给到播放端。

• 该版本中 LiveTranscoding Class 从 io.agora.livePackage 移到了 io.agora.rtc.live Package。

• 该版本修改了 API constants.java 中的拼写错误。

  • 修改前：

  public static final int SOFEWARE_ENCODER = 1;

  • 修改后：

  public static final int SOFTWARE_ENCODER = 1;

• 为更好地提升用户体验，声网 SDK 在 v2.1.0 版本中对动态密钥进行了升级。如果你当前使用的 SDK 是 v2.1.0 之前的版本，并希望升级到 v2.1.0 或更高版本，请务必参考 动态密钥升级说明 。

新增功能

本次发版新增如下功能：

1. 直播中弱网环境下视频自动回退/重开

网络不理想的环境下，直播音视频的质量都会下降。为提升直播效率，声网新增了 setLocalPublishFallbackOption 和 setRemoteSubscribeFallbackOption 两个接口。 用户设置这两个接口后，在网络条件差、无法同时保证音视频质量的情况下，SDK 会自动将视频流从大流切换为小流，或直接关闭视频流，从而保证或提高音频质量。同时 SDK 会持续监控网络质量， 并在网络质量改善时恢复音视频流。在推流回退为音频流时，或由音频流恢复为音视频流，触发 onLocalPublishFallbackToAudioOnly 或 onRemoteSubscribeFallbackToAudioOnly 回调。

2. 提前 30 秒提醒 Token 即将过期

由于 Token 具有一定的时效，在通话过程中如果 Token 即将失效，SDK 会提前 30 秒触发回调 onTokenPrivilegeWillExpire ，提醒应用程序更新 Token。当收到该回调时，用户需要重新在服务端生成新的 Token，然后调用 renewToken 将新生成的 Token 传给 SDK。

3. 按用户返回音视频上下行码率、帧率、丢包率及延迟

为方便统计每个用户的音视频上下行码率、帧率及丢包率，该版本新增 onRemoteAudioTransportStats 和 onRemoteVideoTransportStats 回调。 通话或直播过程中，当用户收到远端用户发送的音视频数据包后，会周期性地发生该回调上报，频率约为 2 秒 1 次。 回调中包含用户的 UID、音/视频接收码率、丢包率、以及延迟时间（毫秒）。 并在统计频道内通话相关数据的 Rtcstats 类中增加 lastmileDelay 参数，返回客户端到 vos 服务器的延迟。

4. 设置视频编码属性

为满足场景中视频旋转的需要，提升自定义视频源画质，该版本引入 setVideoEncoderConfiguration 替换原 setVideoProfile 接口，来设置视频编码属性。 新接口中的 VideoEncoderConfiguration 类对应一套视频参数，支持用户根据实际需要，手动设置视频的分辨率（dimension)、帧率 (frame rate)、码率 (bitrate) 以及视频方向 (orientationMode)。原接口 setVideoProfile 仍可使用，但不再推荐。

5. 直播转码新增支持设置背景图片

在设置直播转码接口 setLiveTranscoding 中，新增 backgroundImage 参数，支持设置直播转码合图的背景图片。

改进功能

• 优化了一对一音视频的质量，在降低延时、防止卡顿方面提升明显。优化效果重点覆盖东南亚、南美、非洲和中东等地区

• 直播场景下，改善了音频编码器的效率，保证通话质量的同时节省用户流量

• 采用深度学习算法，改进了通话及直播中的音频质量

问题修复

• 修复了因视频编码问题引起的 Native 设备与 Web 端互通时，Web 端看不到 Native 端视频画面的问题

• 修复了多人视频直播连麦场景下，SDK 内存异常增长的问题

• 修复了某些 Android 设备上偶现的崩溃的问题

• 修复了特定场景下某些设备上偶发的无法看到远端视图的问题

• 修复了特定场景下部分 Android 设备上无法开启本地视频的问题

• 修复了特定场景下偶现的视频重影的问题

• 修复了小米 8 上出现的本地预览黑屏、远端也看不到它的问题

• 修复了通信场景下，由小流切换到大流时，偶现的视频画面下方出现绿边的问题。

• 修复了多平台互通时，一段时间后某些 Andorid 设备上偶现的崩溃问题。

• 修复了多人连麦场景下，主播频繁进出频道时，偶现的主播内存异常增长的问题

• 修复了某些 Android 设备上偶现的黑屏的问题

• 修复了特定场景下偶现的主播加入频道、下麦再上麦后，远端用户听不到主播声音的问题

• 修复了偶现的设置推流背景图无效的问题

• 修复了通信场景下，某些设备上偶现的视频画面长宽和设置的长宽颠倒的问题

• 修复了某些设备上偶现的开启视频模式加入频道后，调用 destroy 方法无响应的问题

• 修复了频道内其他用户频繁进出频道时，Android 设备上偶现的崩溃问题

• 修复了特定场景下某些 Android 设备上无法渲染远端视频，一直黑屏的问题

• 修复了特定场景下偶现的直播观众无法调节频道内通话音量的问题

• 修复了特定场景下某些 Android 设备上偶现的应用无响应的问题

• 修复了直播场景下，动态切换分辨率时，某些 Android 设备上偶现的崩溃的问题

• 修复了直播场景下，某些 Android 设备上出现的以观众身份加入频道，上麦后无法看到主播图像的问题

• 修复了通信场景下，反复设置不同的视频编码属性进出频道后，某些 Android 设备上出现码率爬升不上的问题

• 修复了直播场景下，主播和观众频繁切换角色时，观众切主播后偶现的采集不到画面的问题

• 修复了通信场景下，反复设置不同的视频编码属性进出频道后，某些 Android 设备上偶现的采集不到画面也不发流的问题

• 修复了设置手动对焦位置并触发对焦时，某些设备上偶现的崩溃的问题

• 修复了通信过程中，特定场景下某些 Android 设备上偶现的无法打开应用摄像头和系统摄像头的问题

• 修复了通信和直播场景下，某些 Android 设备上出现的加入频道一段时候后，视频卡住不再发流的问题

• 修复了 2 人连麦过程中，一端播放背景音乐时将自己静音或关闭音频后，另一端闪退的问题

• 修复了通信场景下，反复设置不同的视频编码属性后，无法进入频道的问题

• 修复了特定场景下，预加载音效时某些设备上偶现的崩溃问题

• 修复了特定场景下，某些 Android 设备上无法输出小分辨率视频的问题

• 修复了通信场景下，某些 Android 设备上偶现的服务端无法踢人的问题

• 修复了直播场景下，主播端编码与解码端渲染的分辨率不一致的问题

• 修复了某些 Andoid 设备上偶现的无法打开硬件编码器的问题

• 修复了通信和直播场景下偶发的视频画面卡住的问题

• 修复了进入频道前暂停指定用户视频流后，某些设备上偶现的崩溃的问题

• 修复了特定场景下，视频通话切到视频直播时，某些 Android 设备上出现的卡住的问题

• 修复了直播场景下，开关闪光灯时某些 Android 设备上出现崩溃的问题

• 修复了直播场景下，某些 Android 设备上出现的观众上麦后，主播接收不到上麦观众的音视频流的问题

• 修复了直播场景下，对某些外部视频源设置编码属性时，某些 Android 设备上出现的崩溃的问题

• 修复了直播场景下，对某些外部视频源设置编码属性时，某些 Android 设备上出现的输出视频方向不正确的问题

• 修复了特定场景下，某些 Android 设备上偶发的设置弱网下视频自动回退为 Audio-only 不生效的问题

• 修复了偶现的频繁切换 Token 时，某些 Android 设备上偶现的崩溃的问题

• 修复了特定场景下，某些 Android 设备上出现的分屏异常的问题

• 修复了直播场景下，旁路推流时部分 Android 设备上偶现的旁路观众看不到拉流画面的问题

• 修复了直播场景下，由连麦切换回单主播时偶现的画面卡顿的问题

• 修复了特殊场景下偶现的 SIP 设备和 SDK 视频不互通的问题

• 修复了某些 Android 设备上偶现的无法看到对方的问题

• 修复了部分 Android 设备上偶现的视频延迟的问题

• 修复了特定场景下某些 Android 设备上出现的传视频过程中出现的崩溃的问题

API 整理

为提升用户体验，声网在 v2.3.0 版本中对 API 进行了梳理，并针对部分接口进行了如下处理：

为避免在直播转码推流中添加多个相同 User，以下接口在 v2.3.0 版本中进行删除，并将 addUser 返回类型由 void 变更为 int。

• setUser

以下接口与录制相关，在 v2.3.0 版本后不再支持。声网提供专门的 Recording SDK 用于更好的录制服务，详见声网 Recording SDK 发版说明。

• startRecordingService

• stopRecordingService

• refreshRecordingServiceStatus

• onRefreshRecordingServiceStatus

以下接口长期处于弃用状态，现进行删除，v2.3.0 版本后不再支持：

• monitorConnectionEvent

• monitorBluetoothHeadsetEvent

• monitorHeadsetEvent

• setPreferHeadset

• switchView

• setSpeakerphoneVolume

2.2.3 版

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

升级必看

为更好地提升用户体验，声网 SDK 在 v2.1.0 版本中对动态密钥进行了升级。如果你当前使用的 SDK 是 v2.1.0 之前的版本，并希望升级到 v2.1.0 或更高版本，请务必参考 动态密钥升级说明 。

问题修复

• 修复了特定场景下偶发的线上统计崩溃的问题。

• 修复了直播时部分设备上主播声音变音的问题。

• 修复了直播时特定场景下偶发的崩溃的问题。

• 修复了多人直播连麦时，SDK 内存增长的问题。

• 修复了部分设备上偶发的离开频道后，收到 onLeaveChannel 回调偏慢的问题。

• 修复了偶发的无法正常反馈频道内谁在说话以及说话者音量的问题。

• 修复了直播时偶发的观众听到主播声忽大忽小的问题。

• 修复了直播时部分设备上偶发的视频卡住的问题。

• 修复了部分设备上偶发的关闭摄像头结束通话时，程序界面无响应的问题。

• 修复了特定场景下偶发的视频窗口尺寸变化后，视频卡住的问题。

2.2.2 版

该版本于 2018 年 6 月 21 日发布。修复问题列表详见下文。

问题修复

• 修复了特定场景下偶发的线上统计崩溃的问题
• 修复了部分安卓设备上偶发的音频崩溃的问题
• 修复了直播场景下部分安卓设备上主播声音变音的问题
• 修复了偶发的无法正常反馈频道内谁在说话以及说话者的音量的问题
• 修复了部分安卓设备上偶现的离开频道后，收到 onLeaveChannel 回调偏慢的问题
• 修复了特定场景下偶发的视频窗口尺寸变化后，视频卡住的问题
• 修复了部分安卓设备上偶现的关闭摄像头结束通话时，程序界面无响应的问题

2.2.1 版

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

问题修复

• 修复了部分设备上偶现的游戏过程中 Crash 的问题。

• 修复了部分设备上无法获取声道指针的问题。

• 修复了部分设备上偶现的 Crash 问题。

• 修复了部分设备上插入耳机后无法调节音量的问题。

2.2.0 版

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

新增功能

本次发版新增如下功能：

1. 音效混响进频道

播放音效 playEffect接口新增了一个 publish 参数，用于在播放音效时，远端用户可以听到本地播放的音效。

如果你的 SDK 是由之前版本升级到 v2.2 版本，请务必关注该接口功能的变动。

2. 服务端部署代理服务器

通过部署声网提供的代理服务器安装包，设有企业防火墙的用户可以设置代理服务器，使用声网的服务。

3. 获取远端视频状态

新增 onRemoteVideoStateChanged 接口，以获知远端视频流的状态。

4. 直播添加视频水印

在本地直播及旁路直播中增加水印功能，允许用户将一张 PNG 图片作为水印添加到正在进行的本地直播或旁路直播中。新增 addVideoWatermark 和 clearVideoWatermarks 接口，以添加或删除本地直播水印；LiveTranscoding 接口中新增 watermark 参数，用于控制旁路直播中水印的添加。

改进功能

本次发版改进如下功能：

1. 当前说话者音量提示

改进 enableAudioVolumeIndication接口的功能，无论频道内是否有人说话，都会在回调中按设置的时间间隔返回说话者音量提示。

2. 频道内网络质量监测

根据用户对频道内实时网络质量监测的需求，在 onNetworkQuality 中改进了返回数据的准确度。

3. 进入频道前网络条件监测

为方便用户在进频道前检查当前网络是否能支撑语音或视频通话，在 onLastmileQuality 中，由通过恒定码率监测优化为根据用户设定的 Video Profile 的码率进行监测，提高返回数据的准确度。且在网络状态为 unknown 时，依然以 2 秒的间隔返回回调。

4. 提升音乐场景下的音质

提升了用户在播放音乐等场景下的音乐音质。

问题修复

• 修复了大量用户同时直播连麦时，偶发的抖屏现象

• 修复了某些 App 在直播过程中退到后台后，旁路推流显示异常的问题

2.1.3 版

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

升级必看

该版本的 SDK 修改了setVideoProfile 方法在直播场景下的码率值，修改后的码率值与 2.0 版本一致。

问题修复

修复了部分手机上，用户离开频道后，开启自带的录音设备时，偶现录音出错的问题。

改进

改进了通信和直播场景下屏幕共享的效果，缩短了用户从屏幕共享模式切换回普通模式需要的时间间隔。

2.1.2 版

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

升级必看

SDK 升级至 2.1.2 的直播场景后，相同分辨率下，视频更清晰，但带宽也会变大。

新增功能

在已有 setVideoProfile接口的基础上，新增一个同名接口。用户可以用此接口，根据自身业务需要，手动设置视频的分辨率、帧率和码率。

问题修复

修复了之前版本 SDK 在 dtx + aac 模式下会视频卡顿的问题。

2.1.1 版

该版本于 2018 年 3 月 16 日发布。

请正在或已集成 2.1 SDK 的客户尽快升级更新！ 本次发版修复了一个的系统风险，请尽快升级以免对服务造成影响。

2.1.0 版

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

新增功能

本次发版新增如下功能：

1. 开黑

新增了一个游戏开黑场景，用于节省流量和去除杂音，通过调用 API setAudioProfile 实现。

2. 音效均衡和音效混响

在直播场景下，主播如果需要通过内置的麦克风美化和定制自己的语音输入，可以通过调用 API setLocalVoiceEqualization 和 setLocalVoiceReverb 轻易地设置音效均衡和混响来实现所需要的效果。

3. 在线频道信息查询

新增 RESTful API 查询用户在频道中的状态信息，查询指定频道内的分角色用户列表，查询厂商频道列表，查询用户是否为连麦用户等。详见控制台 RESTful API。

4. 17 人视频

在直播场景下，同一频道内支持 17 位主播同时进行视频直播和连麦，详见七人以上视频通话。

5. 自定义视频源

声网 SDK 提供了摄像头采集的默认实现，同时允许开发者使用自定义视频源。主要适用场景和文档详见 自定义视频源和渲染器 。

6. 自定义渲染器

声网 SDK 提供了默认的渲染器实现，用来显示本地视频图像和对端视频图像。使用默认的渲染器就能满足大部分开发者需求，复杂的业务场景下，声网也开放了自定义渲染器接口。

7. 插入外部视频源

直播场景下，可以将采集到的视频添加到正在进行的直播中，直播室里的主播和观众可以一起边看电影、比赛或演出，边进行点评、互动等功能，会让现有的直播话题更广、体验更好。 仅支持拉入一路流，格式包括: RTMP, HLS, FLV。赛事直播最多同时支持 5 人连麦直播。

8. 直播优化方案

提供一套全新的 API，直播场景优化 API，将原来 API 封装在底层，更快集成，更多功能扩展性。升级到 SDK 2.1 的用户可以选择使用新 API 或者老 API，两套方案均可以使用。

9. 提示相机对焦区域

新增回调接口提示相机的对焦区域已发生改变，新增了回调 onCameraFocusAreaChanged 。

改进

本次发版改进如下功能：

改进	描述
卡顿	改善了观众模式下的卡顿现象
卡顿	改善了特定设备导致的卡顿现象
鉴权模型优化	旧鉴权模型一个密钥只能对应一个服务权限(例如加入频道)，而新的一个 Token 包含了所有的服务权限(例如加入频道，连麦，推流等)
硬件编码优化	在 Qualcomm、MTK、Hisilicon、和 Orion 芯片上适配硬件 264 编码器
硬件编码优化	改善硬件编码器优化码率控制
计费优化	计费系统针对极小分辨率统一按音频计费，例如 16 * 16

问题修复

• 修复了华为 Nexus 6p 播放杂音的问题。

• 修复了一加手机上的破音问题。

• 修复了自采集声音不正常问题。

• 修复了偶现的崩溃问题。

2.0.2 版

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

问题修复

修复了偶现的语音路由问题。

2.0 版

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

新增功能

• 通信场景支持视频大小流功能，新增 API setRemoteVideoStreamType 和 enableDualStreamMode

• 通信和直播场景下支持摄像头管理功能，新增以下 API:

  名称	描述
  isCameraZoomSupported	检测设备是否支持相机缩放功能
  isCameraTorchSupported	检测设备是否支持闪光灯常开
  isCameraFocusSupported	检测设备是否支持手动对焦功能
  isCameraAutoFocusFaceModeSupported	检测设备是否支持人脸对焦功能
  setCameraZoomFactor	设置相机缩放因子
  getCameraMaxZoomFactor	获取相机支持最大缩放比例
  setCameraFocusPositionInPreview	设置手动对焦位置，并触发对焦
  setCameraTorchOn	设置是否打开闪光灯
  setCameraAutoFocusFaceModeEnabled	设置是否开启人脸对焦功能

• 通信和直播场景下支持音频自采集功能，新增以下 API:

  名称	描述
  setExternalAudioSource	设置外部音频采集参数: 采样率，通道数等
  pushExternalAudioFrame	推送外部音频帧

• 通信和直播场景下支持服务端踢人功能。

• 新增以下 Android 模拟器支持: 夜神、雷电、逍遥。

改进

硬件编码器优化: 支持超小分辨率的编码，例如 64 x 64。

问题修复

• 修复了音频路由和蓝牙相关的若干问题。

• 优化了音量均衡控制。

1.14 版

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

新增功能

• 新增 API setAudioProfile 设置音频参数和应用场景。

• 新增 API setLocalVoicePitch 提供基础变声功能。

• 直播场景: 新增 API setInEarMonitoringVolume提供调节耳返音量功能。

改进

• 优化了在高码率下的音频体验。

• 秒开: 直播场景下，单流模式时观众加入频道 1 秒内看见主播图像 (均值为 226 ms, 网络状态良好时可达 204 ms)。

• 节省带宽:

  • 1.14 以前: 如果你选择不听某人的音频或不看某人的视频，音视频流会照发。

  • 1.14 开始: 如果你选择不听或不看某人的流，则不会下发，从而节省带宽。

• 精准的码率控制:

  • 1.14 以前: 码率控制不够精准，上下波动幅度较大。波动过大容易造成网络拥塞，增加丢包、丢帧的概率，影响了带宽估计模块的精度，特别是在弱网低码率情况下尤为明显。

  • 1.14 开始: 精准的码率控制，要多少给多少，不多给也不少给，避免波动过大造成的网络拥塞，减少传输延时，有助于减少网络卡顿。

问题修复

修复了部分 Android 机器上摄像头相关的问题。

1.13.1 版

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

优化

优化了特定场景下出现的回声问题。

1.13 版

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

新增功能

• 新增 API onClientRoleChanged 用于提醒直播场景下主播、观众上下麦的回调。

• 新增功能 Android 模拟器。

• 新增单独关闭语音播放的功能。

• 新增功能支持服务端推流失败回调。

改进

• 软编情况下，视频属性可控。

• 可以在客户端设置推流的 Profile。

修复问题

修复了部分机型上偶现的崩溃

1.12 版

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

新增功能

• 在 API 方法 setEncryptionMode里新增了加密模式 aes-128-ecb。

• 在 API 方法 startAudioRecording 里新增了参数 quality 用于设置录音音质。

• 新增了一系列 API 管理音效。

• 直播场景下， 新增了 API 方法 injectStream在当前频道内插入一条 RTMP 流。该功能目前为 beta 版。

改进

通信场景下针对 320 x 180 分辨率提供了以下改进方案:

• 网络和设备状态较差的情况下仍能保证画质流畅度。

• 网络和设备状态良好的情况下可以做到比 180P 更好的画质清晰度。

修复问题

• 修复了部分机型上蓝牙相关的语音路由问题。

• 修复了部分机型上偶现的崩溃问题。