发版说明

该版本于 2026 年 9 月 22 日发布。

新增特性Copy Anchor Link

声网高级美颜 2.1Copy Anchor Link

该版本支持声网高级美颜 2.1 API，并新增美颜人脸检测能力。使用声网高级美颜功能的客户可以检测人脸置信度。使用 RTC SDK v4.7.0 及以上版本集成声网高级美颜时，请参考实现声网高级美颜；如果仍使用 RTC SDK v4.6.x，请继续参考声网高级美颜 2.0 文档。

改进Copy Anchor Link

声网高级美颜场景性能优化Copy Anchor Link

该版本针对启用声网高级美颜的场景进行专项性能优化，720p 15fps 满帧开播的机型覆盖率大幅提高，更多中低端设备能稳定输出高清流畅的美颜画面。

音视频链路性能优化Copy Anchor Link

该版本针对音视频链路与线程调度机制做了专项优化，显著降低各音视频场景 CPU 消耗，同步提升长时间运行稳定性。

音频 SDK FFmpeg 插件集成优化Copy Anchor Link

该版本调整了音频 SDK 中 FFmpeg player 插件的加载方式。libagora-ffmpeg.so 已更名为 libagora_ffmpeg_extension.so，并由必需库调整为可选插件。SDK 包中默认包含该插件，你可以根据业务需要选择是否集成。未加载 FFmpeg player 插件时，MediaPlayer 使用系统原生播放能力，实际支持的音频文件格式取决于系统支持的容器格式和音频编解码器，不同系统版本或设备厂商可能存在差异；集成并加载 FFmpeg player 插件后，MediaPlayer 可支持更多音频格式和播放能力。

视频首帧体验优化Copy Anchor Link

该版本优化了视频帧传输调度机制，提升了频道内首个用户订阅流的出图速度。

R8/ProGuard 混淆规则配置优化Copy Anchor Link

该版本优化了 Android SDK 的 R8/ProGuard 混淆规则配置。如果你的 app 未开启 R8/ProGuard 缩减和混淆，无需额外配置；如果开启了 R8/ProGuard 缩减和混淆，则需配置声网 SDK 相关混淆规则，以避免 Native 层通过 JNI 访问的 Java 类、成员或方法被移除或重命名。你可以继续使用 -keep class io.agora.**{*;} 快速配置，或使用 SDK 提供的 consumer-proguard-rules.pro 做精细化配置。

1v1 连麦延时体验优化Copy Anchor Link

该版本优化了视频1v1等实时互动场景下的音视频策略，在保障画质的前提下改善端到端延迟，并提升突发抖动等弱网场景下的播放流畅性。

音频场景码率优化Copy Anchor Link

该版本优化了音频场景下的码率开销，保障音质的前提下提升了音频流传输效率。

Native 与 Web 互通弱网体验优化Copy Anchor Link

该版本优化了视频 1v1 弱网场景下 Native 与 Web 互通的音视频体验。

媒体文件播放兼容性优化Copy Anchor Link

该版本针对不合规 MP3 文件做了针对性兼容适配，提升了媒体文件播放的鲁棒性。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 修复了开启音频裸数据后，从观众切换为主播时低概率出现残留上一段声音的问题。
• 修复了多人音频情况下行压力比较大时，特定 Android 设备升级后播放音频时偶现电流声或杂音的问题。
• 修复了预加载音效场景下，调用 stopEffect 停止播放后再次调用 playEffect 时，上一段音效仍有残留的问题。
• 修复了部分场景下人脸检测回调未按预期触发的现象，解决了人脸信息获取不稳定的问题。
• 修复了设备处于系统通话或音频占用状态时，本地音频状态回调异常的现象，解决了应用无法准确感知本地音频状态的问题。

该版本于 2026 年 8 月 31 日发布。

新增特性Copy Anchor Link

该版本新增以下特性：

• 新增两个回调事件，用于通知 Android 广角 / 超广角摄像头采集开启的成功或失败。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 修复了断网后 onNetworkQuality 回调报告的网络质量可能不准确的问题。
• 修复了接收端设置音频场景为AUDIO_SCENARIO_AI_CLIENT，发送端频繁停止和恢复发送音频流，当接收端网络不佳时偶现无声问题。
• 修复了使用有线耳机进行音视频互动时，在特定音频路由配置场景下偶现音质变差的问题。
• 修复了自渲染视频帧场景下，本地预览画面偶现卡住的问题。
• 修复了在 Android 模拟器上部分场景下偶现回声的问题。
• 修复了启用 Google 安全加固后，音视频互通过程中偶现 App 崩溃或无响应（ANR）的问题。
• 修复了 Android 手表连接蓝牙耳机时，音频路由可能切换到外放的问题。
• 修复了 App 集成调用 setExternalVideoSource 设置推送的外部视频源类型为已编码的视频帧（ENCODED_VIDEO_FRAME），推送的已编码视频帧包含的 SEI 信息长度如果与编码协议规定不匹配，偶现崩溃问题。
• 修复了音视频互动场景下偶现 App 崩溃的问题。
• 修复了 Web 与 Native 音视频互通场景下，偶现视频编码失败、远端视频卡顿或花屏的问题。
• 修复了开启媒体播放器缓存后，在断网场景下播放已缓存资源时，可能延迟约 10 秒并回调错误的问题。
• 修复了使用媒体播放器播放 CDN 流时，分辨率变化后偶现花屏的问题。
• 修复了 App 以通信模式（CHANNEL_PROFILE_COMMUNICATION）加入频道后，调用 updateChannelMediaOptions 更新频道媒体选项后，NCS 和 RESTful API 返回的频道信息被错误识别为互动直播模式的问题。

该版本于 2026 年 2 月 9 日发布。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 部分机型开启美颜功能进行音视频互动场景下，偶现发送端黑屏或 App 崩溃。
• 音视频互动场景下偶现 App 崩溃。

该版本于 2026 年 1 月 16 日发布。

升级必看Copy Anchor Link

EncodedVideoFrameInfo 结构体删除参数 uidCopy Anchor Link

该版本删除了 EncodedVideoFrameInfo 结构体中的 uid 参数。你可以直接从 onEncodedVideoFrameReceived 回调中获取远端用户的 remoteUid 信息。如果你之前集成过相关代码，请相应更新集成逻辑。

Lite 和 Voice 包中去除音频频谱功能Copy Anchor Link

为进一步优化 SDK 包体积，该版本将音频频谱（Audio Spectrum）功能从 Lite 和 Voice SDK 包中移除。如果你需要使用音频频谱功能，请集成完整（Full）包。

其他Copy Anchor Link

• 为保证整体解码兼容性，相关解码器插件已内置在 SDK 中。

新增特性Copy Anchor Link

新增支持共享单个 AppCopy Anchor Link

从 Android 14 开始，系统支持用户在屏幕共享时选择共享整个屏幕或共享单个 App，以提升隐私保护和多任务处理能力。

该版本适配了该系统能力，在支持共享整个屏幕的基础上，新增支持共享单个 App。同时，为便于管理相关事件，新增 onLocalVideoEvent 回调，用于报告本地视频，尤其是屏幕共享相关的事件。

新增权限被授予回调Copy Anchor Link

为便于确认屏幕共享场景下的权限授权情况，该版本新增 onPermissionGranted 回调。你可以通过该回调判断当前用户授予的是相机（Camera）权限还是屏幕（Screen）权限。

Media Player 支持获取音频缓冲延迟Copy Anchor Link

为解决 K 歌场景中可能会出现的主唱与伴唱伴奏不同步的问题，该版本在 Media Player 模块中新增 getAudioBufferDelay 方法，用于获取播放媒体文件时毫秒级的音频缓冲延迟。

改进Copy Anchor Link

playEffect 支持无缝切换Copy Anchor Link

该版本新增支持音效文件的无缝切换。对于同一个音效文件，如果先调用 preloadEffect 再调用 playEffect，在播放完成或通过 stopEffect 停止播放后，SDK 不会关闭该音效文件。当再次调用 playEffect 时，SDK 会直接复用已加载的文件进行播放，从而实现循环播放和无缝切换。该能力同样适用于多频道场景。

onNetworkQuality 准确性提升Copy Anchor Link

该版本提升了 onNetworkQuality 回调中网络质量评估的准确性，使回调数据更贴近用户的主观体验。

onPlaybackAudioFrame 支持 24k 采样率的音频帧Copy Anchor Link

该版本在 onPlaybackAudioFrame 中新增支持采样率为 24000 Hz 的音频数据。在调用 setPlaybackAudioFrameParameters 设置播放音频数据格式时，可以将 sampleRate 设为 24000。

onEncodedVideoFrameReceived 回调支持获取频道 IDCopy Anchor Link

该版本在 onEncodedVideoFrameReceived 回调中新增 channelId 参数，方便你在获取编码后视频数据时识别其所属频道。

其他改进Copy Anchor Link

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

• 新增错误码 ERR_PCMSEND_FORMAT (200) 和 ERR_PCMSEND_BUFFEROVERFLOW (201)，用于报告 PCM 数据发送相关错误。
• 在弱光或暗光场景下，优化了部分设备的视频采集效果，使画面更亮。
• 录制模块 Media Recorder 新增支持录制 Media Player 和 Audio Mixing 的声音。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 接收端使用部分机型（如 Redmi 14C）进行音视频互通时，偶现发送端用户画面出现黑边的问题。
• startLocalTranscoder 接口中设置的 bitrate 不生效。
• 在部分模拟器（如雷电 9）上进行音视频互通时，接收端偶现听到电流声的问题。
• 在直播 PK 场景中，观众端启用合图视频流单独渲染功能时，偶现单独渲染的用户画面显示异常。
• 音视频互通场景下，本地调用 playEffect 播放音效后，当远端用户换为主播角色并开始说话时，本地偶现听到电流声。
• 在部分 vivo 机型上，运行 Android 15 系统的设备在关闭摄像头时，偶现 App 崩溃。
• 用户以主播身份在音频 Scenario 为 AUDIO_SCENARIO_CHATROOM 的情况下加入频道且未发布本地音频，调用 startAudioMixing 播放音乐文件后，再将音频 Scenario 切换为 AUDIO_SCENARIO_GAMESTREAMING 时，偶现听到杂音。
• 在音视频互通场景下，偶现 App 无响应（ANR）的问题。
• 修复了音视频互通过程中偶现崩溃的问题。
• 美颜功能在部分场景下不生效。

该版本于 2025 年 11 月 21 日发布。

问题修复Copy Anchor Link

• 音视频互通过程中，偶现接收端用户看到图像黑屏。
• App 通过 VPN 连接网络进行音视频互通，互通过程中偶现崩溃。
• 使用媒体播放器播放分辨率为 4K 的视频源时，出现花屏图像。
• 音视频互通过程中偶现崩溃。
• 多频道场景下，App 进行音视频互通时偶现闪退。
• 使用音频 SDK 时，onRtcStats 回调报告 memoryAppUsageRatio 值始终为 0。

该版本于 2025 年 8 月 18 日发布。

升级必看Copy Anchor Link

该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的废弃及删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。

各版本废弃及删除的 API 信息。详见 API 下架说明。

直推 CDN 相关接口废弃Copy Anchor Link

该版本废弃直推 CDN 功能的相关接口，并会在后续版本中删除，请改用服务端旁路推流。

• setDirectCdnStreamingAudioConfiguration
• setDirectCdnStreamingVideoConfiguration
• startDirectCdnStreaming
• stopDirectCdnStreaming
• DirectCdnStreamingMediaOptions
• DirectCdnStreamingStats
• DirectCdnStreamingState
• DirectCdnStreamingReason

虚拟节拍器接口废弃Copy Anchor Link

该版本废弃虚拟节拍器功能的相关接口，并会在后续版本中删除。

• startRhythmPlayer
• configRhythmPlayer
• onRhythmPlayerStateChanged

水印接口废弃Copy Anchor Link

该版本废弃水印功能的相关接口，推荐使用该版本新增的水印接口。

• addVideoWatermark[2/3]
• addVideoWatermarkEx[1/2]

冗余接口删除Copy Anchor Link

该版本删除了下列冗余接口及参数：

• setLocalPublishFallbackOption
• onLocalPublishFallbackToAudioOnly
• onDownlinkNetworkInfoUpdated
• onWlAccStats
• enableWirelessAccelerate

美妆功能实现变更Copy Anchor Link

受美颜重构的影响，自 v4.6.0 起，不再支持调用 setExtensionProperty 启用美妆功能，改用 STYLE_MAKEUP 节点实现。

新增域名白名单Copy Anchor Link

如果你由之前的版本升级到 v4.6.0 且使用了域名白名单功能（RtcEngineConfig 下的 mdomainLimit 为 true），请在白名单中添加以下域名，以确保互通顺畅：

• *.rtnsvc.com
• *.realtimemesh.com

新增特性Copy Anchor Link

多路分辨率视频流Copy Anchor Link

该版本新增多路分辨率视频流（Adaptive Bitrate Video Streaming，简称 ABR）功能，支持对同一视频源设置同时发送多路不同分辨率的视频流，并支持多频道场景。接收端通过自动/手动订阅目标分辨率的视频流。

启用 ABR 后，你可以配置不同分辨率的视频流（最多四层分辨率，即一个最高分辨率的主流和三层其他较低分辨率的视频流），并设置视频流的分辨率、码率、是否启用分层推流回退等选项来灵活控制流的发布。启用分层推流回退后，SDK 会在弱网环境下自动回退到低分辨率的视频流，确保流畅的观看体验。订阅端可根据实际需求选择想要接收的视频流。适用于会议场景、大班课、互动直播等多终端、多网络环境，可显著提升弱网下的观看体验。

具体实现方法以及和视频双流的对比可以参考进阶功能发布多路视频流 (ABR)。

多路径网络传输Copy Anchor Link

该版本新增多路径传输功能，适用于终端支持多网卡传输（比如 5G、Wi-Fi、LAN）的设备，可以有效降低甚至消除弱网带来的体验回退，适用于弱网环境、对传输稳定性要求高的实时音视频通信场景，如车载、IoT、火车、高速公路等复杂网络环境。通过在 ChannelMediaOptions 中设置 enableMultipath 为 true，可开启多路径传输能力。支持两种传输模式（MultipathMode）：

• 动态模式：（默认）根据网络状况动态选择最佳路径进行传输，适用于流量敏感、对体验要求比较高的场景，如会议、教育等。动态模式下，你可以通过 preferMultipathType 指定首选的网络传输路径（如优先 Wi-Fi 或移动网络）。
• 全冗余模式：数据会在所有可用网络路径上同时传输，适用于流量不敏感，对体验有极致要求的场景，如户外采播、平行操控等。该模式会产生额外费用，如需使用请联系技术支持。

上下行还可分别通过 ChannelMediaOptions 中的 uplinkMultipathMode、downlinkMultipathMode 配置。启用后，SDK 会通过回调 onMultipathStats 实时上报各路径的传输统计信息，包括每一个传输路径的流量消耗，便于开发者监控和优化网络表现。

视频质量评分Copy Anchor Link

该版本在 RemoteVideoStats 中新增 mosValue 成员，报告声网实时视频 MOS（平均主观意见分）评估系统对接收到的远端视频流的质量评分。评分共有 5 个档次，5 分表示视频画质优秀，画面清晰无噪点，1 分表示视频画质极差，画面严重模糊。你可以通过该参数实时观测远端视频流的主观画质表现，便于动态调整视频参数、优化用户体验，或用于质量监控和告警等场景。如需启用该功能，请联系技术支持。

