声网 Agora SDK 2.4.1 正式上线

声网 Agora Voice/Video SDK 2.4.1 已经正式上线，大家可以在官网「开发者中心」下载对应各系统平台的 SDK。 

该版本我们进一步完善和优化了美颜、屏幕共享等功能，提升了推流服务稳定性，移动端增加了多个在线音效文件播放的支持，部分场景的音质得到了进一步优化。该版本还提供了媒体附属信息的支持，方便开发者在音视频直播等场景中增加互动信息。

新版本新增了网络连接类型变化回调、本地视频状态变化回调、推流状态变化回调、远端音频首帧解码回调以及获取本地和远端播放背景音频音量接口。完善网络连接状态改变原因回调、SDK 和边缘服务器之间上下行丢包率的统计、本地和远端视频解码帧率和渲染帧率相关等接口。同时，全平台提供统一 C++接口，Windows 新增64位开发包，并面向 Windows 和 Mac 平台新增了纯语音开发包。

新增特性

添加媒体附属信息

在一些互动直播场景下，主播有可能会需要发送一些媒体附属信息给观众，比如在线答题中的题目，电商直播中的商品链接、优惠券，或者是在线教育中的题目等。这些都能以 meta-data 的形式添加到视频帧中，与视频数据一起同步下发给观众。

为此，2.4.1新增了相关接口，允许在视频帧中添加 meta-data，发送和接收媒体附属信息。Android 和 Windows平台为 registerMediaMetadataObserver和 IMediaMetadataObserver，iOS和Mac平台为 setMediaMetadataSouce/ setMediaMetadataDelegate和 AgoraMediaMetadataSourceProtocol/ AgoraMediaMetadataDelegateProtocol。

屏幕共享新增参数

我们在 2.4 版中，对屏幕共享功能进行大幅的优化。在 2.4.1 中，为方便用户选择屏幕共享时是否采集鼠标，该版本在AgoraScreenCaptureParameters （ScreenCaptureParameters）类中新增 captureMouseCursor参数。如果不进行设置，该参数默认采集鼠标，即ScreenCaptureParameters增加了captureMouseCursor成员，缺省值为true。

本地视频状态回调

为方便开发者了解本地视频状态，该版本新增onLocalVideoStateChanged 回调，对本地视频提供LOCAL_VIDEO_STREAM_STATE状态和LOCAL_VIDEO_STREAM_STATE_FAILED错误码回调。本地视频有 STOPPED、CAPTURING、ENCODING 和 FAILED 四种状态。当本地视频状态为 FAILED 时，用户可以参考该回调 error 参数返回的错误码进行问题排查。该回调能帮助开发者辨别本地视频故障是由采集还是编码引起的。注意，原有的 onCameraReady 和 onVideoStopped 回调在该版本中仍然有效，但我们不再推荐使用了，建议大家采用新的回调替代它们。

推流状态回调

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

网络连接失败回调参数

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

本地网络连接类型回调

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

获取播放伴奏音量

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

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

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

功能优化

在线音效叠加（Android/iOS）

在很多互动场景下，主播会希望使用更加丰富的音效。因此，该版本新增支持同时播放多个在线音效文件。开发者可以通过多次调用playEffect方法，传入不同的在线音效文件的 URL，实现音效叠加。建议同时最多播放的音效不超过 3 个。

美颜优化

我们在 2.4 版中新增了基础美颜，在这次的 2.4.1 版中，我们对美颜的功能与性能进行了大幅优化。

我们为美颜选项 BeautyOptions 类提供了默认参数，提高了易用性。同时，该版本优化了美颜算法的性能，对低端机型更为友好。根据声网实验室报告显示，优化后的算法下，GPU 消耗、CPU 消耗和功耗均有不同程度的下降。

质量透明优化

该版本进一步完善了网络和视频的质量透明上报统计。

• 增加了SDK和边缘服务器之间的上下行丢包率统计，即rtcStats增加上行丢包率( txPacketLossRate)统计和下行丢包率(rxPacketLossRate)统计。

• 增加本地视频解码帧率和渲染帧率统计，即为 LocalVideoStats增加本地视频解码帧率 (encoderOutputFrameRate)和本地视频渲染帧率(rendererOutputFrameRate)；

• 增加远端视频解码帧率和渲染帧率统计，即为 RemoteVideoStats 增加远端视频解码帧率 (decoderOutputFrameRate)和远端视频渲染帧率(rendererOutputFrameRate)。

屏幕共享编码策略优化

为确保屏幕共享画面完整性，同时保持共享屏幕的宽高比，避免画面裁剪和拉伸，该版本对屏幕共享的编码策略进行了优化。新版本中Agora按如下策略进行编码。假设 dimensions 值为 1920 x 1080，即 2073600 像素：

• 如果屏幕分辨率小于 dimensions，如 1000 x 1000，SDK 直接按 1000 x 1000 进行编码；

• 如果屏幕分辨率大于 dimensions，如 2000 x 2000，SDK 将保持屏幕分辨率的宽高比 1：1，取 dimensions 以内的最大分辨率，即 1440 x 1440， 进行编码。

其它改进

• 优化了AudioScenario 为 GAME_STREAMING 场景的音质效果；

• 优化了部分场景下语音和视频的延时；

• SDK 包大小降低约 0.5 M；

• 提高了用户修改视频属性的码率后，网络质量打分的准确性；

• 默认启用音频质量通知回调，开发者无需调用 enableAudioVolumeIndication 方法，也可以收到 onRemoteAudioStats 回调；

• 提升了视频服务的稳定性；

• windows上，提升了视频设备的兼容性。

点击「阅读原文」了解新版本接口变化，如果在开发过程中遇到问题，可以在RTC 开发者社区的 Agora 版块发帖询问。