发版说明
v4.2.6
该版本于 2023 年 11 月 16 日发布。
该版本修复了以下问题：
- 在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。
v4.2.3
该版本于 2023 年 10 月 12 日发布。
为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动：
AgoraContentInspectType中新增AgoraContentInspectTypeImageModeration枚举值，代表使用声网云市场视频审核插件对视频截图并上传。AgoraContentInspectConfig中新增的serverConfig可选参数用于云市场视频截图上传相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请联系技术支持。
此外，该版本还新增了 enableContentInspectEx 方法，支持同时对多条视频流截图并上传。
该版本新增了 isFeatureAvailableOnDevice 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。
在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。
此外，自该版本起，调用 enableVirtualBackground 和 setBeautyEffectOptions 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 -4 表示该设备不支持开启该功能。
该版本升级了虚拟背景算法，降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4%~10%（具体数值取决于设备型号和平台）。
该版本还进行了如下改进：
- 当调用
setPlaybackSpeed设置音频文件的播放速度时，传入非法参数后会返回错误码 -2，表示方法中设置了无效的参数，需要重新设置参数。 - 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。
该版本修复了以下问题：
- 加入频道偶现的崩溃。
- 本地系统时间不正确时，偶现加入频道失败。
- 调用
playEffect使用相同的soundId播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 - 调用一次
takeSnapshotEx获取视频截图会收到多次snapshotTaken视频截图结果回调。
enableContentInspectExAgoraContentInspectType新增AgoraContentInspectTypeImageModerationAgoraContentInspectConfig中新增serverConfig可选参数isFeatureAvailableOnDeviceAgoraFeatureType
v4.2.2
该版本于 2023 年 7 月 27 日发布。
该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见使用通配 Token。
声网 4.x RTC SDK 均支持使用通配 Token。
该版本新增 preloadChannelByToken[1/2] 和 preloadChannelByToken[2/2] 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。
在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见使用通配 Token。
该版本在 AgoraRtcVideoCanvas 中增加了 backgroundColor 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。
为支持用户选择不同类型的视频源进行本地视频预览，该版本新增 startPreview[2/2] 和 stopPreview[2/2] 方法。你可以调用 startPreview[2/2] 并设置 sourceType 指定待预览的视频源类型；然后调用 stopPreview[2/2] 关闭视频预览。
该方法中设置的视频源类型需要跟 setupLocalVideo 中 AgoraRtcVideoCanvas 的视频源类型一致。
该版本在 AgoraRtcChannelMediaOptions 中新增下列成员，支持你发布第三个、第四个摄像头和屏幕采集到的视频流：
publishThirdCameraTrack：发布第三个摄像头采集的视频。publishFourthCameraTrack：发布第四个摄像头采集的视频。publishThirdScreenTrack：发布第三个屏幕采集的视频。publishFourthScreenTrack：发布第四个屏幕采集的视频。
目前 SDK 支持在同一时间、同一 AgoraRtcConnection 中发布多路音频流、一路视频流。
该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。
该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 startOrUpdateChannelMediaRelay 和 startOrUpdateChannelMediaRelayEx 时，你可以指定最多 6 个目标频道。
为提升设备编解码能力查询功能，该版本在 CodecCapAgoraVideoCodecCapInfoInfo 中新增 codecLevels 成员。当成功调用 queryCodecCapability 后，可通过 codecLevels 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。
- 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。
- 为帮助用户了解更多类型的远端视频状态改变的原因，
remoteVideoStateChangedOfUid回调中新增了AgoraVideoRemoteReasonCodecNotSupport枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。
该版本修复了以下问题：
- 加入频道后，偶现本地用户听自己及远端的声音时出现杂音。
- 网络异常导致频道连接断开后，频道连接恢复较慢。
- 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。
- 自采集场景下，
setBeautyEffectOptions、setLowlightEnhanceOptions、setVideoDenoiserOptions和setColorEnhanceOptions无法自动加载插件。
startPreview[2/2]stopPreview[2/2]preloadChannelByToken[1/2]preloadChannelByToken[2/2]updatePreloadChannelTokenAgoraRtcChannelMediaOptions中增加下列成员：publishThirdCameraTrackpublishFourthCameraTrackpublishThirdScreenTrackpublishFourthScreenTrack
AgoraVideoCodecCapLevelsAgoraVideoCodecCapabilityLevelAgoraRtcVideoCanvas中增加backgroundColor成员CodecCapAgoraVideoCodecCapInfoInfo中增加codecLevels成员AgoraVideoRemoteReason中增加AgoraVideoRemoteReasonCodecNotSupport枚举
v4.2.1
该版本于 2023 年 6 月 21 日发布。
该版本改进了网络传输策略，提升了音视频交互的流畅度。
该版本修复了以下问题：
- SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。
- 发送端调用
setAINSMode开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。
- 发送端启用屏幕共享功能后，偶现接收端看到共享画面的延迟较高。
v4.2.0
该版本于 2023 年 5 月 24 日发布。
该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。
onCaptureVideoFrame和onPreEncodeVideoFrame回调中新增了sourceType参数，用于表示具体的视频源类型。- 以下回调已删除，请通过
onPreEncodeVideoFrame和onCaptureVideoFrame中的sourceType参数得知视频源类型。onScreenCaptureVideoFrameonPreEncodeScreenVideoFrame
AgoraRtcChannelMediaOptions中的publishCustomAudioTrackEnableAec已删除，请改用publishCustomAudioTrack。AgoraRtcChannelMediaOptions中的成员publishTrancodedVideoTrack变更为publishTranscodedVideoTrack。AgoraRtcChannelMediaOptions中的成员publishCustomAudioSourceId变更为publishCustomAudioTrackId。
- 删除
sharedMediaRecorderWithRtcEngine方法，可通过该版本新增的createMediaRecorder方法来创建录制对象。 - 删除
startRecording、stopRecording、setMediaRecorderDelegate中的connection参数。 - 删除
AgoraMediaRecorder类中的destroy方法，你可直接调用该版本新增的destroyMediaRecorder方法来销毁录制对象以释放资源。
自该版本起，SDK 新增对第三方虚拟声卡的支持，你可以将第三方虚拟声卡作为 SDK 的音频输入或输出设备。你可以通过 stateChanged 回调来了解当前 SDK 选择的输入输出设备是否为虚拟声卡。
加频道时如果设置 AgoraALD、Soundflower 作为系统的默认输入或输出设备，会造成无声。
didApiCallExecute已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。enableDualStreamMode[1/2] 和enableDualStreamMode[2/2] 已废弃，请改用setDualStreamMode[1/2] 和setDualStreamMode[2/2]。startChannelMediaRelay、updateChannelMediaRelay、startChannelMediaRelayEx和updateChannelMediaRelayEx已废弃，请改用startOrUpdateChannelMediaRelay和startOrUpdateChannelMediaRelayEx。
该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 setAINSMode 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。
为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 enableVirtualBackground 方法时，将自定义背景设置为更多类型：
- 将背景处理为 alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。
- 将背景替换为多种格式的本地视频。
该版本新增 setVideoScenario 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化：
- 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。
- 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。
该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 stateDidChanged 、informationDidUpdated 中新增 channelId 和 uid 参数，用于表示录制的音视频流的具体信息，并新增 createMediaRecorder 方法，用于创建本地或远端的录制对象。
你可以通过如下方法体验本地录制远端音视频功能：
createMediaRecorder：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。setMediaRecorderDelegate：设置录制回调对象。startRecording：开始录制。stopRecording：停止录制。destroyMediaRecorder：销毁录制对象。
该版本新增本地合图功能，用户可以调用 startLocalVideoTranscoder 方法，在本地将多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）混合和渲染，以实现自定义布局和效果。通过这项功能，你可以轻松创建个性化的视频显示效果，满足各种场景需求，如远程会议、直播、在线教育场景，同时支持人像画中画等功能。
另外，SDK 还提供了updateLocalTranscoderConfiguration 方法和 didLocalVideoTranscoderErrorWithStream 回调。当你在开启本地合图后，可以调用 updateLocalTranscoderConfiguration 更新合图的配置；当你在开启本地合图或者更新本地合图配置失败时，可通过 didLocalVideoTranscoderErrorWithStream 回调得知合图失败的原因。
本地合图对 CPU 的消耗较高，声网建议你在性能较高的设备上开启该功能。
在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 getNtpWallTimeInMs 方法获取当前的 NTP (网络时间协议) 时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。
该版本新增了 setLocalVoiceFormant 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 setLocalVoicePitch 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。
针对自定义视频和音频采集场景，该版本新增 getCurrentMonotonicTimeInMs 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。
该版本新增 startCameraCapture 和 startScreenCapture[2/2] 方法，通过多次调用并指定 sourceType 参数可以开启多路摄像头采集的视频流和多路屏幕采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头和显示器的场景。
该版本新增 startOrUpdateChannelMediaRelay 和 startOrUpdateChannelMediaRelayEx 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。
为更好地满足音频自采集的场景需求，该版本新增了 createCustomAudioTrack 和 destroyCustomAudioTrack 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性：
- 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。
- 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。
该版本修复了以下问题：
- 当快速切换身份角色时，观众端听不到声音。
- 接收端默认接收小流几秒后自动变为大流。
- 调用
getdefaultaudiodevice后返回值中的type字段信息错误。 - 屏幕共享偶现共享画面抖动。
startCameraCapturestopCameraCapturestartScreenCapture[2/2]stopScreenCapture[2/2]startOrUpdateChannelMediaRelaystartOrUpdateChannelMediaRelayExgetNtpWallTimeInMssetVideoScenariogetCurrentMonotonicTimeInMsdidLocalVideoTranscoderErrorWithStreamstartLocalVideoTranscoderupdateLocalTranscoderConfigurationsetAINSModecreateCustomAudioTrackdestroyCustomAudioTrackcreateMediaRecorderdestroyMediaRecorderAudioTrackConfigAgoraRecorderStreamInfoAUDIO_AINS_MODEAgoraAudioTrackTypeAgoraApplicationScenarioTypeAgoraScreenCaptureFrameRateCapabilityAgoraRtcEngineConfig中新增domainLimit和autoRegisterAgoraExtensions属性stateDidChanged、informationDidUpdated中新增channelId和uid参数onCaptureVideoFrame和onPreEncodeVideoFrame中增加sourceType参数AgoraVirtualBackgroundSourceType中新增AgoraVirtualBackgroundNone和AgoraVirtualBackgroundVideo
enableDualStreamMode[1/2]enableDualStreamMode[2/2]startChannelMediaRelaystartChannelMediaRelayExupdateChannelMediaRelayupdateChannelMediaRelayExdidReceiveChannelMediaRelayEventAgoraChannelMediaRelayEvent
startPrimaryScreenCapturestartSecondaryScreenCapturestopPrimaryScreenCapturestopSecondaryScreenCapturestartPrimaryCameraCapturestartSecondaryCameraCapturestopPrimaryCameraCapturestopSecondaryCameraCapturedidApiCallExecuteAgoraRtcChannelMediaOptions中的publishCustomAudioTrackEnableAecsharedMediaRecorderWithRtcEngineAgoraMediaRecorder类中的destroystartRecording、stopRecording、setMediaRecorderDelegate中删除connection参数onScreenCaptureVideoFrameonPreEncodeScreenVideoFrame
v4.1.1
该版本于 2023 年 2 月 8 日发布。
自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。
如果你想自定义视频编码分辨率，可调用 setVideoEncoderConfiguration 方法，重新设置视频编码参数配置中的视频编码分辨率。
由于默认分辨率的提升，会影响集合分辨率从而导致费用变更。详见计费说明。
该版本起，setRemoteVideo 更名为 setRemoteVideoSubscriptionOptions；setRemoteVideoEx 更名为 setRemoteVideoSubscriptionOptionsEx。如果你将 SDK 升级至该版本或更高版本，请在调用处同步修改以上两个方法的名称。
该版本新增 enableInstantMediaRendering 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。
该版本新增 startMediaRenderingTracing 和 startMediaRenderingTracingEx 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 videoRenderingTracingResultOfUid 回调报告相关事件的信息。
声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 videoRenderingTracingResultOfUid 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。
自该版本起，SDK 对 onRenderVideoFrame 回调进行了优化，在不同的视频处理模式下返回值的意义不同：
- 当视频处理模式为
AgoraVideoFrameProcessModeReadOnly时，返回值无实际含义。 - 当视频处理模式为
AgoraVideoFrameProcessModeReadWrite时，返回YES代表设置 SDK 接收视频帧；返回NO代表设置 SDK 丢弃视频帧。
该版本修复了以下问题：
- 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。
- 把播放器的渲染视图设为
UIViewController的视图后，使用播放器播放视频，视频窗口切到全屏时视频画面会从左下角开始逐渐放大。 - 加入频道后接入外接摄像头，调用
setDevice指定视频采集设备为该外接摄像头，方法未生效。 - 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。
- 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。
enableInstantMediaRenderingstartMediaRenderingTracingstartMediaRenderingTracingExvideoRenderingTracingResultOfUidAgoraMediaRenderTraceEventAgoraVideoRenderingTracingInfo
setRemoteVideo更名为setRemoteVideoSubscriptionOptionssetRemoteVideoEx更名为setRemoteVideoSubscriptionOptionsEx
enableRemoteSuperResolutionAgoraRtcRemoteVideoStats中删除superResolutionType
v4.1.0
该版本于 2022 年 12 月 19 日发布。
该版本新增 setHeadphoneEQParameters 方法，用于调节耳机均衡器的低频和高频参数，主要应用于空间音效场景。如果在调用 setHeadphoneEQPreset 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。
该版本在 AgoraRtcEngineKit 及 AgoraRtcEngineKitEx 中新增 setRemoteVideo 方法，当你调用 setEncodedVideoFrameDelegate 方法为编码后的视频注册视频帧观测器时，SDK 默认订阅编码后的视频帧。如果你想要修改订阅选项，可以调用该新增的方法进行设置。
有关更多注册视频观测器和订阅选项的介绍，详见 API 参考。
自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在移动端和桌面端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。
如果你希望体验该功能，请联系 sales@shengwang.cn。
该版本新增了一系列回调，帮助你更好地了解音视频设备的状态。
onVideoDeviceStateChanged（C++）：当视频设备的状态发生改变时上报。onAudioDeviceStateChanged（C++）：当音频设备的状态发生改变时上报。onAudioDeviceVolumeChanged（C++）：当音频设备或 App 的音量发生改变时上报。
该版本在 AgoraCameraCapturerConfiguration 中增加了 followEncodeDimensionRatio 成员，你可以在使用摄像头采集视频时，通过该成员设置是否跟随 setVideoEncoderConfiguration 中已经设置的视频宽高比。
该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。
- 新增
muteLocalAudioStreamEx和muteLocalVideoStreamEx方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增
muteAllRemoteAudioStreamsEx和muteAllRemoteVideoStreamsEx方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增
startRtmpStreamWithoutTranscodingEx、startRtmpStreamWithTranscodingEx、updateRtmpTranscodingEx和stopRtmpStreamEx方法，用于实现多频道场景下的旁路推流。 - 新增
startChannelMediaRelayEx、updateChannelMediaRelayEx、pauseAllChannelMediaRelayEx、resumeAllChannelMediaRelayEx和stopChannelMediaRelayEx方法，用于实现多频道场景下的跨频道媒体流转发。 - 新增
leaveChannelEx[2/2] 方法，相较于leaveChannelEx[1/2] 方法新增了options参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。
一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 AgoraVideoEncoderConfiguration 中新增 advancedVideoOptions 成员，用于视频编码属性的进阶设置：
compressionPreference：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。encodingPreference：视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。
使用声网私有媒体服务器的场景下，为支持用户在调用 setLocalAccessPoint 方法时的进阶设置，该版本在 AgoraLocalAccessPointConfiguration 中新增 advancedConfig 成员参数，该参数支持如下设置：
logUploadServer：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。
为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 didClientRoleChanged 回调中新增 newRoleOptions 参数，该参数取值如下：
AgoraAudienceLatencyLevelLowLatency(1): 低延时，属于极速直播。AgoraAudienceLatencyLevelUltraLowLatency(2): 超低延时，属于互动直播。
该版本对屏幕共享功能做了一系列优化，除以下列出的功能性改进之外，还有一部分可用性提升，详见问题修复。
- 兼容更多设备和场景，包括但不限于：双显卡设备，使用外接屏幕进行屏幕共享。
- 支持超高清视频 (分辨率为 4K，帧率为 60 fps)，你可以在满足要求的设备上使用该功能。声网推荐的最低设备规格为：2021年m1 MacBook pro 16 英寸。
为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 onDirectCdnStreamingStats 回调报告推送的视频流的实际分辨率。
该版本对 updateChannelMediaRelay 方法做了如下优化：
- 4.1.0 版本前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码
AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8)，你需要重新调用updateChannelMediaRelay方法。 - 4.1.0 版本及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。
该版本基于 AI 方法重构了AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。
该版本对虚拟背景算法做了如下优化：
- 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。
- 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。
- 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。
- 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。
- 降低了推送外部音频源时的上行延迟。
- 提升了会议场景 (
AgoraAudioScenarioMeeting) 默认参数配置下的回声消除性能。 - 提升了 SDK 视频渲染的流畅度。
- 降低了当主播调用
muteLocalVideoStream方法时本地设备的 CPU 占用率和耗电量。 - 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。
该版本修复了以下问题：
-
在屏幕共享场景下，将共享的窗口最小化或关闭共享窗口时，共享窗口自动切换为该 App 的其他窗口。
-
在屏幕共享场景下偶现系统声音音量变小。
-
在屏幕共享场景下，当共享的窗口为半屏模式时，对窗口的描边不正确。
-
在屏幕共享场景下，远端用户看到的画面偶现黑屏、卡顿、崩溃。
-
在屏幕共享场景下，偶现
networkQuality回调报告频道内指定用户的上下行网络状态不准确。 -
启动并停止音频采集设备测试后，启动音频播放设备测试时必现无声。
-
在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。
-
didVideoPublishStateChange回调报告的视频源类型不准确。 -
调用
getExtensionProperty失败，返回空字符串。 -
当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。
setHeadphoneEQParameterssetRemoteVideoSubscriptionOptionssetRemoteVideoSubscriptionOptionsExAgoraVideoSubscriptionOptionsmuteLocalAudioStreamExmuteLocalVideoStreamExmuteAllRemoteAudioStreamsExmuteAllRemoteVideoStreamsExstartRtmpStreamWithoutTranscodingExstartRtmpStreamWithTranscodingExupdateRtmpTranscodingExstopRtmpStreamExstartChannelMediaRelayExupdateChannelMediaRelayExpauseAllChannelMediaRelayExresumeAllChannelMediaRelayExstopChannelMediaRelayExAgoraCameraCapturerConfiguration中增加followEncodeDimensionRatioAgoraRtcLocalVideoStats中增加hwEncoderAcceleratingleaveChannelEx[2/2]AgoraVideoEncoderConfiguration中增加advancedVideoOptions成员AgoraLocalAccessPointConfiguration中增加advancedConfig成员didClientRoleChanged中增加newRoleOptionsadjustUserPlaybackSignalVolumeExenableAudioVolumeIndicationEx
didApiCallExecute，改用具体方法触发的回调。
- 删除了
AgoraLiveTranscoding类中的废弃成员参数backgroundImage和watermark didReceiveChannelMediaRelayEvent中删除AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8)
v4.0.1
该版本于 2022 年 9 月 29 日发布。
如果你已经使用了以下类或方法，请在升级到该版本后重新调用方法并更新参数设置。
- 为提高代码易用性，该版本将以下类中
Optional类型的参数变更为Bool、Int等基本数据类型：AgoraDirectCdnStreamingMediaOptions中publishCameraTrack、publishMicrophoneTrack、publishCustomAudioTrack、publishCustomVideoTrack、publishMediaPlayerAudioTrack的参数类型由Optional变为Bool型。AgoraMediaSource中的isAgoraSource和isLiveSource由Optional型变为Bool型。AgoraRtcChannelMediaOptions中的所有参数类型由Optional变为Bool型或Int型。
destroyCustomVideoTrack方法中的position参数变更为trackid。- 删除了
enableDualStreamMode[3/3] 和enableDualStreamModeEx中的sourceType参数以及enableDualStreamMode[2/3] 方法，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。
该本版新增耳返功能。你可以调用 enableInEarMonitoring 开启耳返功能。
成功开启耳返功能后，你可以调用 setAudioFrameDelegate 注册音频观测器，SDK 会触发 onEarMonitoringAudioFrame 回调报告耳返原始音频数据。你可以使用自己的音效处理模块对耳返音频数据进行前处理，实现自定义音效，声网推荐你在如下两种方式中选其一来设置耳返音频数据格式：
- 调用
setEarMonitoringAudioFrameParametersWithSampleRate方法设置耳返音频数据格式，SDK 会根据该方法中的参数计算采样间隔，并根据该采样间隔触发onEarMonitoringAudioFrame回调。 - 在
getEarMonitoringAudioParams回调的返回值中设置耳返音频数据格式，SDK 会根据该回调的返回值计算采样间隔，并根据该采样间隔触发onEarMonitoringAudioFrame回调。
如需调节耳返音量，你可以调用 setInEarMonitoringVolume。
为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 getNetworkType 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 networkTypeChangedToType 回调，报告当前的网络连接类型。
该版本新增音强选流功能。该功能开启后，声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请联系技术支持。
同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗，详见音强选流。
如需开启该功能，请联系技术支持。
该版本对双流模式做了优化，在加入频道前后均可调用 enableDualStreamMode 和 enableDualStreamModeEx。
扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式（即：默认不主动发送小流），可通过以下步骤开启发送小流：
- 接收端主播调用
setRemoteVideoStreamType或setRemoteDefaultVideoStreamType发起接收小流申请。 - 发送端收到申请后自动切换为发送小流模式。
如果你想修改上述发送端的默认行为，可以调用 setDualStreamMode[1/2] 或 setDualStreamMode[2/2] 方法，将 mode 参数设置为 AgoraDisableSimulcastStream （始终不发送小流）或 AgoraEnableSimulcastStream （始终发送小流）。
该版本新增了如下适用于空间音效场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。
- 隔声区域：你可以通过调用
setZones设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用setPlayerAttenuation和setRemoteAudioAttenuation方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖setZones中的声音衰减系数。 - 多普勒音效：你可以通过设置
SpatialAudioParams中的enable_doppler参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下（比如赛车游戏场景），接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用
setHeadphoneEQPreset方法使用预设的耳机均衡效果，以改善耳机的听感。
该版本优化了 videoSizeChangedOfUid 的触发逻辑，当单独调用 startPreview 时，也可触发该回调并上报本地视频大小发生改变。
该版本修复了以下问题：
-
通过摄像头采集视频时，如果在
AgoraCameraCapturerConfiguration中设置的视频宽高比例和在setVideoEncoderConfiguration中设置的不一致，导致本地视频预览的画面比例未按照后者的设置呈现。 -
在频道内调用
setVideoEncoderConfigurationEx将视频的分辨率调高时，偶现失效。 -
使用媒体播放器播放视频，先调用
play再调用pause暂停播放后，调用seek指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用resume恢复播放后，偶现视频画面出现快进。
enableInEarMonitoringsetEarMonitoringAudioFrameParametersWithSampleRateonEarMonitoringAudioFramesetInEarMonitoringVolumegetEarMonitoringAudioParamsgetNetworkTypeAgoraRtcChannelMediaOptions中新增isAudioFilterablesetDualStreamMode[1/2]setDualStreamMode[2/2]setDualStreamModeExAgoraSimulcastStreamModesetZonessetPlayerAttenuationsetRemoteAudioAttenuationmuteRemoteAudioStreamSpatialAudioParamssetHeadphoneEQPresetAgoraHeadphoneEQPreset
enableDualStreamMode[3/3]enableDualStreamModeEx
startEchoTest[2/3]
enableDualStreamMode[2/3]
v4.0.0
该版本于 2022 年 8 月 3 日发布。
v4.0.0 SDK 对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见迁移指南。
- 多频道
- 媒体流发布控制
- 自定义视频采集与渲染（Media IO 方式）
- 警告码
该版本通过设置 AgoraRtcEngineKit(Ex) 和 AgoraRtcChannelMediaOptions 实现一个 AgoraRtcEngineKit 实例同时采集多组音视频流并发布到远端：
调用 joinChannelByToken 加入首个频道后，多次调用 joinChannelExByToken 加入多个频道，通过不同的用户 ID (localUid) 和 AgoraRtcChannelMediaOptions 设置发布指定的流到不同的频道。
支持通过设置 AgoraRtcChannelMediaOptions 中的 publishSecondaryCameraTrack 和 publishSecondaryScreenTrack 同时发布多路摄像头采集或者屏幕共享的视频流。
同时，该版本支持通过 createCustomVideoTrack 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流：
-
创建自采集视频轨道：调用
createCustomVideoTrack方法创建一个自定义视频轨道，并获得视频轨道 ID。 -
设置频道中待发布的自采集视频轨道：在每个频道的
AgoraRtcChannelMediaOptions中，将customVideoTrackId参数设置为你想要发布的视频轨道 ID，并将publishCustomVideoTrack设置为true。 -
推送外部视频源：调用
pushExternalVideoFrame，并将videoTrackId指定为步骤 2 中指定的视频轨道 ID，即可实现在多个频道中发布对应的自定义视频源。
结合多频道能力，你还可以体验如下功能：
- 将多组音视频流通过不同的用户 ID (
uid) 发布到远端。 - 将多路音频流混音后通过一个用户 ID (
uid) 发布到远端。 - 将多组视频频流通过不同的用户 ID (
uid) 发布到远端。 - 将多路视频流合图后通过一个用户 ID (
uid) 发布到远端。
为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持 4K 分辨率。优化了 FEC（Forward Error Correction）算法，可根据视频帧包数与帧率进行自适应切换，降低 4K 场景下的视频卡顿率。
你可以在调用 setVideoEncoderConfiguration 时，设置编码分辨率为 4K (3840 × 2160)、帧率为 60 fps。当你的设备不支持 4K 时，SDK 支持自动回退到适合的分辨率和帧率。
为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 createMediaPlayerWithDelegate 创建媒体播放器后，你可以通过 AgoraRtcMediaPlayerProtocol 类的一系列方法体验内置媒体播放器的各类功能：
- 自动播放本地、在线、自定义的媒体资源。
- 预先加载待播放的媒体资源。
- 根据网络情况切换媒体资源的播放线路。
- 将媒体播放器的音视频流推送到任意频道、分享给远端用户。
- 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。
自该版本起，SDK 支持新版 AI 降噪（相对于 v3.7.0 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。
如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。
为还原音频的细节、提升音频的清晰度，该版本在 AgoraVoiceBeautifierPreset 中新增 AgoraVoiceBeautifierUltraHighQuality。在语聊、歌唱等以人声为主的场景中，你可以调用 setVoiceBeautifierPreset 并使用该枚举体验超高音质。
空间音效功能当前处于实验阶段，请联系 sales@shengwang.cn 开通空间音效功能，如果需要技术支持，请联系技术支持。
该版本提供本地直角坐标系计算方案实现空间音效：
-
该方案使用
AgoraLocalSpatialAudioKit类实现空间音效，通过 SDK 计算远端用户的空间坐标。你需要分别调用updateSelfPosition和updateRemotePosition更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音效。 -
该方案通过 SDK 计算媒体播放器的空间坐标。你需要在
AgoraCloudSpatialAudioKit或AgoraLocalSpatialAudioKit类中分别调用updateSelfPosition和updatePlayerPositionInfo更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音效。
该版本为实时合唱赋予了如下能力：
- 支持两人及两人以上合唱。
- 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。
- 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。
该版本在 AgoraAudioScenario 中新增 AgoraAudioScenarioChorus 枚举设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。
为在声网 SDK 的基础上增强实时音视频互动性，该版本支持声网云市场插件的一站式解决方案：
- 方便集成：只需执行简单统一的 API 即可实现模块化功能的集成，将实时互动模块集成效率提高约 95%。
- 可扩展性设计：模块化和可扩展的 SDK 设计风格赋予了声网 SDK 良好的可扩展性，更有利于开发者基于声网云市场插件生态快速搭建好用的实时互动应用。
- 打造生态系统：可容纳众多开发者的实时音视频 App 社区，提供多种扩展组合。添加并开启云市场插件后，开发者可以实现更为丰富的实时音视频互动功能，详见实现插件功能。
- 助力服务商：支持服务商将技术产品以插件的形式与声网 SDK 做技术上的融合，在声网云市场中展示并售卖，与声网一起共建开发者的实时互动生态系统。如何开发和发布插件详见服务商流程。
为满足各类业务场景对频道管理的需求，该版本在 AgoraRtcChannelMediaOptions 中新增了如下功能：
- 设置或切换多种音视频源的发布
- 设置或切换频道场景、用户角色
- 设置或切换订阅视频的大小流类型
- 控制音频发布时延
在调用 joinChannelByToken 或 joinChannelExByToken 时设置 AgoraRtcChannelMediaOptions，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 updateChannelWithMediaOptions 随时更新 AgoraRtcChannelMediaOptions 中的设置，例如，切换发布的音视频源。
该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享：
- 在加入频道前调用
startScreenCaptureByDisplayId，然后调用joinChannelByToken[2/4] 加入频道并设置publishScreenTrack或publishSecondaryScreenTrack为YES，即可开始屏幕共享。 - 在加入频道后调用
startScreenCaptureByDisplayId，然后调用updateChannelWithMediaOptions设置publishScreenTrack或publishSecondaryScreenTrack为YES，即可开始屏幕共享。
该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通 AgoraRtcEngineKit(Ex) 类下的同名方法来实现该功能。
setSubscribeAudioBlacklist：设置音频订阅黑名单。setSubscribeAudioWhitelist：设置音频订阅白名单。setSubscribeVideoBlacklist：设置视频订阅黑名单。setSubscribeVideoWhitelist：设置视频订阅白名单。
如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。
为方便用户灵活修改音频场景，该版本新增 setAudioScenario 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (AgoraAudioScenarioDefault) 切换为高音质场景 (AgoraAudioScenarioGameStreaming)，你可以调用该方法。
该本版新增 setLocalAccessPoint 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。
该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 enableVideoImageSource 来开启该功能，并通过 options 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。
该版本通过 leaveChannel 和 joinChannelByToken 切换频道即可实现和 v3.7.0 中 switchChannelByToken 一样的切换速度，无需额外调用 switchChannelByToken 方法。
该版本新增支持推送 I422 格式的外部视频帧，你可以通过 pushExternalVideoFrame 方法将 I422 格式的外部视频帧推送至 SDK。
该版本在 reportAudioVolumeIndicationOfSpeakers 的 AgoraRtcAudioVolumeInfo 中新增 voicePitch 参数。你可以通过 voicePitch 获取本地用户的人声音调，从而实现唱歌评分等业务功能。
该版本优化了 startPreview 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 startPreview 方法来开启视频预览，无调用时序要求。
你可以通过 setRemoteDefaultVideoStreamType 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。