支持添加多个水印Copy Anchor Link

该版本废弃了 addVideoWatermark[2/3] 和 addVideoWatermarkEx[1/2] 方法，新增 addVideoWatermark[3/3] 和 addVideoWatermarkEx[2/2] 方法，支持通过水印 ID 来给视频添加多个水印，并可对水印进行排序。如果你需要移除指定水印，可调用 removeVideoWatermark 方法。

异步销毁引擎Copy Anchor Link

该版本新增 destroy [2/2] 方法，用于销毁 RTC 引擎，且支持通过参数配置以同步或异步方式销毁引擎。异步销毁引擎时，SDK 会触发 onEngineReleased 回调。

美颜功能拓展Copy Anchor Link

新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。

Token 更新结果回调Copy Anchor Link

该版本新增 onRenewTokenResult 回调及 RENEW_TOKEN_ERROR_CODE 错误码。当调用 renewToken 方法更新 Token 后，SDK 会通过 onRenewTokenResult 回调通知 Token 更新的结果，并通过 RENEW_TOKEN_ERROR_CODE 返回详细的错误码，开发者可在回调中根据错误码及时处理 Token 更新失败的场景。

其他Copy Anchor Link

• 新增 setPlaybackAudioFrameBeforeMixingParameters[2/2] 方法用于设置 onPlaybackAudioFrameBeforeMixing 回调中返回的音频帧格式，包括采样率、声道数以及每次回调的数据采样点数。调用此方法后，SDK 会按照设定的参数返回混音前的原始音频数据，便于开发者进行自定义处理或分析。
• 新增 preloadEffectEx 方法，用于将指定音效文件预加载到指定频道，支持本地或在线音效文件，便于后续快速播放，适合多频道场景。
• 新增 playEffectEx 方法，用于在指定频道播放音效文件，支持设置循环次数、音调、空间位置、音量、是否发布到频道及播放起始位置等参数，满足丰富的音效播放需求。
• 本地截图上传功能支持通过 ContentInspectModule 中新增的 position 成员设置截图的视频观测位置，从而实现对原始视频数据或效果处理前后的视频流进行截图并上传。
• 为了提升用户使用绿幕或蓝幕开启虚拟背景功能时，人像分割的准确性和稳定性，该版本在 SegmentationProperty 中新增 screenColorType 属性，支持指定背景幕布的颜色为绿色、蓝色或自动识别。

改进Copy Anchor Link

美颜重构Copy Anchor Link

该版本对美颜功能进行了彻底重构和升级，不仅拓展了美颜功能，提升了美颜效果和性能，还解决了美颜参数配置复杂、集成成本高、美颜资源依赖网络易失效等痛点。主要改进包括：

• 新增美颜功能：新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。
• API 大幅简化：将过去版本中的基础美颜、美型、美妆、滤镜功能整合为 BEAUTY、STYLE_MAKEUP、FILTER 三个核心节点 (node)，通过 IVideoEffectObject 统一管理生命周期和参数设置，减少频繁 API 调用带来的性能负担。
• 预设模板开箱即用：提供多套预设风格模板（如“自然美颜”、“学姐妆”、“冷白滤镜”），大幅简化集成流程，无需手动调试数十项参数。
• 美颜参数动态控制：该版本新增实时获取美颜参数的能力，开发者可通过 key-value 方式动态读取或修改任意细粒度参数（如磨皮强度、口红类型）。同时支持：调用预设模板快速启用风格效果、保存主播自定义参数配置、随时重置参数至默认状态，极大提升了业务层状态同步的灵活性和开发效率。
• 美颜资源外置：该版本通过美颜资源外置化设计，将所有美颜资源（特效、滤镜、妆容）均打包为本地 bundle 文件，彻底消除因网络下载失败导致美颜失效的风险。

其他改进Copy Anchor Link

• 在与 Web 端互通时，新增对 g711 和 g722 音频编解码器的支持，进一步提升了跨平台音频播放的兼容性和清晰度。
• 优化了插件加载的方式，用 C++ 开发 Android App 支持自动加载 SDK 的动态库插件。
• 优化了屏幕共享文档场景下的共享视频清晰度。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 调用 open [1/2] 打开在线音效文件后，调用 playEffect[2/2] 开始播放，当调用 seek 指定播放位置后，音效文件会从头开始播放。
• 在媒体音量模式下，主播在频道中发布麦克风采集的音频流，同时调用 playEffect[2/2] 播放音效文件、调用 startAudioMixing[2/2] 播放音乐文件，偶现回声。
• 在 setExternalVideoSource 之后调用 registerMediaMetadataObserver 注册媒体 metadata 观测器，SDK 没有触发 metadata 观测器的回调。
• 偶现的崩溃问题。
• 调用 joinChannelEx 加入频道，然后调用 startOrUpdateChannelMediaRelay 开始跨频道媒体流转发，下麦、退出频道后重新加入频道开始连麦，偶现 onChannelMediaRelayStateChanged 回调报告 state 为 RELAY_STATE_FAILURE，code 为 RELAY_ERROR_SERVER_ERROR_RESPONSE。
• 加入频道前调用 setAudioScenario 设置音频场景为 AUDIO_SCENARIO_CHATROOM，加入频道后使用蓝牙耳机或有线耳机进行音视频互通，偶现听到杂音。

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

升级必看Copy Anchor Link

该版本对部分功能的实现方式进行了优化，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。

成员参数变更为方法Copy Anchor Link

为优化 API 设计，该版本将 PlayerInfo 中的所有成员参数变为方法。如果你的 App 中使用了 PlayerInfo 中的成员参数，请更新为对应的方法。

改进Copy Anchor Link

URL 拉流播放Copy Anchor Link

该版本进一步拓展了 URL 拉流播放的功能，支持播放 CDN URL 和本地媒体资源文件，同时可以设置从指定位置开始播放、调节播放速度、设置播放音量、在播放过程中切换播放源等，详见观众端 URL 拉流。

媒体播放器信息属性可访问Copy Anchor Link

自该版本起，媒体播放器相关信息 PlayerUpdatedInfo 中的所有属性访问修饰符已从 private 修改为 public。这一改进旨在提高类的可访问性，使得外部代码能够更方便地访问和修改这些属性。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 开启导唱功能播放多音轨歌曲时，调用 setAudioPitch 方法调整歌曲音调后出现杂音。
• 主播端调用 createCustomAudioTrack 创建自定义音频采集轨道并将 trackType 设为 AUDIO_TRACK_DIRECT，调用 pushExternalAudioFrame 将自采集音频推送到频道内，然后调用 playEffect[2/2] 播放音效，频道内的观众听主播的音频有杂音。
• 集成了 SDK 的 App 在音视频互动过程中偶现主线程阻塞导致的 UI 卡顿。
• 调用 startAudioMixing[2/2] 播放 EAC3 音频编码的 MP4 文件时偶现无声。
• 退出频道停止视频渲染后出现渲染内存泄漏。
• 调用 setCameraFocusPositionInPreview 设置手动对焦位置，摄像头拍摄缩放画面后，设置的对焦位置不准确。
• 调用 setExternalMediaProjection 设置 SDK 外部的 MediaProjection 采集屏幕视频流，当屏幕变为横屏或竖屏时，发送的视频流宽、高没有随之变化。
• 调用 openWithMediaSource 并通过 source 参数将 isLiveSource 设为 true 并播放纯视频流，播放失败。
• 使用媒体播放器打开实际不存在的本地媒体文件时，播放器状态改变回调 onPlayerStateChanged 不会报告 PLAYER_STATE_FAILED，不符合预期。
• 发送端传输多声道编码音频时，接收端偶现杂音。
• App 集成媒体播放器场景下，先后两次调用 open 打开不同媒体资源，第二次打开时，媒体播放器信息变化回调 onPlayerInfoUpdated 返回第一次媒体资源的信息，不符合预期。
• 调用 enableAudioVolumeIndication 启用用户音量提示本地发流用户和远端用户音量相关信息，用户音量提示回调 onAudioVolumeIndication 返回的本地用户音量为 0。
• 音视频互通过程中偶现 App 卡死。
• 调用 setExtensionProperty 设置 key 为 "makeup_options" 实现美妆效果失败。
• 发送端用户在光线较暗的环境中进行音视频互通，部分机型偶现本地预览的图像偏暗。
• App 调用 enableVideoImageSource 启用垫片推流功能，偶现发送端推流成功但是 onVideoPublishStateChanged 返回当前的发布状态不是 PUB_STATE_PUBLISHED，不符合预期。
• 多频道场景下，App 在调用 joinChannelEx 成功前调用 setupRemoteVideoEx 初始化远端用户视图，偶现远端用户视图首帧图像显示延时大。
• 加入频道失败后，在没有调用 leaveChannel 离开频道的情况下，再次调用 joinChannel 加入频道时偶现崩溃。

该版本于 2025 年 3 月 5 日发布。

新增特性Copy Anchor Link

AI 对话场景Copy Anchor Link

该版本新增了专为与声网对话式 AI 引擎创建的智能体互动设计的 AUDIO_SCENARIO_AI_CLIENT 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 集成 SDK 的 App 设置 targetSdkVersion 为 34，在 Android 14 系统上首次开启屏幕共享进行授权时出现崩溃。
• 同时加入两个及以上的频道，连续调用 takeSnapshotEx[1/2] 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。
• 使用媒体播放器时，调用 pause 暂停播放后，调用 seek 定位到指定播放位置、然后调用 play 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。
• 使用媒体播放器时，调用 switchSrc 切换媒体资源后，调用 getPlaySrc[2/2] 获取当前正在播放的媒体资源的路径没有变化。
• 用户在特定机型上进行音视频互动并使用蓝牙耳机，偶现调整手机音量后改变的是媒体音量而非蓝牙音量。
• 音视频互动时，偶现接收端观看发送端画面出现黑屏。
• 在特定机型上，调用 setCameraExposureFactor 在设备的某个特定角度设置当前摄像头的曝光系数后，当设备移动到另一个角度时，偶现视频画面变暗。
• 播放 CDN 直播流时，直播流短暂中断后恢复，偶现播放画面长时间卡住。
• 在极速直播场景下，观众通过 string 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。
• 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。

该版本于 2024 年 11 月 26 日发布。

升级必看Copy Anchor Link

该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。

强效视频降噪实现变更Copy Anchor Link

该版本调整了强效视频降噪的实现方式，删除了 VIDEO_DENOISER_LEVEL_STRENGTH，改为调用 setVideoDenoiserOptions[1/2] 启用视频降噪后，调用 setBeautyEffectOptions[1/2] 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 setVideoDenoiserOptions[1/2]。

此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 setLowlightEnhanceOptions[1/2]。

视频编码偏好变更Copy Anchor Link

为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好：

• 在 COMPRESSION_PREFERENCE 枚举类中新增 PREFER_COMPRESSION_AUTO (-1) 枚举，并替代原有的 PREFER_QUALITY (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 PREFER_LOW_LATENCY 或 PREFER_QUALITY，以获得最佳的用户体验。
• 在 DEGRADATION_PREFERENCE 枚举类中新增 MAINTAIN_AUTO (-1) 枚举，并替代原有的 MAINTAIN_QUALITY (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 MAINTAIN_FRAMERATE、MAINTAIN_BALANCED 或 MAINTAIN_RESOLUTION，以获得最优的综合质量体验 (QoE)。

16 KB 内存页大小Copy Anchor Link

自 Android 15 起，系统新增了对 16 KB 内存页大小的支持，详见 Support 16 KB page sizes。为了保证 App 的稳定性和性能表现，自该版本起，SDK 支持 16 KB 内存页大小，确保可以在使用 4 KB 和 16 KB 内存页大小的设备上无缝运行，提升兼容性并避免崩溃。

新增特性Copy Anchor Link

高级美颜Copy Anchor Link

该版本新增以下两种高级美颜功能：

• 美型：调用 setFaceShapeBeautyOptions[1/2] 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 setFaceShapeAreaOptions[1/2] 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。
• 美妆：调用 setExtensionProperty 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。

有关美型和美妆的实现步骤，详见实现高级美颜。

秀场直播场景Copy Anchor Link

该版本在 VideoScenario 类下新增枚举 APPLICATION_SCENARIO_LIVESHOW(3)（秀场直播），你可以调用 setVideoScenario 将视频业务场景设置为秀场直播。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，例如，默认开启音视频帧加速渲染来提升首帧出图体验，无需再额外调用 enableInstantMediaRendering，同时增强了在弱网环境和低端设备上的画质和流畅度表现。

限制视频渲染帧率Copy Anchor Link

该版本新增 setLocalRenderTargetFps 和 setRemoteRenderTargetFps 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。

在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。

URL 拉流播放Copy Anchor Link

URL 拉流播放功能主要用于直播场景，观众端可以直接通过 openWithUrl 打开特定的 URL 来播放实时媒体流，无需显示调用加入频道、订阅等 API，极大简化了观众端观看直播流的 API 调用。

在播放的过程中，观众端可以通过 setAbrSubscriptionLayer 设置订阅视频大小流，并可以在大小流之间实现平滑切换。如果对视频体验有更高要求，可以联系技术支持开通 ABR（Adaptive Bitrate，自适应码率）功能。启用该功能后，可以自定义不同层级的视频流分辨率，观众可以实现不同分辨率视频流的平滑切换。

当网络情况不稳定时，观众端可以调用 setAbrFallbackLayer 来设置订阅的视频流的回退选项。SDK 会以你指定的最低质量层级对应的视频流分辨率为下限，在此范围内根据网络状况动态调整分辨率。实现细节详见观众端 URL 拉流。

滤镜效果Copy Anchor Link

该版本新增 setFilterEffectOptions[1/2] 方法，你可以在 config 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 built_in_whiten_filter.cube 文件，用于快速实现美白滤镜效果。

本地音频合流Copy Anchor Link

该版本新增本地音频合流功能，你可以调用 startLocalAudioMixer 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 stopLocalAudioMixer 方法停止本地音频合流；在合流过程中，可以调用 updateLocalAudioMixerConfiguration 方法更新正在合流的音频流配置。

该功能的使用场景示例如下：

• 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。
• 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。
• 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。

外部 MediaProjectionCopy Anchor Link

该版本新增 setExternalMediaProjection 方法，该方法支持你自行设置外部 MediaProjection，并取代 SDK 申请的 MediaProjection。

如果你具备自行申请 MediaProjection 的开发能力，可通过该功能实现更加灵活的屏幕采集。

EGL 环境上下文Copy Anchor Link

该版本新增了 setExternalRemoteEglContext 方法，用于设置远端视频流渲染的 EGL 环境上下文。使用 Texture 格式的视频数据进行远端视频自渲染时，你可以通过该方法替换 SDK 默认的远端 EGL 环境上下文，实现统一的 EGL 上下文管理。

色彩空间设置Copy Anchor Link

该版本在 VideoFrame 和 ExternalVideoFrame 中新增了 colorSpace，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。

改进Copy Anchor Link

虚拟背景算法优化Copy Anchor Link

该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。

录制本地预览视频Copy Anchor Link

该版本在 RecorderStreamInfo 中新增 type 成员。当调用 createMediaRecorder 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 MediaRecorderConfiguration 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 startRecording 即可开始录制本地预览的视频。

指定视频观测位置截图Copy Anchor Link

该版本新增 takeSnapshot[2/2] 和 takeSnapshotEx[2/2] 方法，你可以在调用该方法时通过 config 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。

自定义音频采集改进Copy Anchor Link

该版本在 AudioTrackConfig 中新增了 enableAudioProcessing 成员参数，用于控制是否对 AUDIO_TRACK_DIRECT 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 false，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。

其他改进Copy Anchor Link

• 通过拼接视频帧和 Alpha 数据实现 Alpha 透明特效的应用场景下，提升了接收端的渲染性能，有效减少卡顿和延迟。
• 优化了调用 queryDeviceScore 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。
• 调用 switchSrc 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 onPlayerEvent 回调报告 PLAYER_EVENT_SWITCH_ERROR 事件，表示媒体资源切换时发生错误。
• 调用 setPlaybackSpeed 设置音频文件的播放速度时，最低支持 0.3 倍速播放。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 当发送端视频源类型为 JPEG 格式时，偶现接收端帧率低于预期。
• 在播放音乐内容中心的音乐资源时，偶现杂音和卡顿。
• 在 App 没有获取麦克风权限时，通过 IAgoraMusicPlayer 播放伴奏音乐偶现卡顿。
• 音视频互动过程中被系统来电打断后，通过 onAudioVolumeIndication 回调上报的用户音量错误。
• 在接收端默认订阅视频小流、加入频道时不自动订阅任何视频流的前提下，加入频道后调用 muteRemoteVideoStream(uid,false) 恢复接收视频流，但接收到的视频流为视频大流，不符合预期。
• 调用 startAudioMixing[1/2] 后，立即调用 pauseAudioMixing 暂停播放音乐文件不生效。
• 音视频互动过程中偶现崩溃。

该版本于 2024 年 8 月 8 日发布。

问题修复Copy Anchor Link

修复了因上传错误导致 io.agora.rtc:full-rtc-basic:4.4.0 和 io.agora.rtc:voice-rtc-basic:4.4.0 在 Maven Central 上无法正常使用的问题。

该版本于 2024 年 8 月 5 日发布。

升级必看Copy Anchor Link

该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。

1. 为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的 ExtensionContext 了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。

   原有回调	现有回调
   onEvent	onEventWithContext
   onStarted	onStartedWithContext
   onStopped	onStoppedWithContext
   onError	onErrorWithContext

   表格内容超出当前宽度，可横向滚动查看更多列。

2. 该版本删除了 onMetadataReceived 回调中的 buffer、uid、timeStampMs 参数，你可以通过新增的 metadata 参数来获取 Metadata 的相关信息，包括 timeStampMs（发送数据的时间戳）、uid（用户 ID）、channelId（源频道名称）等。

新增特性Copy Anchor Link

Lite SDKCopy Anchor Link

自该版本起，声网推出 Lite 版 SDK，该 SDK 中仅包含音视频基础能力、对高阶音视频处理的功能进行部分裁剪，可有效减少集成 SDK 后的 App 体积。

• Lite SDK 支持手动集成或三方仓库集成，详见下载和集成 SDK。
• Lite SDK 包含的动态库信息详见减小 App 体积。
• Lite SDK 支持的 API 清单详见 Lite SDK API 列表。
• 使用 Lite SDK 播放媒体文件时的限制和注意事项详见 RTC SDK 支持播放哪些格式的音频文件？

Alpha 透明特效Copy Anchor Link

该版本新增 Alpha 透明特效功能，支持在 SDK 采集和自定义采集视频的场景下，在发送端发布视频帧的 Alpha 通道、在接收端对 Alpha 通道进行渲染处理，实现透明礼物特效、接收端自定义主播背景等：

• VideoFrame 和 AgoraVideoFrame 中新增 alphaBuffer：设置 Alpha 通道数据。
• AgoraVideoFrame 中新增 fillAlphaBuffer：对于 BGRA 或 RGBA 格式的视频数据，设置是否自动提取 Alpha 通道数据并填入到 alphaBuffer 中。
• VideoFrame 和 AgoraVideoFrame 中新增 alphaStitchMode：设置 alphaBuffer 和视频帧拼接的相对位置。

另外，AdvanceOptions 中新增成员 encodeAlpha，用于设置是否将 Alpha 信息编码并发送到远端。SDK 默认不对 Alpha 信息进行编码发送；如果需要对 Alpha 信息编码发送至远端（例如开启了虚拟背景功能），请显式调用 setVideoEncoderConfiguration 设置视频编码属性，并将 encodeAlpha 设置为 true。

AI 调音器Copy Anchor Link

该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 enableVoiceAITuner 方法并传入 VOICE_AI_TUNER_TYPE 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。

版权音乐优化Copy Anchor Link

• 该版本在 IAgoraMusicPlayer 类下新增 setPlayMode 方法，用于设置音乐资源的播放模式。在在线 K 歌房等场景下，你可以根据需求启用伴唱、原唱或导唱模式。
• 该版本废弃了 IAgoraMusicPlayer 类下的 destroy[1/2] 方法。如需销毁音乐播放器，请改用IAgoraMusicContentCenter 类下新增 destroyMusicPlayer 方法。

1v1 视频通话场景Copy Anchor Link

该版本在 VideoScenario 类下新增枚举 APPLICATION_SCENARIO_1V1（1v1 视频通话）。你可以调用 setVideoScenario 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。

改进Copy Anchor Link

自适应硬解支持Copy Anchor Link

该版本新增自适应硬解支持，改进了低端机的渲染流畅性，有效降低系统负载。

人脸区域美颜Copy Anchor Link

为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。

其他改进Copy Anchor Link

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

• 优化了传输策略，调用 enableInstantMediaRendering 不再对传输链路的安全性产生影响。
• 废弃了冗余枚举值 CLIENT_ROLE_CHANGE_FAILED_REQUEST_TIME_OUT、CLIENT_ROLE_CHANGE_FAILED_CONNECTION_FAILED。
• 优化了以下 API 的参数类型。此改进有助于提升代码的可读性，减少潜在的错误，并便于后续维护。
  • 废弃了 option 参数为 int 类型的 setRemoteSubscribeFallbackOption[1/2]，新增了 option 参数为 StreamFallbackOptions 类型的重载函数 setRemoteSubscribeFallbackOption[2/2]。
  • 废弃了 streamType 参数为 int 类型的 setRemoteVideoStreamType[1/2]、setRemoteDefaultVideoStreamType[1/2]、setRemoteVideoStreamTypeEx[1/2]，新增了 streamType 参数为 VideoStreamType 类型的重载函数 setRemoteVideoStreamType[2/2]、setRemoteDefaultVideoStreamType[2/2]、setRemoteVideoStreamTypeEx[2/2]。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 调用 pushExternalAudioFrame 推送外部音频数据，外部音频渲染的采样率如果不是 SDK 推荐的值时，比如 22050 Hz 和 11025 Hz，声音播放失败。

该版本于 2024 年 6 月 4 日发布。

升级必看Copy Anchor Link

该版本修改了播放版权音乐的行为，当调用 IAgoraMusicPlayer 中的 play 方法播放版权音乐媒体文件时，存在以下行为变更：

• v4.3.2 以前版本：SDK 默认播放当前音频文件的第一个音轨。
• v4.3.2： SDK 默认播放伴奏。

改进Copy Anchor Link

1. 提升了 setRemoteSubscribeFallbackOption 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 setRemoteSubscribeFallbackOption 动态切换弱网环境下的音视频流回退选项。
2. 媒体播放器支持播放带有 Alpha 通道的 MP4 文件。
3. 媒体播放器全面支持播放 /assets/ 目录下或以 content:// 开头的音乐资源文件。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 音视频互动过程中偶现视频流畅度不佳。
• 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。
• 首次安装 App 或重启系统后，打开 App 并开启屏幕共享时出现崩溃。
• 接听系统电话时加入频道，挂断电话后，本地音频采集失败，远端用户听不到声音。
• 在部分机型（例如：红米 Note8）上进行互动的过程中接听系统来电并挂断后，本地播放媒体文件无声、听远端无声。
• 远端用户离开频道时偶现崩溃。
• 调用 queryCameraFocalLengthCapability 返回的 AgoraFocalLengthInfo 中，cameraDirection 和 focalLengthType 的值无法被直接读取。

该版本于 2024 年 4 月 29 日发布。

升级必看Copy Anchor Link

为确保参数命名的一致性，该版本该版本将 joinChannel[1/2] 中的 channelName 改为 channelId，将 optionalUid 改为 uid。为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。

新增特性Copy Anchor Link

摄像头广角和超广角Copy Anchor Link

为了让用户捕捉到更宽阔的视野和更完整的画面内容，该版本新增了对广角和超广角摄像头的支持。你可以先调用 queryCameraFocalLengthCapability 查询设备支持的焦距能力，然后调用 setCameraCapturerConfiguration 并将 cameraFocalLengthType 设置为支持的焦距类型，包括广角、超广角等。

摄像头多路采集Copy Anchor Link

该版本针对 Android 摄像头采集新增以下功能：

1. 支持第三个和第四个摄像头视频流的采集和发布。
   • 在 VideoSourceType 中新增 VIDEO_SOURCE_CAMERA_THIRD(11) 和 VIDEO_SOURCE_CAMERA_FOURTH(12) 枚举，分别用于指定视频源为第三个和第四个摄像头。此项改动允许你在调用 startCameraCapture 开启摄像头采集时，指定最多 4 路摄像头采集的视频流。
   • 在 ChannelMediaOptions 中新增 publishThirdCameraTrack 和 publishFourthCameraTrack 成员。调用 joinChannel[2/2] 加入频道时，将这两个成员参数设置为 true 即可在频道内发布第三个和第四个摄像头采集的视频流。
2. 支持通过摄像头 ID 指定摄像头。
   • 在 CameraCapturerConfiguration 中新增 cameraId 成员。对于多摄像头的设备，cameraDirection 无法识别或访问全部可用摄像头。这种情况下，你可以通过 Android 原生系统 API 获取摄像头 ID，再调用 startCameraCapture 并传入 cameraId 指定所需的摄像头。
   • 新增 switchCamera[2/2]，支持通过 cameraId 切换摄像头，允许 App 在运行期间基于可用摄像头的实际情况动态调整摄像头使用。

数据流加密Copy Anchor Link

该版本在 EncryptionConfig 中新增 datastreamEncryptionEnabled 成员用于启用数据流加密。你可以在调用 enableEncryption 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE 和 ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE 枚举得知。

本地视频渲染Copy Anchor Link

该版本在 VideoCanvas 中新增如下成员，以支持更多本地渲染功能。

• surfaceTexture：设置一个 Android 原生的 SurfaceTexture 对象作为提供视频图像的容器，然后使用 SDK 外部的方法自行实现 OpenGL 中的纹理绘制。
• enableAlphaMask：可以通过该成员设置接收端是否开启 Alpha 遮罩渲染。Alpha 遮罩渲染功能可以创建具有透明效果的图像或提取视频中的人像。

视频小流自适应配置Copy Anchor Link

该版本新增视频小流的自适应配置功能，当你调用 setDualStreamMode[2/2] 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示：

• 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。
• 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。

其他Copy Anchor Link

• 新增 enableEncryptionEx 方法，用于多频道场景下开启媒体流或数据流加密。
• 新增 setAudioMixingPlaybackSpeed 方法，用于设置音乐文件的播放速度。
• 新增 getCallIdEx 方法，用于多频道场景下获取通话 ID。

改进Copy Anchor Link

本地视频状态回调优化Copy Anchor Link

该版本新增如下枚举，你可以通过 onLocalVideoStateChanged 回调了解更多本地视频状态发生改变的原因：

• LOCAL_VIDEO_STREAM_REASON_DEVICE_INTERRUPT (14)：由于摄像头被其他 App 占用或 App 切后台等原因导致的视频采集中断。
• LOCAL_VIDEO_STREAM_REASON_DEVICE_FATAL_ERROR (15)：视频采集设备出错，可能由于摄像头设备故障导致。

摄像头采集改进Copy Anchor Link

优化了摄像头采集的视频处理机制，减少噪点、提高亮度、改善色彩，使采集到的图形更加清晰、明亮和真实。

虚拟背景算法优化Copy Anchor Link

为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法：

• 支持识别任意纯色背景，不再局限于绿幕。
• 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。
• 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。

降低耳返的 CPU 消耗Copy Anchor Link

该版本新增 EAR_MONITORING_FILTER_REUSE_POST_PROCESSING_FILTER(1 << 15) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。

其他改进Copy Anchor Link

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

• 提升了本地合图功能的性能和稳定性，并降低了该功能对 CPU 的占用率。
• 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。
• 新增 ROOM_ACOUSTICS_CHORUS（合唱音效），可使人声在合唱场景下更具空间立体感。
• 在 RemoteAudioStats 中新增 e2eDelay，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。
• 加入频道后调用 disableAudio 关闭音频模块，音频播放没有立即停止。
• 主播使用部分型号设备在扬声器下进行音视频互动，之后切换 App 进程到后台再切回前台，偶现本地音频采集失败，远端用户听不到主播的声音。
• 在 Android 8.0 系统的设备上，启用屏幕共享功能时 App 偶现崩溃。
• 使用摄像头采集本地视频场景下，在 App 切后台时已调用 disableVideo 或 stopPreview[1/2] 关闭视频采集，但将 App 再切回前台时，摄像头采集被打开，不符合预期。
• 当发送端用户的网络环境恶化（例如弱网）时，接收端偶现视频流畅度降低、卡顿增加。

API 变更Copy Anchor Link

新增Copy Anchor Link

• VideoCanvas 中新增 surfaceTexture 和 enableAlphaMask
• LOCAL_VIDEO_STREAM_REASON_DEVICE_INTERRUPT
• LOCAL_VIDEO_STREAM_REASON_DEVICE_FATAL_ERROR
• EncryptionConfig 中新增 datastreamEncryptionEnabled
• ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE
• ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE
• RemoteAudioStats 新增 e2eDelay
• ERR_DATASTREAM_DECRYPTION_FAILED
• ROOM_ACOUSTICS_CHORUS
• getCallIdEx
• enableEncryptionEx
• setAudioMixingPlaybackSpeed
• queryCameraFocalLengthCapability
• AgoraFocalLengthInfo
• CAMERA_FOCAL_LENGTH_TYPE
• CameraCapturerConfiguration 新增成员 cameraFocalLengthType
• VideoSourceType 新增以下枚举：
  • VIDEO_SOURCE_CAMERA_THIRD(11)
  • VIDEO_SOURCE_CAMERA_FOURTH(12)
• ChannelMediaOptions 新增以下成员：
  • publishThirdCameraTrack
  • publishFourthCameraTrack
• CameraCapturerConfiguration 新增成员 cameraId
• CAMERA_DIRECTION 中新增 CAMERA_EXTRA(2)
• switchCamera[2/2]
• EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS(1 <<15)

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

升级必看Copy Anchor Link

该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。

原始视频数据回调行为变更Copy Anchor Link

自该版本起，原始视频数据相关的回调处理从原有的固定单线程变更为随机线程，即：回调处理可以在不同的线程上进行。由于 Android 系统限制，OpenGL 必须与线程强绑定，声网建议你采取以下两种方式之一修改你的代码：

• （推荐）使用 TextureBufferHelper 类创建一个专门的 OpenGL 线程进行视频前处理或后处理（例如美颜、贴纸等效果）。
• 使用 eglMakeCurrent 方法，将每一个视频帧所需的 OpenGL 环境都关联到当前的线程中。

回调中的参数改名Copy Anchor Link

为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。

跨频道媒体流转发Copy Anchor Link

为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项：

视频自采集Copy Anchor Link

该版本起，pushExternalVideoFrameEx[1/2] 和 pushExternalVideoFrameEx[2/2] 方法分别更名为 pushExternalVideoFrameById[1/2] 和 pushExternalVideoFrameById[2/2] ，并从 RtcEngineEx 接口类迁移到 RtcEngine 接口类。

音频路由Copy Anchor Link

该版本起，ROUTE_BLUETOOTH 更名为 AUDIO_ROUTE_BLUETOOTH_DEVICE_HFP，表示音频路由为使用 HFP 协议的蓝牙设备，新增 AUDIO_ROUTE_BLUETOOTH_DEVICE_A2DP(10) 表示音频路由为使用 A2DP 协议的蓝牙设备。

远端视频流状态Copy Anchor Link

为使枚举的名称便于理解，该版本将 REMOTE_VIDEO_STATE_PLAYING 枚举名变更为 REMOTE_VIDEO_STATE_DECODING，枚举的含义不变。

本地视频状态改变原因Copy Anchor Link

LOCAL_VIDEO_STREAM_ERROR_ENCODE_FAILURE 的枚举名变更为 LOCAL_VIDEO_STREAM_REASON_CODEC_NOT_SUPPORT。

日志加密行为变更Copy Anchor Link

出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案：

• 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。
• 如有其他特殊需求，请联系技术支持并附上对应的加密日志。

IAgoraEventHandler 接口类删除Copy Anchor Link

该版本删除了 IAgoraEventHandler 接口类，该类下的所有回调事件现均通过 IRtcEngineEventHandler 接口类进行处理。

新增特性Copy Anchor Link

接收端自定义合图布局Copy Anchor Link

为支持接收端自定义多路合图流的布局，该版本新增了 onTranscodedStreamLayoutInfo 回调。当接收端收到合图服务器发送的频道内合图视频流时，该回调会被触发，上报合图视频流的布局信息、以及合图流中每一路子视频流的布局信息。接收端可以在调用 setupRemoteVideo 方法时，为合图视频流中的子视频流（通过 subviewUid 区分）设置单独的 view 进行渲染，从而达到自定义视频布局的效果。

当合图视频流中的子视频流布局发生变化时，该回调也会被触发，实时上报最新的布局信息。

通过该特性，接收端可以灵活调整本地的视图布局。当在多人视频场景下应用时，接收端只需接收并解码一路合图视频流，可以有效降低接收端解码多路视频时的 CPU 占用率和网络带宽。

多视图本地预览Copy Anchor Link

该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下：

1. 调用 setupLocalVideo 设置第一个视图：在 VideoCanvas 中设置 position 参数为 VIDEO_MODULE_POSITION_POST_CAPTURER_ORIGIN（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。
2. 调用 setupLocalVideo 设置第二个视图：在 VideoCanvas 中设置 position 参数为 VIDEO_MODULE_POSITION_POST_CAPTURER，此处观测到的视频具备视频前处理的效果。
3. 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。

查询设备评分等级Copy Anchor Link

该版本新增 queryDeviceScore 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请联系技术支持。

本地播放及发布至远端的音轨控制Copy Anchor Link

该版本新增 selectMultiAudioTrack 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 openWithMediaSource 打开媒体文件，并通过 MediaPlayerSource 中新增的 enableMultiAudioTrack 成员来开启音轨控制。

音频播放设备测试Copy Anchor Link

该版本新增 startPlaybackDeviceTest 方法，用于在加入频道前测试音频播放设备能否正常工作。你可以通过 testAudioFilePath 参数指定需要播放的音频文件，测试者如果能听到声音，说明播放设备能正常工作。测试完毕后，你需要调用新增的 stopPlaybackDeviceTest 方法停止测试。

其他Copy Anchor Link

该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。

• setRemoteSubscribeFallbackOption：设置弱网环境下订阅的音视频流回退选项。
• onRemoteSubscribeFallbackToAudioOnly：订阅流已回退为音频流或恢复为音视频流回调。
• setPlayerOption 和 setPlayerOptionString：设置媒体播放器选项，用于提供技术预览或特别定制功能。
• enableCustomAudioLocalPlayback：设置是否在本地播放外部音频源。

改进Copy Anchor Link

SDK 任务处理调度优化Copy Anchor Link

该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面：

• 远端及本地的首帧出图与出声速度提升了 10% 到 20%。
• API 的调用耗时和响应耗时缩短了 5% 到 50%。
• SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。
• SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。

耳返音量提升Copy Anchor Link

该版本为用户提供更灵活的耳返音频调整选项，支持调用 setInEarMonitoringVolume 将耳返音量设置为原始音量的 4 倍。

空间音频易用性提升Copy Anchor Link

• 该版本优化了 setZones 方法的设计，支持将 zones 参数设置为 NULL，表示清除所有隔声区域。
• 自该版本起，在调用 ILocalSpatialAudioEngine 中的方法之前，无需先取消订阅频道内所有远端用户的音频流。

视频前处理方法优化Copy Anchor Link

该版本对以下 5 个视频前处理方法新增了带 souceType 参数的重载方法，支持通过传入 sourceType 来指定视频前处理特效应用的媒体源类型（例如应用在自定义的视频采集媒体源上）：

• setBeautyEffectOptions[2/2]
• setLowlightEnhanceOptions[2/2]
• setVideoDenoiserOptions[2/2]
• setColorEnhanceOptions[2/2]
• enableVirtualBackground[2/2]

其他改进Copy Anchor Link

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

• 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。
• VideoEncoderConfiguration 中新增 codecType 成员，用于设置视频编码类型。
• AudioCaptureParameters 中新增 allowCaptureCurrentApp 成员，用于设置在屏幕共享时是否采集当前 App 中的音频。该成员默认值为 true，即：默认采集当前 App 中的音频。在个别场景下，屏幕共享采集到的 App 音频可能由于信号延迟等原因引起远端出现回声，声网建议你在此场景下将该成员设置为 false，以消除屏幕共享进程中引入的远端回声。
• 新增 onPlayerCacheStats 回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。
• 新增 onPlayerPlaybackStats 回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过 PlayerPlaybackStats 来获取当前音、视频的码率等信息。
• MusicContentCenterStateReason 中新增状态码 MUSIC_CONTENT_CENTER_STATE_REASON_HTTP_INTERNAL 表示 HTTP 内部发生错误，请稍后重试。
• 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用 setLocalAccessPoint 解析域名时的稳定性。
• 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。
• LocalAudioStats 新增 earMonitorDelay 和 aecEstimatedDelay 成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 当同时共享两路屏幕共享视频流时，onLocalVideoStats 回调上报的 captureFrameRate 为 0，不符合预期。
• 会议场景下，本地听远端用户说话偶现卡顿。

API 变更Copy Anchor Link

新增Copy Anchor Link

• onTranscodedStreamLayoutInfo
• VideoLayout
• VideoCanvas 新增 subviewUid 和 uid 成员
• VideoEncoderConfiguration 新增 codecType 成员
• AudioCaptureParameters 新增 allowCaptureCurrentApp 成员
• enableCustomAudioLocalPlayback
• selectMultiAudioTrack
• onPlayerCacheStats
• onPlayerPlaybackStats
• PlayerPlaybackStats
• MusicContentCenterStateReason 中新增 MUSIC_CONTENT_CENTER_STATE_REASON_HTTP_INTERNAL
• startPlaybackDeviceTest
• stopPlaybackDeviceTest
• LocalAudioStats 新增 earMonitorDelay 和 aecEstimatedDelay 成员
• queryDeviceScore
• MediaSourceType 中新增 CUSTOM_VIDEO_SOURCE 枚举
• setBeautyEffectOptions[2/2]
• setLowlightEnhanceOptions[2/2]
• setVideoDenoiserOptions[2/2]
• setColorEnhanceOptions[2/2]
• enableVirtualBackground[2/2]
• 新增 AUDIO_ROUTE_BLUETOOTH_DEVICE_A2DP 枚举

修改Copy Anchor Link

• pushExternalVideoFrameEx[1/2] 和 pushExternalVideoFrameEx[2/2] 方法分别更名为 pushExternalVideoFrameById[1/2] 和 pushExternalVideoFrameById[2/2]，并从 RtcEngineEx 接口类迁移到 RtcEngine 接口类
• REMOTE_VIDEO_STATE_PLAYING 枚举名变更为 REMOTE_VIDEO_STATE_DECODING
• ROUTE_BLUETOOTH 枚举名变更为 AUDIO_ROUTE_BLUETOOTH_DEVICE_HFP
• 以下枚举名中的 ERROR 字段全部修改为 REASON：
  • LOCAL_AUDIO_STREAM_ERROR_OK
  • LOCAL_AUDIO_STREAM_ERROR_FAILURE
  • LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION
  • LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY
  • LOCAL_AUDIO_STREAM_ERROR_CAPTURE_FAILURE
  • LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE
  • LOCAL_VIDEO_STREAM_ERROR_OK
  • LOCAL_VIDEO_STREAM_ERROR_FAILURE
  • LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION
  • LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY
  • LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE
  • LOCAL_VIDEO_STREAM_ERROR_CODEC_NOT_SUPPORT
  • LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND
  • PLAYER_ERROR_NONE
  • PLAYER_ERROR_INVALID_ARGUMENTS
  • PLAYER_ERROR_INTERNAL
  • PLAYER_ERROR_NO_RESOURCE
  • PLAYER_ERROR_INVALID_MEDIA_SOURCE
  • PLAYER_ERROR_UNKNOWN_STREAM_TYPE
  • PLAYER_ERROR_OBJ_NOT_INITIALIZED
  • PLAYER_ERROR_CODEC_NOT_SUPPORTED
  • PLAYER_ERROR_VIDEO_RENDER_FAILED
  • PLAYER_ERROR_INVALID_STATE
  • PLAYER_ERROR_URL_NOT_FOUND
  • PLAYER_ERROR_INVALID_CONNECTION_STATE
  • PLAYER_ERROR_SRC_BUFFER_UNDERFLOW
  • PLAYER_ERROR_INTERRUPTED
  • PLAYER_ERROR_NOT_SUPPORTED
  • PLAYER_ERROR_TOKEN_EXPIRED
  • PLAYER_ERROR_UNKNOWN
  • RTMP_STREAM_PUBLISH_ERROR_OK
  • RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT
  • RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED
  • RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT
  • RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR
  • RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR
  • RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN
  • RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT
  • RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED
  • RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND
  • RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED
  • RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER
  • RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM
  • RTMP_STREAM_PUBLISH_ERROR_NET_DOWN
  • RTMP_STREAM_PUBLISH_ERROR_INVALID_PRIVILEGE
  • RTMP_STREAM_UNPUBLISH_ERROR_OK
• MusicContentCenterStatusCode 修改为 MusicContentCenterStateReason，其中的枚举名的 STATUS_ERR 字段全部修改为 STATE_REASON：
  • MUSIC_CONTENT_CENTER_STATUS_ERR_GATEWAY
  • MUSIC_CONTENT_CENTER_STATUS_ERR_PERMISSION_AND_RESOURCE
  • MUSIC_CONTENT_CENTER_STATUS_ERR_INTERNAL_DATA_PARSE
  • MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_LOADING
  • MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_DECRYPTION
• MUSIC_CONTENT_CENTER_STATUS_OK 修改为 MUSIC_CONTENT_CENTER_STATE_REASON_OK
• MUSIC_CONTENT_CENTER_STATUS_ERR 修改为 MUSIC_CONTENT_CENTER_STATE_REASON_ERROR

删除Copy Anchor Link

• startChannelMediaRelay
• updateChannelMediaRelay
• startChannelMediaRelayEx
• updateChannelMediaRelayEx
• onChannelMediaRelayEvent

该版本于 2023 年 11 月 16 日发布。

问题修复Copy Anchor Link

该版本修复了在使用 Android 14 系统版本时可能出现的问题：

• 在屏幕共享过程中切换横竖屏模式导致当前屏幕共享进程中断，需要在弹出窗口中点击确认录制屏幕才可重新开始屏幕共享。
• 在集成 SDK 时，如果将 Android targetSdkVersion 设置为 34，导致屏幕共享不可用甚至 App 崩溃。
• 先调用 startScreenCapture 但不共享视频（设置 captureVideo 为 false）、后调用 updateScreenCaptureParameters 共享视频（设置 captureVideo 为 true）时，接收端看到的屏幕共享画面冻结。
• 采用横屏模式进行屏幕共享时，观众端看到的共享画面被拆分成两部分：一侧的画面被压缩；另一侧为黑屏。

该版本还修复了以下问题：

• 在直播场景下，观众端看到的画面偶现变形。
• 在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。

该版本于 2023 年 10 月 12 日发布。

升级必看Copy Anchor Link

兼容性变更Copy Anchor Link

该版本优化了 SDK 采集和自定义视频采集场景下 Texture Buffer 的管理方式，有效消除丢帧和崩溃隐患。自该版本起，TextureBuffer 类型的纹理格式不再包括 OES 格式，仅为 RGB 格式。你需要在处理视频数据时增加对 I420、RGB 纹理格式的适配。

新增特性Copy Anchor Link

本地截图上传更新Copy Anchor Link

为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动：

• ContentInspectModule 中的 type 新增 CONTENT_INSPECT_TYPE_IMAGE_MODERATION 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。
• ContentInspectConfig 中新增的 serverConfig 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请联系技术支持。

此外，该版本还新增了 enableContentInspectEx 方法，支持同时对多条视频流截图并上传。

进阶功能查询Copy Anchor Link

该版本新增了 isFeatureAvailableOnDevice 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。

在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。

此外，自该版本起，调用 enableVirtualBackground 和 setBeautyEffectOptions 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 -4: ERR_NOT_SUPPORTED 表示该设备不支持开启该功能。

改进Copy Anchor Link

优化虚拟背景内存占用Copy Anchor Link

该版本升级了虚拟背景算法，降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。

屏幕共享场景优化Copy Anchor Link

该版本优化了屏幕共享场景下的视频编码配置。当用户自定义视频的 width 和 height 属性时，SDK 会在保持视频与屏幕的宽高比一致的前提下，对实际的编码分辨率进行向下取整，确保最终编码分辨率不超过用户自定义的编码分辨率，从而提升了对屏幕共享流的计费准确性。

其他改进Copy Anchor Link

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

• 当调用 setPlaybackSpeed 设置音频文件的播放速度时，传入非法参数后会返回错误码 -2，表示方法中设置了无效的参数，需要重新设置参数。
• 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 在采用 H.265 编码模式时，如果 Web 端加入互动，会导致 Native 端出现冗余的 onUserEnableLocalVideo 回调：当主播调用 enableLocalVideo(true)时，接收端在收到 onUserEnableLocalVideo (enabled 为 true) 回调之前，会先收到一个 onUserEnableLocalVideo (enabled 为 false) 回调。
• 本地系统时间不正确时，偶现加入频道失败。
• 调用 playEffect[2/2] 使用相同的 soundId 播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。
• 主播调用 startAudioMixing[2/2] 播放音乐文件时，偶现主播本地无法听见音乐，远端用户可以正常听见。
• 合唱场景下，调用 preload[1/2] 加载音乐，偶现加载失败。
• 在特定机型上开启 AI 降噪偶现崩溃。
• 当本地系统时间不准确时，歌曲榜单加载失败。
• 调用一次 takeSnapshotEx 获取视频截图会收到多次 onSnapshotTaken 视频截图结果回调。
• 在仅调用 joinChannelEx 加入的频道中，调用 setEnableSpeakerphone 无法将音频路由从扬声器切换至听筒。

API 变更Copy Anchor Link

新增Copy Anchor Link

• enableContentInspectEx
• ContentInspectModule 中的 type 新增 CONTENT_INSPECT_TYPE_IMAGE_MODERATION
• ContentInspectConfig 中新增 serverConfig 可选参数
• isFeatureAvailableOnDevice

该版本于 2023 年 7 月 27 日发布。

升级必看Copy Anchor Link

该版本废弃了 IAgoraMusicContentCenter 类下的 preload[1/2] 方法并新增 preload[2/2] 方法。如果你使用了 preload[1/2] 方法实现预加载音乐资源，请在升级到该版本后更新 App 代码。

新增特性Copy Anchor Link

通配 TokenCopy Anchor Link

该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见使用通配 Token。

预加载频道Copy Anchor Link

该版本新增 preloadChannel[1/2] 和 preloadChannel[2/2] 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。

在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见使用通配 Token。

自定义视频画布背景颜色Copy Anchor Link

该版本在 VideoCanvas 中增加了 backgroundColor 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。

支持仅播放副歌片段Copy Anchor Link

该版本新增 getInternalSongCode 方法，如果你仅需要播放某一音乐资源的副歌片段，在播放前你需要调用该方法来为该副歌片段创建一个内部歌曲编号，作为该资源的唯一标识。你可以查看在线 K 歌房文档了解更多 K 歌场景方案。

改进Copy Anchor Link

摄像头采集效果提升Copy Anchor Link

该版本支持摄像头采集曝光调节。新增 isCameraExposureSupported 和 setCameraExposureFactor 方法，用于查询当前设备是否支持曝光调节和设置摄像头的曝光增益。

虚拟背景算法升级Copy Anchor Link

该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。

跨频道连麦优化Copy Anchor Link

该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 startOrUpdateChannelMediaRelay 和 startOrUpdateChannelMediaRelayEx 时，你可以指定最多 6 个目标频道。

视频编解码查询能力增强Copy Anchor Link

为提升设备编解码能力查询功能，该版本在 CodecCapInfo 中新增 codecLevels 成员。当成功调用 queryCodecCapability 后，可通过 codecLevels 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。

其他改进Copy Anchor Link

• 为了提升多种音频路由之间的切换体验，该版本新增了 setRouteInCommunicationMode 方法，用于在通话音量模式 (MODE_IN_COMMUNICATION) 下，将音频路由从蓝牙耳机切换为听筒、有线耳机或扬声器。
• 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。
• 为帮助用户了解更多类型的远端视频状态改变的原因，onRemoteVideoStateChanged 回调中新增了 REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT 枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。
• 版权音乐新增 getSongSimpleInfo 方法，可用于获取某一指定歌曲的详细信息，你可以通过触发的 onSongSimpleInfoResult 回调来获取歌曲信息。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 网络异常导致频道连接断开后，频道连接恢复较慢。
• 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。
• 自采集场景下，setBeautyEffectOptions、setLowlightEnhanceOptions、setVideoDenoiserOptions 和 setColorEnhanceOptions 无法自动加载插件。

API 变更Copy Anchor Link

新增Copy Anchor Link

• setCameraExposureFactor
• isCameraExposureSupported
• preloadChannel[1/2]
• preloadChannel[2/2]
• updatePreloadChannelToken
• getSongSimpleInfo
• onSongSimpleInfoResult
• getInternalSongCode
• preload[2/2]
• onLyricResult 中增加 songCode
• onPreLoadEvent 中增加 requestId
• setRouteInCommunicationMode
• CodecCapLevels
• VideoCodecCapLevel
• VideoCanvas 中增加 backgroundColor 成员
• CodecCapInfo 中增加 codecLevels 成员
• 增加 REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT 枚举

废弃Copy Anchor Link

• preload[1/2]

该版本于 2023 年 6 月 21 日发布。

改进Copy Anchor Link

该版本改进了网络传输策略，提升了音视频交互的流畅度。

问题修复Copy Anchor Link

该版本修复了以下问题：

• SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。
• 发送端调用 setAINSMode 开启 AI 降噪功能后，接收端用户偶现回声。
• 使用媒体播放器播放媒体文件时出现短暂杂音。
• 屏幕共享场景下，部分机型必现接收端看到共享的画面卡顿。

该版本于 2023 年 5 月 24 日发布。

升级必看Copy Anchor Link

该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。

视频数据获取Copy Anchor Link

• onCaptureVideoFrame 和 onPreEncodeVideoFrame 回调中新增了 sourceType 参数，用于表示具体的视频源类型。
• 以下回调已删除，请通过 onPreEncodeVideoFrame 和 onCaptureVideoFrame 中的 sourceType 参数得知视频源类型。
  • onScreenCaptureVideoFrame
  • onPreEncodeScreenVideoFrame

媒体发布选项Copy Anchor Link

• ChannelMediaOptions 中的 publishCustomAudioTrackEnableAec 已删除，请改用 publishCustomAudioTrack。
• ChannelMediaOptions 中的成员 publishTrancodedVideoTrack 变更为 publishTranscodedVideoTrack。
• ChannelMediaOptions 中的成员 publishCustomAudioSourceId 变更为 publishCustomAudioTrackId。

音视频录制Copy Anchor Link

• 删除 getMediaRecorder 方法，可通过该版本新增的 createMediaRecorder 方法来创建录制对象。
• 删除 startRecording 、stopRecording、setMediaRecorderObserver 中的 connection 参数。
• 删除 AgoraMediaRecorder 类中的 release 方法，你可直接调用该版本新增的 destroyMediaRecorder 方法来销毁录制对象以释放资源。

其他兼容性变更Copy Anchor Link

• onApiCallExecuted 已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。
• enableDualStreamMode[1/2] 和 enableDualStreamMode[2/2] 已废弃，请改用 setDualStreamMode[1/2] 和 setDualStreamMode[2/2]。
• startChannelMediaRelay、updateChannelMediaRelay、startChannelMediaRelayEx 和 updateChannelMediaRelayEx 已废弃，请改用 startOrUpdateChannelMediaRelay 和 startOrUpdateChannelMediaRelayEx。

新增特性Copy Anchor Link

AI 降噪Copy Anchor Link

该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 setAINSMode 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。

增强虚拟背景Copy Anchor Link

为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 enableVirtualBackground 方法时，将自定义背景设置为更多类型：

• 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。
• 将背景替换为多种格式的本地视频。

视频场景化设置Copy Anchor Link

该版本新增 setVideoScenario 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化：

• 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。
• 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。

本地录制远端音视频 (Beta)Copy Anchor Link

该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 onRecorderStateChanged 和 onRecorderInfoUpdated 中新增 channelId 和 uid 参数，用于表示录制的音视频流的具体信息，并新增 createMediaRecorder 方法，用于创建本地或远端的录制对象。

你可以通过如下方法体验本地录制远端音视频功能：

• createMediaRecorder：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。
• setMediaRecorderObserver：设置录制回调对象。
• startRecording：开始录制。
• stopRecording：停止录制。
• destroyMediaRecorder：销毁录制对象。

本地合图Copy Anchor Link

该版本新增本地合图功能，用户可以调用 startLocalVideoTranscoder 方法，在本地将多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）混合和渲染，以实现自定义布局和效果。通过这项功能，你可以轻松创建个性化的视频显示效果，满足各种场景需求，如远程会议、直播、在线教育场景，同时支持人像画中画等功能。

另外，SDK 还提供了 updateLocalTranscoderConfiguration 方法和 onLocalVideoTranscoderError 回调。当你在开启本地合图后，可以调用 updateLocalTranscoderConfiguration 更新合图的配置；当你在开启本地合图或者更新本地合图配置失败时，可通过 onLocalVideoTranscoderError 回调得知合图失败的原因。

多端同步Copy Anchor Link

在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 getNtpWallTimeInMs 方法获取当前的 NTP (网络时间协议) 时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。

改进Copy Anchor Link

优化变声Copy Anchor Link

该版本新增了 setLocalVoiceFormant 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 setLocalVoicePitch 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。

增强屏幕共享Copy Anchor Link

该版本新增 queryScreenCaptureCapability 方法，用于查询当前设备的屏幕捕获能力。如果你想在屏幕共享时启用高帧率（如 60 fps）、但不确定设备是否支持时，可以调用该方法、然后从返回值中得知设备支持的最高帧率是否满足需求。

该版本新增 setScreenCaptureScenario 方法，用于设置屏幕共享的场景类型，SDK 会根据场景类型自动调整共享画面的的流畅度和清晰度。

提升音频文件类型兼容性Copy Anchor Link

该版本提升了音频文件类型兼容性，你可以通过 startAudioMixing[2/2]、playEffect[3/3]、open[2/2]、openWithMediaSource 方法来打开以 content:// 开头的 URI 文件。

提升音视频同步能力Copy Anchor Link

针对自定义视频和音频采集场景，该版本新增 getCurrentMonotonicTimeInMs 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。

优化多路摄像头采集Copy Anchor Link

该版本新增 startCameraCapture 方法，通过多次调用并指定 sourceType 参数可以同时开启多路摄像头采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头的场景。

优化版权音乐Copy Anchor Link

针对在线 K 歌房场景，改版本新增 getCaches 和 removeCache 方法，用于获取、删除音乐资源缓存，并新增状态码和错误码，可方便用户排查问题。

优化跨频道连麦Copy Anchor Link

该版本新增 startOrUpdateChannelMediaRelay 和 startOrUpdateChannelMediaRelayEx 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。

多路音频自采集Copy Anchor Link

为更好地满足音频自采集的场景需求，该版本新增了 createCustomAudioTrack 和 destroyCustomAudioTrack 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性：

• 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。
• 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 加入或退出频道时，安卓设备端偶现的崩溃。
• 当快速切换身份角色时，观众端听不到声音。
• 偶现耳返开启无效。
• 偶现回声。
• 由于 onRemoteAudioStateChanged 回调异常造成客户端状态异常。

API 变更Copy Anchor Link

新增Copy Anchor Link

• startCameraCapture
• stopCameraCapture
• startOrUpdateChannelMediaRelay
• startOrUpdateChannelMediaRelayEx
• getNtpWallTimeInMs
• setVideoScenario
• getCurrentMonotonicTimeInMs
• startLocalVideoTranscoder
• updateLocalTranscoderConfiguration
• onLocalVideoTranscoderError
• queryScreenCaptureCapability
• setScreenCaptureScenario
• setAINSMode
• createCustomAudioTrack
• destroyCustomAudioTrack
• createMediaRecorder
• destroyMediaRecorder
• IAgoraMusicContentCenter 中新增如下方法：
  • getCaches
  • removeCache
• IAgoraMusicPlayer 中新增如下方法：
  • open[2/2]
  • getPlaySrc
  • stop
• AudioTrackConfig
• AudioTrackType
• MusicCacheInfo
• MusicCacheStatusType
• RecorderStreamInfo
• VideoScenario
• RtcEngineConfig 中新增 mDomainLimit 和 mAutoRegisterAgoraExtensions 属性
• onRecorderStateChanged、onRecorderInfoUpdated 中新增 channelId 和 uid 参数
• onCaptureVideoFrame 和 onPreEncodeVideoFrame 中增加 sourceType 参数
• MusicContentCenterConfiguration 中新增 maxCacheSize 属性
• MUSIC_CONTENT_CENTER_STATUS_ERR_GATEWAY(2)
• MUSIC_CONTENT_CENTER_STATUS_ERR_PERMISSION_AND_RESOURCE(3)
• MUSIC_CONTENT_CENTER_STATUS_ERR_INTERNAL_DATA_PARSE(4)
• MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_LOADING(5)
• MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_DECRYPTION(6)
• PRELOAD_STATUS_REMOVED(3)
• BACKGROUND_NONE(0)
• BACKGROUND_VIDEO(4)

修改Copy Anchor Link

• onMusicChartsResult 中的 status 修改为 errorCode
• onMusicCollectionResult 中的 status 修改为 errorCode
• onLyricResult 中的 status 修改为 errorCode
• onPreLoadEvent 中的 msg 修改为 errorCode

废弃Copy Anchor Link

• enableDualStreamMode[1/2]
• enableDualStreamMode[2/2]
• startChannelMediaRelay
• startChannelMediaRelayEx
• updateChannelMediaRelay
• updateChannelMediaRelayEx
• onChannelMediaRelayEvent

删除Copy Anchor Link

• onApiCallExecuted
• ChannelMediaOptions 中的 publishCustomAudioTrackEnableAec
• getMediaRecorder
• AgoraMediaRecorder 类中的 release
• startRecording、stopRecording、setMediaRecorderObserver 中的 connection
• onScreenCaptureVideoFrame
• onPreEncodeScreenVideoFrame

该版本于 2023 年 2 月 8 日发布。

升级必看Copy Anchor Link

自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。

如果你想自定义视频编码分辨率，可调用 setVideoEncoderConfiguration 方法，重新设置视频编码参数配置中的视频编码分辨率。

新增特性Copy Anchor Link

快速出图出声Copy Anchor Link

该版本新增 enableInstantMediaRendering 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。

视频渲染数据打点Copy Anchor Link

该版本新增 startMediaRenderingTracing 和 startMediaRenderingTracingEx 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 onVideoRenderingTracingResult 回调报告相关事件的信息。

声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 onVideoRenderingTracingResult 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。

改进Copy Anchor Link

视频观测器Copy Anchor Link

自该版本起，SDK 对 onRenderVideoFrame 回调进行了优化，在不同的视频处理模式下返回值的意义不同：

• 当视频处理模式为 PROCESS_MODE_READ_ONLY 时，返回值无实际含义。
• 当视频处理模式为 PROCESS_MODE_READ_WRITE 时，返回 true 代表设置 SDK 接收视频帧；返回 false 代表设置 SDK 丢弃视频帧。

超分辨率Copy Anchor Link

该版本提升了超分辨率的性能表现。为提升超分辨率易用性，该版本删除了 enableRemoteSuperResolution，超分辨率纳入画质增强线上策略的一部分，无需单独设置即可体验。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。
• 在红米 9A 上进行 CDN 推流，将推流的视频分辨率设置为 3840 × 2160 必现崩溃。
• 合唱模式下，OPPO R11 设备外放加入频道后，对端听到明显杂声和回音。
• 本地音乐文件结束播放时，未能触发 onAudioMixingFinished 回调。
• 接收端通过视频观测器接收的第一帧视频帧偶现丢包。
• 在多频道场景下开启屏幕共享，偶现远端看到的本地屏幕共享画面为黑屏。
• 开启虚拟背景时切换至后置摄像头会导致背景倒置。
• 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。
• 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。

API 变更Copy Anchor Link

新增Copy Anchor Link

• enableInstantMediaRendering
• startMediaRenderingTracing
• startMediaRenderingTracingEx
• onVideoRenderingTracingResult
• MEDIA_RENDER_TRACE_EVENT
• VideoRenderingTracingInfo

删除Copy Anchor Link

• enableRemoteSuperResolution
• RemoteVideoStats 中删除 superResolutionType

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

新增特性Copy Anchor Link

版权音乐Copy Anchor Link

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

耳机均衡器Copy Anchor Link

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

已编码视频帧观测器Copy Anchor Link

该版本新增 setRemoteVideoSubscriptionOptions 和 setRemoteVideoSubscriptionOptionsEx 方法，当你调用 registerVideoEncodedFrameObserver 方法为编码后的视频注册视频帧观测器时，SDK 默认订阅编码后的视频帧。如果你想要修改订阅选项，可以调用该新增的方法进行设置。

有关更多注册视频观测器和订阅选项的介绍，详见 API 参考。

MPUDP (MultiPath UDP)Copy Anchor Link

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

摄像头采集选项Copy Anchor Link

该版本在 CameraCapturerConfiguration 中增加了 followEncodeDimensionRatio 成员，你可以在使用摄像头采集视频时，通过该成员设置是否跟随 setVideoEncoderConfiguration 中已经设置的视频宽高比。

多频道管理Copy Anchor Link

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

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

视频编码偏好Copy Anchor Link

一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 VideoEncoderConfiguration 中新增 advanceOptions 成员，用于视频编码属性的进阶设置：

• compressionPreference：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。
• encodingPreference：视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。

日志上传Copy Anchor Link

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

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

用户角色切换Copy Anchor Link

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

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

改进Copy Anchor Link

蓝牙权限Copy Anchor Link

为简化集成步骤，自该版本起，SDK 支持你在不添加 BLUETOOTH_CONNECT 权限的情况下，也能让 Android 用户正常使用蓝牙。

CDN 推流Copy Anchor Link

为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 onDirectCdnStreamingStats 回调报告推送的视频流的实际分辨率。

跨频道媒体流转发Copy Anchor Link

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

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

AIAECCopy Anchor Link

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

虚拟背景Copy Anchor Link

该版本对虚拟背景算法做了如下优化：

• 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。
• 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。
• 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。
• 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。

其他改进Copy Anchor Link

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

问题修复Copy Anchor Link

该版本修复了以下问题：

• 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。
• onVideoPublishStateChanged 回调报告的视频源类型不准确。
• 调用 getExtensionProperty 失败，返回空字符串。
• 当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。

API 变更Copy Anchor Link

新增Copy Anchor Link

• setHeadphoneEQParameters
• setRemoteVideoSubscriptionOptions
• setRemoteVideoSubscriptionOptionsEx
• VideoSubscriptionOptions
• muteLocalAudioStreamEx
• muteLocalVideoStreamEx
• muteAllRemoteAudioStreamsEx
• muteAllRemoteVideoStreamsEx
• startRtmpStreamWithoutTranscodingEx
• startRtmpStreamWithTranscodingEx
• updateRtmpTranscodingEx
• stopRtmpStreamEx
• startChannelMediaRelayEx
• updateChannelMediaRelayEx
• pauseAllChannelMediaRelayEx
• resumeAllChannelMediaRelayEx
• stopChannelMediaRelayEx
• leaveChannelEx[2/2]
• enableAudioVolumeIndicationEx
• CameraCapturerConfiguration 中增加 followEncodeDimensionRatio
• LocalVideoStats 中增加 hwEncoderAccelerating
• VideoEncoderConfiguration 中增加 advanceOptions 成员
• LocalAccessPointConfiguration 中增加 advancedConfig 成员
• onClientRoleChanged 中增加 newRoleOptions
• adjustUserPlaybackSignalVolumeEx
• IAgoraMusicContentCenter 接口类及其中方法
• IAgoraMusicPlayer 接口类及其中方法
• IMusicContentCenterEventHandler 接口类及其中回调
• Music 类
• MusicChartInfo 类
• MusicContentCenterConfiguration 类
• ClimaxSegment 类

废弃Copy Anchor Link

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

删除Copy Anchor Link

• 删除了 LiveTranscoding 类中的废弃成员参数 backgroundImage 和 watermark
• onChannelMediaRelayEvent 中删除 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED(8)

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

升级必看Copy Anchor Link

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

该版本删除了 enableDualStreamMode[3/3] 和 enableDualStreamModeEx 中的 sourceType 参数以及 enableDualStreamMode[2/3] 方法，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。

新增特性Copy Anchor Link

耳返Copy Anchor Link

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

音频采集设备测试Copy Anchor Link

该版本支持加入频道前测试本地音频采集设备。你可以调用 startRecordingDeviceTest 开启音频采集设备测试，测试完成后，调用 stopPlaybackDeviceTest 方法停止音频采集设备测试。

本地网络连接类型Copy Anchor Link

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

音强选流Copy Anchor Link

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

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

双流模式Copy Anchor Link

该版本对双流模式做了优化，在加入频道前后均可调用 enableDualStreamMode 和 enableDualStreamModeEx。

扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式（即：默认不主动发送小流），可通过以下步骤开启发送小流：

1. 接收端主播调用 setRemoteVideoStreamType 或 setRemoteDefaultVideoStreamType 发起接收小流申请。
2. 发送端收到申请后自动切换为发送小流模式。

如果你想修改上述发送端的默认行为，可以调用 setDualStreamMode[1/2] 或 setDualStreamMode[2/2] 方法，将 mode 参数设置为 DISABLE_SIMULCAST_STREAM（始终不发送小流）或 ENABLE_SIMULCAST_STREAM（始终发送小流）。

空间音频Copy Anchor Link

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

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

改进Copy Anchor Link

视频信息发生改变回调Copy Anchor Link

该版本优化了 onVideoSizeChanged 的触发逻辑，当单独调用 startPreview 时，也可触发该回调并上报本地视频大小发生改变。

问题修复Copy Anchor Link

该版本修复了以下问题：

1. 在频道内调用 setVideoEncoderConfigurationEx 将视频的分辨率调高时，偶现失效。
2. 在多人会议场景下，本地用户接听并挂断电话后，偶现本地用户和远端用户无法听见对方的声音。
3. 调用 setCloudProxy 设置云代理后，调用 joinChannelEx 加入多频道失败。
4. 使用媒体播放器播放视频，先调用 play 再调用 pause 暂停播放后，调用 seek 指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用 resume 恢复播放后，偶现视频画面出现快进。

API 变更Copy Anchor Link

新增Copy Anchor Link

• getEarMonitoringAudioParams
• startRecordingDeviceTest
• stopRecordingDeviceTest
• getNetworkType
• ChannelMediaOptions 中新增 isAudioFilterable
• setDualStreamMode[1/2]
• setDualStreamMode[2/2]
• setDualStreamModeEx
• SIMULCAST_STREAM_MODE
• setZones
• setPlayerAttenuation
• setRemoteAudioAttenuation
• muteRemoteAudioStream
• SpatialAudioParams
• setHeadphoneEQPreset

修改Copy Anchor Link

• enableDualStreamMode[3/3]

• enableDualStreamModeEx

废弃Copy Anchor Link

• startEchoTest[2/3]

删除Copy Anchor Link

• enableDualStreamMode[2/3]

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

升级必看Copy Anchor Link

兼容性变更Copy Anchor Link

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

• 多频道
• 媒体流发布控制
• 自定义视频采集与渲染（Media IO 方式）
• 警告码

回调异常处理Copy Anchor Link

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

新增特性Copy Anchor Link

多路媒体流Copy Anchor Link

该版本通过设置 RtcEngineEx 和 ChannelMediaOptions 实现一个 RtcEngine 实例同时采集多组音视频流并发布到远端：

调用 joinChannel 加入首个频道后，多次调用 joinChannelEx 加入多个频道，通过不同的用户 ID (localUid) 和 ChannelMediaOptions 设置发布指定的流到不同的频道。

同时，该版本支持通过 createCustomVideoTrack 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流：

1. 创建自采集视频轨道：调用 createCustomVideoTrack 方法创建一个自定义视频轨道，并获得视频轨道 ID。

2. 设置频道中待发布的自采集视频轨道：在每个频道的 ChannelMediaOptions 中，将 customVideoTrackId 参数设置为你想要发布的视频轨道 ID，并将 publishCustomVideoTrack 设置为 true。

3. 推送外部视频源：调用 pushExternalVideoFrameEx，并将 videoTrackId 指定为步骤 2 中指定的视频轨道 ID，即可实现在多个频道中发布对应的自定义视频源。

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

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

全高清和超高清分辨率Copy Anchor Link

为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持全高清 (FHD) 和超高清 (UHD) 视频分辨率。你可以在调用 setVideoEncoderConfiguration 方法时，将 dimensions 参数设置为 1920 × 1080 或更高的分辨率。如果你的设备不支持高分辨率，SDK 支持自动回退到适合的分辨率。

内置媒体播放器Copy Anchor Link

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

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

新版 AI 降噪Copy Anchor Link

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

超高音质Copy Anchor Link

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

空间音频Copy Anchor Link

该版本支持对远端用户设置空间音频：

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

该版本还支持对媒体播放器设置空间音频：

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

实时合唱Copy Anchor Link

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

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

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

云市场插件Copy Anchor Link

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

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

增强的频道管理Copy Anchor Link

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

• 设置或切换多种音视频源的发布
• 设置或切换频道场景、用户角色
• 设置或切换订阅视频的大小流类型
• 控制音频发布时延

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

屏幕共享Copy Anchor Link

该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享：

• 在加入频道前调用 startScreenCapture，然后调用 joinChannel[2/2] 加入频道并设置 publishScreenCaptureVideo 为 true，即可开始屏幕共享。
• 在加入频道后调用 startScreenCapture，然后调用 updateChannelMediaOptions 设置 publishScreenCaptureVideo 为 true，即可开始屏幕共享。

设置音视频流订阅黑/白名单Copy Anchor Link

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

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

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

设置音频场景Copy Anchor Link

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

设置本地代理Copy Anchor Link

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

垫片推流Copy Anchor Link

该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 enableVideoImageSource 来开启该功能，并通过 options 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。

改进Copy Anchor Link

快速切换频道Copy Anchor Link

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

推送外部视频帧Copy Anchor Link

该版本新增支持推送 I422 格式的外部视频帧，你可以通过 pushExternalVideoFrame[1/2] 方法将 I422 格式的外部视频帧推送至 SDK。

本地人声音调Copy Anchor Link

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

设备权限管理Copy Anchor Link

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

本地视频预览Copy Anchor Link

该版本优化了 startPreview 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 startPreview 方法来开启视频预览，无调用时序要求。

订阅视频流Copy Anchor Link

你可以通过 setRemoteDefaultVideoStreamType 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。

该版本于 2026 年 9 月 22 日发布。

新增特性Copy Anchor Link

声网高级美颜 2.1Copy Anchor Link

该版本支持声网高级美颜 2.1 API，并新增美颜人脸检测能力。使用声网高级美颜功能的客户可以检测人脸置信度。使用 RTC SDK v4.7.0 及以上版本集成声网高级美颜时，请参考实现声网高级美颜；如果仍使用 RTC SDK v4.6.x，请继续参考声网高级美颜 2.0 文档。

改进Copy Anchor Link

音视频链路性能优化Copy Anchor Link

该版本针对音视频链路与线程调度机制做了专项优化，显著降低各音视频场景 CPU 消耗，同步提升长时间运行稳定性。

音频 SDK FFmpeg 插件集成优化Copy Anchor Link

该版本调整了音频 SDK 中 FFmpeg player 插件的加载方式。Agoraffmpeg.xcframework 已调整为可选插件 AgoraffmpegExtension.xcframework。SDK 包中默认包含该插件，你可以根据业务需要选择是否集成。未加载 FFmpeg player 插件时，MediaPlayer 使用系统原生播放能力，实际支持的音频文件格式取决于系统支持的容器格式和音频编解码器；集成并加载 FFmpeg player 插件后，MediaPlayer 可支持更多音频格式和播放能力。

视频首帧体验优化Copy Anchor Link

该版本优化了视频帧传输调度机制，提升了频道内首个用户订阅流的出图速度。

1v1 连麦延时体验优化Copy Anchor Link

该版本优化了视频1v1等实时互动场景下的音视频策略，在保障画质的前提下改善端到端延迟，并提升突发抖动等弱网场景下的播放流畅性。

音频场景码率优化Copy Anchor Link

该版本优化了音频场景下的码率开销，保障音质的前提下提升了音频流传输效率。

视频方向处理优化Copy Anchor Link

该版本改进了横竖屏切换过程中的视频方向处理，降低设备旋转后视频 UI 旋转延迟或异常的概率。

后台摄像头采集与重新开播体验优化Copy Anchor Link

该版本改进了 App 进入后台后的摄像头采集状态处理，解决主播重新开播时本地或远端画面偶现黑屏的问题。

Native 与 Web 互通弱网体验优化Copy Anchor Link

该版本优化了视频 1v1 弱网场景下 Native 与 Web 互通的音视频体验。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 修复了 iOS 26 上触发系统键盘语音转文字后，播放端低概率无声的问题。
• 修复了使用蓝牙音频设备上麦后，音频路由异常切换或远端音频无声的问题。
• 修复了聊天室上下麦场景中，先关闭本地音频、切换观众/主播角色后再开启本地音频时导致的低概率远端无声的问题。
• 修复了 AI QoS 配置下，通话刚开始时偶现首句音频丢字或异常的问题。
• 修复了音视频互动、屏幕共享、视频帧数据访问和音视频统计等场景下偶现 App 崩溃的问题，提升了 SDK 稳定性。

该版本于 2026 年 8 月 31 日发布。

升级必看Copy Anchor Link

iOS 27 横屏采集画面方向适配Copy Anchor Link

在使用 Xcode 27 编译 App 并运行于 iOS 27.0 及以上系统时，由于声网 RTC SDK 旧版本依赖的界面方向相关系统 API，如 UIApplicationWillChangeStatusBarOrientationNotification，在 iOS 27 中不再支持，导致 App 在横屏界面下启用摄像头采集时出现采集画面方向异常。本版本已使用新API完成适配。

更多信息请参考 Apple 的 iOS & iPadOS 27 Release Notes。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 修复了断网后 onNetworkQuality 回调报告的网络质量可能不准确的问题。
• 修复了接收端设置音频场景为AUDIO_SCENARIO_AI_CLIENT，发送端频繁停止和恢复发送音频流，当接收端网络不佳时偶现无声问题。
• 修复了使用有线耳机进行音视频互动时，在特定音频路由配置场景下偶现音质变差的问题。
• 修复了自渲染视频帧场景下，本地预览画面偶现卡住的问题。
• 修复了在 Android 模拟器上部分场景下偶现回声的问题。
• 修复了启用 Google 安全加固后，音视频互通过程中偶现 App 崩溃或无响应（ANR）的问题。
• 修复了 App 集成调用 setExternalVideoSource 设置推送的外部视频源类型为已编码的视频帧（ENCODED_VIDEO_FRAME），推送的已编码视频帧包含的 SEI 信息长度如果与编码协议规定不匹配，偶现崩溃问题。
• 修复了开启媒体播放器缓存后，在断网场景下播放已缓存资源时，可能延迟约 10 秒并回调错误的问题。
• 修复了 App 以通信模式（CHANNEL_PROFILE_COMMUNICATION）加入频道后，调用 updateChannelMediaOptions 更新频道媒体选项后，NCS 和 RESTful API 返回的频道信息被错误识别为互动直播模式的问题。

该版本于 2026 年 1 月 16 日发布。

升级必看Copy Anchor Link

支持自定义编码帧率Copy Anchor Link

为支持更灵活的视频编码帧率设置，该版本将 AgoraVideoEncoderConfiguration 中 frameRate 参数的数据类型由枚举类型改成了 Int。在实际集成时，你可以参考原有 AgoraVideoFrameRate 枚举中的取值进行设置。

Lite 和 Voice 包中去除音频频谱功能Copy Anchor Link

为进一步优化 SDK 包体积，该版本将音频频谱（Audio Spectrum）功能从 Lite 和 Voice SDK 包中移除。如果你需要使用音频频谱功能，请集成完整 (Full) 包。

关闭自动切换微距Copy Anchor Link

摄像头自适应切换微距可能会导致视频画面跳变。为避免该问题，该版本关闭了摄像头微距的自动切换功能。你仍可以根据业务或场景需要，通过私有参数设置手动切换摄像头微距。如有需要，可以联系技术支持。

其他Copy Anchor Link

• 为保证整体解码兼容性，相关解码器插件已内置在 SDK 中。
• 从该版本起，SDK 默认不再支持 armv7 架构。如需支持该架构，可以联系技术支持。

新增特性Copy Anchor Link

支持多任务采集Copy Anchor Link

从 iOS 16 起，系统支持多任务处理，允许用户在多个 App 之间并行使用。常见的多任务模式包括分屏显示 (Split views)、滑动叠放 (Slide over)、画中画 (Picture in picture) 和台前调度 (Stage manager) 等。

从 v4.6.2 起，SDK 适配 iOS 的相机多任务采集能力，支持在多任务场景下持续进行音视频采集。在实时音视频互动场景中，启用该能力后，可支持例如视频通话过程中同时查阅资料、互动教学中分屏展示课件、直播过程中同时管理商品后台等业务场景。

在实际集成过程中，你需要先为 App 开启相机多任务采集能力，才能在多任务场景下正常使用相关功能。具体配置步骤请参考如何开启 iOS 多任务相机采集。

经声网实验室测试，该功能支持的机型和系统版本如下：

Media Player 支持获取音频缓冲延迟Copy Anchor Link

为解决 K 歌场景中可能会出现的主唱与伴唱伴奏不同步的问题，该版本在 Media Player 模块中新增 getAudioBufferDelay 方法，用于获取播放媒体文件时毫秒级的音频缓冲延迟。

改进Copy Anchor Link

playEffect 支持无缝切换Copy Anchor Link

该版本新增支持音效文件的无缝切换。对于同一个音效文件，如果先调用 preloadEffect 再调用 playEffect，在播放完成或通过 stopEffect 停止播放后，SDK 不会关闭该音效文件。当再次调用 playEffect 时，SDK 会直接复用已加载的文件进行播放，从而实现循环播放和无缝切换。该能力同样适用于多频道场景。

networkQuality 准确性提升Copy Anchor Link

该版本提升了 networkQuality 回调中网络质量评估的准确性，使回调数据更贴近用户的主观体验。

onPlaybackAudioFrame 支持 24k 采样率的音频帧Copy Anchor Link

该版本在 onPlaybackAudioFrame 中新增支持采样率为 24000 Hz 的音频数据。在调用 setPlaybackAudioFrameParameters 设置播放音频数据格式时，可以将 sampleRate 设为 24000。

onEncodedVideoFrameReceived 回调支持获取频道 IDCopy Anchor Link

该版本在 onEncodedVideoFrameReceived 回调中新增 channelId 参数，方便你在获取编码后视频数据时识别其所属频道。

其他Copy Anchor Link

• 新增错误码 AgoraErrorCodePcmSendFormat (200) 和 AgoraErrorCodePcmSendBufferOverflow (201)，用于报告 PCM 数据发送相关错误。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 美颜功能在部分场景下不生效。
• 当在子线程调用 leaveChannel 和 destroy 时，并同时发生 UI 方向切换时，可能导致 App 崩溃。
• 在 iOS 26 部分设备上，用户以主播身份在音频 Scenario 为 AgoraAudioScenarioChatRoom 的情况下加入频道，调用 enableLocalAudio 关闭本地音频采集后，无法调整通话音量。
• 在硬件异常的情况下切换视频分辨率时，偶现视频编码无输出帧，导致画面卡住的问题。

该版本于 2025 年 8 月 18 日发布。

升级必看Copy Anchor Link

该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的废弃及删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。

各版本废弃及删除的 API 信息。详见 API 下架说明。

直推 CDN 相关接口废弃Copy Anchor Link

该版本废弃直推 CDN 功能的相关接口，并会在后续版本中删除，请改用服务端旁路推流。

• setDirectCdnStreamingAudioConfiguration:
• setDirectCdnStreamingVideoConfiguration:
• startDirectCdnStreaming:publishUrl:mediaOptions:
• stopDirectCdnStreaming
• AgoraDirectCdnStreamingMediaOptions
• AgoraDirectCdnStreamingStats
• AgoraDirectCdnStreamingState
• AgoraDirectCdnStreamingReason

虚拟节拍器接口废弃Copy Anchor Link

该版本废弃虚拟节拍器功能的相关接口，并会在后续版本中删除。

• startRhythmPlayer:sound2:config:
• configRhythmPlayer:
• rtcEngine:didRhythmPlayerStateChanged:reason:

水印接口废弃Copy Anchor Link

该版本废弃水印功能的相关接口，推荐使用该版本新增的水印接口。

• addVideoWatermark:options:
• addVideoWatermarkEx:options:connection:

冗余接口删除Copy Anchor Link

该版本删除了下列冗余接口及参数：

• setLocalPublishFallbackOption
• didLocalPublishFallbackToAudioOnly
• downlinkNetworkInfoUpdate
• wlAccStats
• wlAccMessage
• enableWirelessAccelerate
• AgoraWlAccReason
• AgoraWlAccAction
• AgoraWlAccStats
• AgoraRtcRemoteVideoStats 中删除 receivedFrameRate

美妆功能实现变更Copy Anchor Link

受美颜重构的影响，自 v4.6.0 起，不再支持调用 setExtensionPropertyWithVendor:extension:key:value: 启用美妆功能，改用 STYLE_MAKEUP 节点实现。

默认日志路径修正Copy Anchor Link

该版本将默认日志路径由 AppSandbox/Library/documents/agorasdk.log 修正为 AppSandbox/Library/caches/agorasdk.log。如果你是由 v4.3.1 及之后的版本升级到 v4.6.0，请改用修正后的路径查找日志。

新增域名白名单Copy Anchor Link

如果你由之前的版本升级到 v4.6.0 且使用了域名白名单功能（AgoraRtcEngineConfig 下的 domainLimit 为 YES），请在白名单中添加以下域名，以确保互通顺畅：

• *.rtnsvc.com
• *.realtimemesh.com

新增特性Copy Anchor Link

多路分辨率视频流Copy Anchor Link

该版本新增多路分辨率视频流（Adaptive Bitrate Video Streaming，简称 ABR）功能，支持对同一视频源设置同时发送多路不同分辨率的视频流，并支持多频道场景。接收端通过自动/手动订阅目标分辨率的视频流。

启用 ABR 后，你可以配置不同分辨率的视频流（最多四层分辨率，一个最高分辨率的主流和三层其他较低分辨率的视频流），并设置视频流的分辨率、码率、是否启用分层推流回退等选项来灵活控制流的发布。启用分层推流回退后，SDK 会在弱网环境下自动回退到低分辨率的视频流，确保流畅的观看体验。订阅端可根据实际需求选择想要接收的视频流。适用于会议场景、大班课、互动直播等多终端、多网络环境，可显著提升弱网下的观看体验。

具体实现方法以及和视频双流的对比可以参考进阶功能发布多路视频流 (ABR)。

多路径网络传输Copy Anchor Link

该版本新增多路径传输功能，适用于终端支持多网卡传输(比如 5G， Wi-Fi，LAN)的设备，可以有效降低甚至消除弱网带来的体验回退，适用于弱网环境、对传输稳定性要求高的实时音视频通信场景，如车载、IoT、火车、高速公路等复杂网络环境。通过在 AgoraRtcChannelMediaOptions 中设置 enableMultipath 为 YES，可开启多路径传输能力。支持两种传输模式（AgoraMultipathMode）：

• 动态模式：（默认）根据网络状况动态选择最佳路径进行传输，适用于流量敏感、对体验要求比较高的场景，如会议、教育等。动态模式下，你可以通过 preferMultipathType 指定首选的网络传输路径（如优先 Wi-Fi 或移动网络）。
• 全冗余模式：数据会在所有可用网络路径上同时传输，适用于流量不敏感，对体验有极致要求的场景，如户外采播、平行操控等。该模式会产生额外费用，如需使用请联系技术支持。

上下行还可分别通过 AgoraRtcChannelMediaOptions 中的 uplinkMultipathMode、downlinkMultipathMode 配置。启用后，SDK 会通过回调 rtcEngine:multiPathStats: 实时上报各路径的传输统计信息，包括每一个传输路径的流量消耗，便于开发者监控和优化网络表现。

视频质量评分Copy Anchor Link

该版本在 AgoraRtcRemoteVideoStats 中新增 mosValue 成员，报告声网实时视频 MOS（平均主观意见分）评估系统对接收到的远端视频流的质量评分。评分共有 5 个档次，5 分表示视频画质优秀，画面清晰无噪点，1 分表示视频画质极差，画面严重模糊。你可以通过该参数实时观测远端视频流的主观画质表现，便于动态调整视频参数、优化用户体验，或用于质量监控和告警等场景。如需启用该功能，请联系技术支持。

支持添加多个水印Copy Anchor Link

该版本废弃了 addVideoWatermark:options: 和 addVideoWatermarkEx:options:connection: 方法，新增 addVideoWatermarkWithConfig 和 addVideoWatermarkEx3 方法，支持通过水印 ID 来给视频添加多个水印，并可对水印进行排序。如果你需要移除指定水印，可调用 removeVideoWatermark 方法。

异步销毁引擎Copy Anchor Link

该版本新增 destroy: 方法，用于销毁 RTC 引擎，且支持通过参数配置以同步或异步方式销毁引擎。异步销毁引擎时，SDK 会触发 engineReleasedBlock 回调块。

美颜功能拓展Copy Anchor Link

新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。

Token 更新结果回调Copy Anchor Link

该版本新增 rtcEngine:renewTokenResult:code: 回调及 RENEW_TOKEN_ERROR_CODE 错误码。当调用 renewToken: 方法更新 Token 后，SDK 会通过 rtcEngine:renewTokenResult:code: 回调通知 Token 更新的结果，并通过 RENEW_TOKEN_ERROR_CODE 返回详细的错误码，开发者可在回调中根据错误码及时处理 Token 更新失败的场景。

其他Copy Anchor Link

• 新增 setPlaybackAudioFrameBeforeMixingParametersWithSampleRate 方法用于设置 onPlaybackAudioFrameBeforeMixing:channelId:uid: 回调中返回的音频帧格式，包括采样率、声道数以及每次回调的数据采样点数。调用此方法后，SDK 会按照设定的参数返回混音前的原始音频数据，便于开发者进行自定义处理或分析。
• 新增 preloadEffectEx 方法，用于将指定音效文件预加载到指定频道，支持本地或在线音效文件，便于后续快速播放，适合多频道场景。
• 新增 playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:startPos: 方法，用于在指定频道播放音效文件，支持设置循环次数、音调、空间位置、音量、是否发布到频道及播放起始位置等参数，满足丰富的音效播放需求。
• 本地截图上传功能支持通过 AgoraContentInspectModule 中新增的 position 成员设置截图的视频观测位置，从而实现对原始视频数据或效果处理前后的视频流进行截图并上传。
• 为了提升用户使用绿幕或蓝幕开启虚拟背景功能时，人像分割的准确性和稳定性，该版本在 AgoraSegmentationProperty 中新增 screenColorType 属性，支持指定背景幕布的颜色为绿色、蓝色或自动识别。

改进Copy Anchor Link

美颜重构Copy Anchor Link

该版本对美颜功能进行了彻底重构和升级，不仅拓展了美颜功能，提升了美颜效果和性能，还解决了美颜参数配置复杂、集成成本高、美颜资源依赖网络易失效等痛点。主要改进包括：

• API 大幅简化：将过去版本中的基础美颜、美型、美妆、滤镜功能整合为 AgoraVideoEffectNodeBeauty、AgoraVideoEffectNodeStyleMakeup、AgoraVideoEffectNodeFilter 三个核心节点 (node)，通过 AgoraVideoEffectObject 统一管理生命周期和参数设置，减少频繁 API 调用带来的性能负担。
• 预设模板开箱即用：提供多套预设风格模板（如“自然美颜”、“学姐妆”、“冷白滤镜”），大幅简化集成流程，无需手动调试数十项参数。
• 美颜参数动态控制：该版本新增实时获取美颜参数的能力，开发者可通过 key-value 方式动态读取或修改任意细粒度参数（如磨皮强度、口红类型）。同时支持：调用预设模板快速启用风格效果、保存主播自定义参数配置、随时重置参数至默认状态，极大提升了业务层状态同步的灵活性和开发效率。
• 美颜资源外置：该版本通过美颜资源外置化设计，将所有美颜资源（特效、滤镜、妆容）均打包为本地 bundle 文件，彻底消除因网络下载失败导致美颜失效的风险。

其他改进Copy Anchor Link

• 在与 Web 端互通时，新增对 g711 和 g722 音频编解码器的支持，进一步提升了跨平台音频播放的兼容性和清晰度。
• 优化了屏幕共享文档场景下的共享视频清晰度。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 调用 open:startPos: 打开在线音效文件后，调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 开始播放，当调用 seekToPosition: 指定播放位置后，音效文件会从头开始播放。
• 在媒体音量模式下，主播在频道中发布麦克风采集的音频流，同时调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 播放音效文件、调用 startAudioMixing:loopback:cycle:startPos: 播放音乐文件，偶现回声。
• 在 setExternalVideoSource:useTexture:sourceType: 之后调用 setMediaMetadataDelegate:withType: 注册媒体 metadata 观测器，SDK 没有触发 metadata 观测器的回调。
• 偶现的崩溃问题。
• 调用 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 加入频道，然后调用 startOrUpdateChannelMediaRelay: 开始跨频道媒体流转发，下麦、退出频道后重新加入频道开始连麦，偶现 rtcEngine:channelMediaRelayStateDidChange:error: 回调报告 state 为 AgoraChannelMediaRelayStateFailure，code 为 AgoraChannelMediaRelayErrorServerErrorResponse。

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

改进Copy Anchor Link

URL 拉流播放Copy Anchor Link

该版本进一步拓展了 URL 拉流播放的功能，支持播放 CDN URL 和本地媒体资源文件，同时可以设置从指定位置开始播放、调节播放速度、设置播放音量、在播放过程中切换播放源等，详见 观众端 URL 拉流。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 开启导唱功能播放多音轨歌曲时，调用 setAudioPitch: 方法调整歌曲音调后出现杂音。
• 主播端调用 createCustomAudioTrack:config: 创建自定义音频采集轨道并将 trackType 设为 AUDIO_TRACK_DIRECT，调用 pushExternalAudioFrameRawData:samples:sampleRate:channels:trackId:timestamp: 将自采集音频推送到频道内，然后调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 播放音效，频道内的观众听主播的音频有杂音。
• 集成了 SDK 的 App 在音视频互动过程中偶现主线程阻塞导致的 UI 卡顿。
• 调用 openWithMediaSource: 并通过 source 参数将 isLiveSource 设为 YES 并播放纯视频流，播放失败。
• 调用 enableVirtualBackground:backData:segData: 开启虚拟背景功能，手机横竖屏旋转后，虚拟背景图像变大变模糊。
• 发送端传输多声道编码音频时，接收端偶现杂音。
• App 集成媒体播放器场景下，先后两次调用 open 打开不同媒体资源，第二次打开时，媒体播放器信息变化回调 AgoraRtcMediaPlayer:infoUpdated: 返回第一次媒体资源的信息，不符合预期。
• 调用 enableAudioVolumeIndication:smooth:reportVad: 启用用户音量提示本地发流用户和远端用户音量相关信息，用户音量提示回调 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 返回的本地用户音量为 0。
• App 调用 enableVideoImageSource:options: 启用垫片推流功能，偶现发送端推流成功但是 rtcEngine:didVideoPublishStateChange:sourceType:oldState:newState:elapseSinceLastState: 返回当前的发布状态不是 PUB_STATE_PUBLISHED，不符合预期。
• 多频道场景下，App 在调用 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess: 成功前调用 setupRemoteVideoEx:connection: 初始化远端用户视图，偶现远端用户视图首帧图像显示延时大。
• App 退出时偶现崩溃。

该版本于 2025 年 3 月 5 日发布。

新增特性Copy Anchor Link

AI 对话场景Copy Anchor Link

该版本新增了专为与声网对话式 AI 引擎创建的智能体互动设计的 AgoraAudioScenarioAiClient 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。

改进Copy Anchor Link

该版本优化了特定机型上 SDK 初始化的耗时。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 同时加入两个及以上的频道，连续调用 takeSnapshotEx:uid:filePath: 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。
• 使用媒体播放器时，调用 pause 暂停播放后，调用 seekToPosition: 定位到指定播放位置、然后调用 play 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。
• 使用媒体播放器时，调用 switchSrc:syncPts: 切换媒体资源后，调用 getPlaySrc获取当前正在播放的媒体资源的路径没有变化。
• 在推送 i420 格式的视频帧到频道内时，使用 CVPixelBuffer 会导致崩溃。
• 调用 setupLocalVideo: 设置两个视图（view），然后调用 enableFaceDetection: 开启人脸检测，后传入的视图中无法检测到人脸信息。
• 屏幕共享场景下，接收端用户看到的共享图像出现绿线。
• 在极速直播场景下，观众通过 string 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。
• 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。

该版本于 2024 年 11 月 26 日发布。

升级必看Copy Anchor Link

该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。

强效视频降噪实现变更Copy Anchor Link

该版本调整了强效视频降噪的实现方式，在 AgoraVideoDenoiserLevel 中删除了 AgoraVideoDenoiserLevelStrength，改为调用 setVideoDenoiserOptions:options: 启用视频降噪后，调用 setBeautyEffectOptions:options: 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 setVideoDenoiserOptions:options:。

此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 setLowlightEnhanceOptions:options:。

视频编码偏好变更Copy Anchor Link

为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好：

• 在 AgoraCompressionPreference 枚举类中新增 AgoraCompressionAuto (-1) 枚举，并替代原有的 AgoraCompressionQuality (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 AgoraCompressionLowLatency 或 AgoraCompressionQuality，以获得最佳的用户体验。
• 在 AgoraDegradationPreference 枚举类中新增 AgoraDegradationMaintainAuto (-1) 枚举，并替代原有的 AgoraDegradationMaintainQuality (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 AgoraDegradationMaintainFramerate、AgoraDegradationBalanced 或 AgoraDegradationMaintainResolution，以获得最优的综合质量体验 (QoE)。

新增特性Copy Anchor Link

高级美颜Copy Anchor Link

该版本新增以下两种高级美颜功能：

• 美型：调用 setFaceShapeBeautyOptions:options: 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 setFaceShapeAreaOptions: 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。
• 美妆：调用 setExtensionPropertyWithVendor:extension:key:value: 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。

有关美型和美妆的实现步骤，详见实现高级美颜。

秀场直播场景Copy Anchor Link

该版本在 AgoraApplicationScenarioType 类下新增枚举 AgoraApplicationLiveShowScenario(3)（秀场直播），你可以调用 setVideoScenario: 将视频业务场景设置为秀场直播。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，例如，默认开启音视频帧加速渲染来提升首帧出图体验，无需再额外调用 enableInstantMediaRendering，此外，也增强了在弱网环境和低端设备上的画质和流畅度表现。

限制视频渲染帧率Copy Anchor Link

该版本新增 setLocalRenderTargetFps 和 setRemoteRenderTargetFps 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。

在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。

URL 拉流播放Copy Anchor Link

URL 拉流播放功能主要用于直播场景，观众端可以直接通过 openWithUrl:startTime:cb: 打开特定的 URL 来播放实时媒体流，无需显示调用加入频道、订阅等 API，极大简化了观众端观看直播流的 API 调用。

在播放的过程中，观众端可以通过 setAbrSubscriptionLayer:error: 设置订阅视频大小流，并可以在大小流之间实现平滑切换。如果对视频体验有更高要求，可以联系联系技术支持开通 ABR（Adaptive Bitrate，自适应码率）功能。启用该功能后，可以自定义不同层级的视频流分辨率，观众可以实现不同分辨率视频流的平滑切换。

当网络情况不稳定时，观众端可以调用 setAbrFallbackLayer:error: 来设置订阅的视频流的回退选项。SDK 会以你指定的最低质量层级对应的视频流分辨率为下限，在此范围内根据网络状况动态调整分辨率。实现细节详见观众端 URL 拉流。

滤镜效果Copy Anchor Link

该版本新增 setFilterEffectOptions:options:sourceType: 方法，你可以在 config 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 built_in_whiten_filter.cube 文件，用于快速实现美白滤镜效果。

本地音频合流Copy Anchor Link

该版本新增本地音频合流功能，你可以调用 startLocalAudioMixer 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 stopLocalAudioMixer 方法停止本地音频合流；在合流过程中，可以调用 updateLocalAudioMixerConfiguration 方法更新正在合流的音频流配置。

该功能的使用场景示例如下：

• 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。
• 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。
• 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。

色彩空间设置Copy Anchor Link

该版本在 AgoraOutputVideoFrame 和 AgoraVideoFrame 中新增了 colorSpace，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。

改进Copy Anchor Link

虚拟背景算法优化Copy Anchor Link

该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。

录制本地预览视频Copy Anchor Link

该版本在 AgoraRecorderStreamInfo 中新增 type 成员。当调用 createMediaRecorder: 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 AgoraMediaRecorderConfiguration 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 startRecording: 即可开始录制本地预览的视频。

指定视频观测位置截图Copy Anchor Link

该版本新增 takeSnapshotWithConfig:config: 和 takeSnapshotExWithConfig:uid:config: 方法，你可以在调用该方法时通过 config 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。

自定义音频采集改进Copy Anchor Link

该版本在 AgoraAudioTrackConfig 中新增了 enableAudioProcessing 成员参数，用于控制是否对 AUDIO_TRACK_DIRECT 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 NO，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。

其他改进Copy Anchor Link

• 通过拼接视频帧和 Alpha 数据实现 Alpha 透明特效的应用场景下，提升了接收端的渲染性能，有效减少卡顿和延迟。
• 优化了调用 queryDeviceScore 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。
• 频道内调用 enableLocalAudio: 关闭本地采集后，支持通过手机静音侧键把 App 播放的背景音效设置为静音状态。
• 调用 switchSrc:syncPts: 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 AgoraRtcMediaPlayer:didOccurEvent:elapsedTime:message: 回调报告 AgoraMediaPlayerEventSwitchError 事件，表示媒体资源切换时发生错误。
• 调用 setPlaybackSpeed: 设置音频文件的播放速度时，最低支持 0.3 倍速播放。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 当发送端视频源类型为 JPEG 格式时，偶现接收端帧率低于预期。
• 音视频互动过程中，偶现接收端听发送端没有声音。
• 音视频互动过程中，如果发送端设备的系统版本为 iOS 17，偶现接收端听不到来自发送端的声音。
• 直播场景下，观众端因切换网络导致断开连接，重新连接直播间花费的时间长于预期。
• App 启动后使用媒体播放器播放在线媒体资源，播放无声。
• 音视频互动过程中被系统其他 App 打断后恢复，偶现音频采集无声。
• 调用 startAudioMixing:loopback:cycle: 后，立即调用 pauseAudioMixing 暂停播放音乐文件不生效。

该版本于 2024 年 8 月 5 日发布。

升级必看Copy Anchor Link

该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。

1. 为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的 AgoraExtensionContext 了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。

   原有回调	现有回调
   onEvent	onEventWithContext:key:value:
   onExtensionStarted	onExtensionStartedWithContext:
   onExtensionStopped	onExtensionStoppedWithContext:
   onExtensionError	onExtensionErrorWithContext:error:message:

   表格内容超出当前宽度，可横向滚动查看更多列。

2. 在 v4.4.0 之前，当你的用户角色为观众时，调用 setAudioScenario: 将音频场景设为聊天室场景（AgoraAudioScenarioChatRoom）会显示麦克风采集状态。自 v4.4.0 起，SDK 通过 iOS 原生的 API 控制麦克风开关，因此观众角色在聊天室场景下不会再显示麦克风采集状态。

3. 该版本将 receiveMetadata 回调改名为 didMetadataReceived:，并删除了回调中的 data、timeStamp 参数，你可以通过新增的 metadata 参数来获取 Metadata 的相关信息，包括 timeStamp（发送数据的时间戳）、uid（用户 ID）、channelId（源频道名称）等。

新增特性Copy Anchor Link

Lite SDKCopy Anchor Link

自该版本起，声网推出 Lite 版 SDK，该 SDK 中仅包含音视频基础能力、对高阶音视频处理的功能进行部分裁剪，可有效减少集成 SDK 后的 App 体积。

• Lite SDK 支持手动集成或三方仓库集成，详见下载和集成 SDK。
• Lite SDK 包含的动态库信息详见减小 App 体积。
• Lite SDK 支持的 API 清单详见 Lite SDK API 列表。
• 使用 Lite SDK 播放媒体文件时的限制和注意事项详见 RTC SDK 支持播放哪些格式的音频文件？

Alpha 透明特效Copy Anchor Link

该版本新增 Alpha 透明特效功能，支持在 SDK 采集和自定义采集视频的场景下，在发送端发布视频帧的 Alpha 通道、在接收端对 Alpha 通道进行渲染处理，实现透明礼物特效、接收端自定义主播背景等：

• AgoraOutputVideoFrame 和 AgoraVideoFrame 中新增 alphaBuffer：设置 Alpha 通道数据。
• AgoraVideoFrame 中新增 fillAlphaBuffer：对于 BGRA 或 RGBA 格式的视频数据，设置是否自动提取 Alpha 通道数据并填入到 alphaBuffer 中。
• AgoraOutputVideoFrame 和 AgoraVideoFrame 中新增 alphaStitchMode：设置 alphaBuffer 和视频帧拼接的相对位置。

另外，AgoraAdvancedVideoOptions 中新增成员 encodeAlpha，用于设置是否将 Alpha 信息编码并发送到远端。SDK 默认不对 Alpha 信息进行编码发送；如果需要对 Alpha 信息编码发送至远端（例如开启了虚拟背景功能），请显式调用 setVideoEncoderConfiguration: 设置视频编码属性，并将 encodeAlpha 设置为 YES。

AI 调音器Copy Anchor Link

该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 enableVoiceAITuner:type: 方法并传入 AgoraVoiceAITunerType 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。

版权音乐优化Copy Anchor Link

• 该版本在 AgoraMusicPlayerProtocol 类下新增 setPlayMode: 方法，用于设置音乐资源的播放模式。在在线 K 歌房等场景下，你可以根据需求启用伴唱、原唱或导唱模式。
• 该版本在 AgoraMusicContentCenter 类下新增 destroyMusicPlayer: 方法，用于销毁音乐播放器并释放相应的资源。

1v1 视频通话场景Copy Anchor Link

该版本在 AgoraApplicationScenarioType 类下新增枚举 AgoraApplication1V1Scenario（1v1 视频通话）。你可以调用 setVideoScenario: 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。

改进Copy Anchor Link

人脸区域美颜Copy Anchor Link

为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。

其他改进Copy Anchor Link

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

• 优化了传输策略，调用 enableInstantMediaRendering 不再对传输链路的安全性产生影响。
• 废弃了 AgoraClientRoleChangeFailedReason 中的冗余枚举值 AgoraClientRoleChangeFailedRequestTimeout、AgoraClientRoleChangeFailedConnectionFailed。

问题修复Copy Anchor Link

该版本修复了以下问题：

• 在实时互动过程中，当多个远端同时加入频道时 App 偶现崩溃。
• App 切后台一段时间、然后返回前台时，远端视频画面偶现卡住或花屏。
• 发送端调用 startDirectCdnStreaming:publishUrl:mediaOptions: 开始直接向 CDN 推流后，频繁开关或切换网络，偶现接收端黑屏但发送端未收到推流失败回调。
• 调用 pushExternalAudioFrameRawData:samples:sampleRate:channels:trackId:timestamp: 推送外部音频数据，外部音频渲染的采样率如果不是 SDK 推荐的值时，比如 22050 Hz 和 11025 Hz，声音播放失败。

该版本于 2024 年 6 月 4 日发布。

升级必看Copy Anchor Link

该版本修改了播放版权音乐的行为，当调用 AgoraMusicPlayerProtocol 中的 play 方法播放版权音乐媒体文件时，存在以下行为变更：

• v4.3.2 以前版本：SDK 默认播放当前音频文件的第一个音轨。
• v4.3.2： SDK 默认播放伴奏。

改进Copy Anchor Link

1. 提升了 setRemoteSubscribeFallbackOption: 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 setRemoteSubscribeFallbackOption: 动态切换弱网环境下的音视频流回退选项。
2. 媒体播放器支持播放带有 Alpha 通道的 MP4 文件。

问题修复Copy Anchor Link

该版本修复了以下问题：

• App 长时间切后台再返回前台时，远端视频画面卡住或花屏。
• 部分 iPad 设备上的本地预览画面旋转 90°，不符合预期。
• 音视频互动过程中偶现视频流畅度不佳。
• 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。
• 远端用户离开频道时偶现崩溃。
• 调用 startAudioMixing:loopback:cycle: 播放音乐文件，音乐文件播放结束后偶现无法触发 rtcEngine:audioMixingStateChanged:reasonCode:(AgoraAudioMixingStateTypeStopped,AgoraAudioMixingReasonAllLoopsCompleted) 回调报告音乐文件播放完毕。
• 调用 playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: 播放时长不足 1 秒的音效文件并设置不循环播放（ loopCount 为 0 ）时，出现无声。
• 使用媒体播放器播放视频，暂停播放后恢复播放，偶现短暂无声。