发版说明
macOS 15 Sequoia Beta 系统问题
当 App 路径（以及 App 名称）中包含中文字符时，编译后的 Metal shader library 中可能不包含任何方法，导致 App 无法正常运行。解决方案可参考如何解决 macOS 15 Beta 不支持路径中包含中文字符的 App 问题？
v4.4.0
该版本于 2024 年 8 月 5 日发布。
该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。
自 v4.4.0 起，RTC SDK 提供 API 下架说明，包含各版本废弃及删除的 API 信息。详见 API 下架说明。
-
为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的
AgoraExtensionContext了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。原有回调 现有回调 onEventonEventWithContext:key:value:onExtensionStartedonExtensionStartedWithContext:onExtensionStoppedonExtensionStoppedWithContext:onExtensionErroronExtensionErrorWithContext:error:message: -
该版本将
receiveMetadata回调改名为didMetadataReceived:，并删除了回调中的data、timeStamp参数，你可以通过新增的metadata参数来获取 Metadata 的相关信息，包括timeStamp（发送数据的时间戳）、uid（用户 ID）、channelId（源频道名称）等。
该版本新增 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。
如需了解在各场景下实现 Alpha 特效的最佳实践，详见实现 Alpha 透明特效。
该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 enableVoiceAITuner:type: 方法并传入 AgoraVoiceAITunerType 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。
该版本在 AgoraApplicationScenarioType 类下新增枚举 AgoraApplication1V1Scenario（1v1 视频通话）。你可以调用 setVideoScenario: 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。
为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。
该版本还进行了如下改进：
- 优化了传输策略，调用
enableInstantMediaRendering不再对传输链路的安全性产生影响。 rtcEngine:localVideoStateChangedOfState:reason:sourceType:回调中新增AgoraLocalVideoStreamReasonScreenCaptureDisplayDisconnected枚举，表示进行屏幕采集的显示器已断开连接。- 优化了共享窗口的视频链路，降低了 CPU 占用率。
- 废弃了
AgoraClientRoleChangeFailedReason中的冗余枚举值AgoraClientRoleChangeFailedRequestTimeout、AgoraClientRoleChangeFailedConnectionFailed。
无。
v4.3.2
该版本于 2024 年 6 月 4 日发布。
提升了 setRemoteSubscribeFallbackOption: 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 setRemoteSubscribeFallbackOption: 动态切换弱网环境下的音视频流回退选项。
该版本修复了以下问题：
- 音视频互动过程中偶现视频流畅度不佳。
- 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。
- 远端用户离开频道时偶现崩溃。
v4.3.1
该版本于 2024 年 4 月 29 日发布。
为提升在线会议、秀场、在线教育等场景中的主播演讲效果，该版本新增 enableCameraCenterStage: 方法开启人像锁定功能。该功能可确保主播无论移动与否，始终位于画面中心，以取得良好的演讲效果。
在开启人像锁定前，建议你先调用 isCameraCenterStageSupported 查询当前设备性能是否支持该功能。支持的设备清单可参考 API 文档。
该版本在 AgoraEncryptionConfig 中新增 datastreamEncryptionEnabled 成员用于启用数据流加密。你可以在调用 enableEncryption:encryptionConfig: 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE 和 ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE 枚举得知。
该版本新增视频小流的自适应配置功能，当你调用 setDualStreamMode:streamConfig: 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示：
- 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。
- 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。
- 新增
enableEncryptionEx:encryptionConfig:connection:方法，用于多频道场景下开启媒体流或数据流加密。 - 新增
setAudioMixingPlaybackSpeed:方法，用于设置音乐文件的播放速度。 - 新增
getCallIdEx:方法，用于多频道场景下获取通话 ID。
为方便你了解本地视频状态改变的具体原因，该版本在 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调的 AgoraLocalVideoStreamReason 枚举类中新增如下枚举：
AgoraLocalVideoStreamReasonScreenCaptureRecoverFromMinimized(27)：进行屏幕采集的窗口已经从最小化状态恢复正常。
该版本在 AgoraRtcDeviceInfo 中新增 deviceTypeName 成员，用于获取音频设备的类型，如 built-in、USB、HDMI 等。
为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法：
- 支持识别任意纯色背景，不再局限于绿幕。
- 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。
- 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。
为提升音频自采集的灵活性，该版本废弃 pushExternalAudioFrameSampleBuffer: 并新增 pushExternalAudioFrameSampleBuffer:sampleRate:channels:trackId:。相比废弃方法，新增方法中增加了 sampleRate、channels、trackId 参数，支持你通过自定义音频轨道将外部 CMSampleBuffer 音频数据推送到频道内，并支持设置外部音频源的采样率和声道数。
该版本在 AgoraEarMonitoringFilterType 中新增 AgoraEarMonitoringFilterReusePostProcessingFilter(1<<15) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。
该版本还进行了如下改进：
- 优化了非屏幕共享场景的视频编解码策略，节省系统性能开销。
- 针对 macOS 14 及以上系统，优化了
getScreenCaptureSourcesWithThumbSize:iconSize:includeScreen:的行为。自该版本起，调用该方法返回的可用窗口资源中会自动过滤小组件窗口。 - 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。
- 在
AgoraAudioEffectPreset中新增AgoraAudioEffectPresetRoomAcousticsChorus（合唱音效），可使人声在合唱场景下更具空间立体感。 - 在
AgoraRtcRemoteAudioStats中新增e2eDelay，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。
该版本修复了以下问题：
- 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。
- 用户插拔一次蓝牙或有线耳机，音频状态改变回调
rtcEngine:device:type:stateChanged:会触发多次。 - 当发送端用户的网络环境恶化（例如弱网）时，接收端偶现视频流畅度降低、卡顿增加。
-
AgoraLocalVideoStreamReason中新增如下枚举：AgoraLocalVideoStreamReasonScreenCaptureRecoverFromMinimized
-
AgoraEncryptionConfig中新增datastreamEncryptionEnabled -
AgoraEncryptionErrorType中新增如下枚举：ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILUREENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE
-
AgoraRtcDeviceInfo新增deviceTypeName -
AgoraRtcRemoteAudioStats新增e2eDelay -
AgoraErrorCode新增AgoraErrorCodeDatastreamDecryptionFailed -
AgoraAudioEffectPreset新增AgoraAudioEffectPresetRoomAcousticsChorus -
AgoraEarMonitoringFilterType新增枚举AgoraEarMonitoringFilterBuiltInAudioFilters(1<<15) -
pushExternalAudioFrameSampleBuffer:sampleRate:channels:trackId:
v4.3.0
该版本于 2024 年 2 月 22 日发布。
该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。
为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。
| 回调 | 原有参数名 | 现有参数名 |
|---|---|---|
rtcEngine:localAudioStateChanged:reason: | error | reason |
localVideoStateChanged | error | reason |
onDirectCdnStreamingStateChanged:reason:message: | error | reason |
AgoraRtcMediaPlayer:didChangedToState:reason: | error | reason |
rtcEngine:rtmpStreamingChangedToState:state:reason: | errCode | reason |
| 原有枚举类 | 现有枚举类 |
|---|---|
AgoraAudioLocalError | AgoraAudioLocalReason |
AgoraLocalVideoStreamError | AgoraLocalVideoStreamReason |
AgoraDirectCdnStreamingError | AgoraDirectCdnStreamingReason |
AgoraMediaPlayerError | AgoraMediaPlayerReason |
AgoraRtmpStreamingError | AgoraRtmpStreamingReason |
AgoraMusicContentCenterStatusCode | AgoraMusicContentCenterStateReason |
有关具体枚举的改名详见 API 变更。
为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项：
| 已删除的方法和回调 | 替代的方法和回调 |
|---|---|
| startOrUpdateChannelMediaRelay: |
| startOrUpdateChannelMediaRelayEx:connection: |
didReceiveChannelMediaRelayEvent | rtcEngine:channelMediaRelayStateDidChange:error: |
该版本对 AgoraLocalVideoStreamReason 枚举类中的枚举进行了如下修改：
AgoraLocalVideoStreamErrorEncodeFailure的枚举名变更为AgoraLocalVideoStreamReasonCodecNotSupport。
- 在 v4.3.0 之前，当你调用
disableAudio关闭整个音频模块后，声卡采集功能不会被关闭。 - 从 v4.3.0 起，当你调用
disableAudio关闭音频模块后，声卡采集功能也会被关闭，如果你需要再次启用声卡采集功能，需要在调用enableAudio启用音频模块后再次调用enableLoopbackRecording:deviceName:。
出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案：
- 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。
- 如有其他特殊需求，请联系技术支持并附上对应的加密日志。
该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下：
- 调用
setupLocalVideo:设置第一个视图：在AgoraRtcVideoCanvas中设置position参数为AgoraVideoModulePositionPostCaptureOrigin（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。 - 调用
setupLocalVideo:设置第二个视图：在AgoraRtcVideoCanvas中设置position参数为AgoraVideoModulePositionPostCapture，此处观测到的视频具备视频前处理的效果。 - 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。
该版本新增 queryDeviceScore 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请联系技术支持。
该版本新增 selectMultiAudioTrack:publishTrackIndex: 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 openWithMediaSource: 打开媒体文件，并通过 AgoraMediaSource 中新增的 enableMultiAudioTrack 成员来开启音轨控制。
该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。
setRemoteSubscribeFallbackOption:：设置弱网环境下订阅的音视频流回退选项。rtcEngine:didRemoteSubscribeFallbackToAudioOnly:byUid:：订阅流已回退为音频流或恢复为音视频流回调。setPlayerOption:value:和setPlayerOptionString:value:：设置媒体播放器选项，用于提供技术预览或特别定制功能。enableCustomAudioLocalPlayback:enabled:：设置是否在本地播放外部音频源。
该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面：
- 远端及本地的首帧出图与出声速度提升了 10% 到 20%。
- API 的调用耗时和响应耗时缩短了 5% 到 50%。
- SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。
- SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。
该版本为用户提供更灵活的耳返音频调整选项，支持调用 setInEarMonitoringVolume: 将耳返音量设置为原始音量的 4 倍。
- 该版本优化了
setZones:方法的设计，支持将zones参数设置为NULL，表示清除所有隔声区域。 - 自该版本起，在调用
AgoraLocalSpatialAudioKit中的方法之前，无需先取消订阅频道内所有远端用户的音频流。
该版本在 AgoraAudioLocalReason 中增加了如下枚举，用户可通过 rtcEngine:localAudioStateChanged:reason: 回调了解更多本地音频状态改变的原因：
AgoraAudioLocalReasonNoRecordingDevice：无本地音频采集设备。请提示用户在设备的控制面板中检查麦克风是否与设备连接正常，检查麦克风是否正常工作。AgoraAudioLocalReasonNoPlayoutDevice：无本地音频播放设备。请提示用户在设备的控制面板中检查扬声器是否与设备连接正常，检查扬声器是否正常工作。
该版本对以下 5 个视频前处理方法新增了带 souceType 参数的重载方法，支持通过传入 sourceType 来指定视频前处理特效应用的媒体源类型（例如应用在自定义的视频采集媒体源上）：
setBeautyEffectOptions:options:sourceType:setLowlightEnhanceOptions:options:sourceType:setVideoDenoiserOptions:options:sourceType:setColorEnhanceOptions:options:sourceType:enableVirtualBackground:backData:segData:sourceType:
该版本还进行了如下改进：
- 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。
- 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用
setLocalAccessPoint:解析域名时的稳定性。 - 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。
AgoraRtcLocalAudioStats新增earMonitorDelay和aecEstimatedDelay成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。- 在使用声卡进行采集时，支持采集双声道的音频数据。
- 新增
AgoraRtcMediaPlayer:cacheStats:回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。 - 新增
AgoraRtcMediaPlayer:playbackStats:回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过AgoraMediaPlayerPlaybackStats来获取当前音、视频的码率等信息。
该版本修复了以下问题：
- 当同时共享两路屏幕共享视频流时，
rtcEngine:localVideoStats:sourceType:回调上报的captureFrameRate为 0，不符合预期。
AgoraRtcVideoCanvas新增subviewUid和uid成员AgoraAudioLocalReason中新增以下枚举AgoraAudioLocalReasonNoRecordingDeviceAgoraAudioLocalReasonNoPlayoutDevice
enableCustomAudioLocalPlayback:enabled:queryDeviceScoreAgoraMediaSourceType中新增AgoraMediaSourceTypeCustomVideo枚举setBeautyEffectOptions:options:sourceType:setLowlightEnhanceOptions:options:sourceType:setVideoDenoiserOptions:options:sourceType:setColorEnhanceOptions:options:sourceType:enableVirtualBackground:backData:segData:sourceType:AgoraAudioOutputRouting中新增AgoraAudioOutputRoutingBluetoothDeviceA2dp枚举AgoraRtcLocalAudioStats新增earMonitorDelay和aecEstimatedDelay成员selectMultiAudioTrack:publishTrackIndex:AgoraRtcMediaPlayer:cacheStats:AgoraRtcMediaPlayer:playbackStats:
- 以下枚举名中的
Error字段全部修改为Reason：AgoraAudioLocalErrorOKAgoraAudioLocalErrorFailureAgoraAudioLocalErrorDeviceNoPermissionAgoraAudioLocalErrorDeviceBusyAgoraAudioLocalErrorRecordFailureAgoraAudioLocalErrorEncodeFailureAgoraLocalVideoStreamErrorOKAgoraLocalVideoStreamErrorFailureAgoraLocalVideoStreamErrorDeviceNoPermissionAgoraLocalVideoStreamErrorDeviceBusyAgoraLocalVideoStreamErrorCaptureFailureAgoraLocalVideoStreamErrorCodecNotSupportAgoraLocalVideoStreamErrorCaptureNoDeviceFoundAgoraLocalVideoStreamErrorCaptureDeviceDisconnectedAgoraLocalVideoStreamErrorCaptureDeviceInvalidIdAgoraLocalVideoStreamErrorScreenCaptureWindowMinimizedAgoraLocalVideoStreamErrorScreenCaptureWindowClosedAgoraDirectCdnStreamingErrorOKAgoraDirectCdnStreamingErrorFailedAgoraDirectCdnStreamingErrorAudioPublicationAgoraDirectCdnStreamingErrorVideoPublicationAgoraDirectCdnStreamingErrorNetConnectAgoraDirectCdnStreamingErrorBadNameAgoraMediaPlayerErrorNoneAgoraMediaPlayerErrorInvalidArgumentsAgoraMediaPlayerErrorInternalAgoraMediaPlayerErrorNoSourceAgoraMediaPlayerErrorInvalidMediaSourceAgoraMediaPlayerErrorUnknowStreamTypeAgoraMediaPlayerErrorObjNotInitializedAgoraMediaPlayerErrorCodecNotSupportedAgoraMediaPlayerErrorVideoRenderFailedAgoraMediaPlayerErrorInvalidStateAgoraMediaPlayerErrorUrlNotFoundAgoraMediaPlayerErrorInvalidConnectStateAgoraMediaPlayerErrorSrcBufferUnderflowAgoraMediaPlayerErrorInterruptedAgoraMediaPlayerErrorNotSupportedAgoraMediaPlayerErrorTokenExpiredAgoraMediaPlayerErrorUnknownAgoraRtmpStreamingErrorOKAgoraRtmpStreamingErrorInvalidParametersAgoraRtmpStreamingErrorEncryptedStreamNotAllowedAgoraRtmpStreamingErrorConnectionTimeoutAgoraRtmpStreamingErrorInternalServerErrorAgoraRtmpStreamingErrorRtmpServerErrorAgoraRtmpStreamingErrorTooOftenAgoraRtmpStreamingErrorReachLimitAgoraRtmpStreamingErrorNotAuthorizedAgoraRtmpStreamingErrorStreamNotFoundAgoraRtmpStreamingErrorFormatNotSupportedAgoraRtmpStreamingErrorNotBroadcasterAgoraRtmpStreamingErrorTranscodingNoMixStreamAgoraRtmpStreamingErrorNetDownAgoraRtmpStreamingErrorInvalidPrivilegeAgoraRtmpStreamingErrorUnpublishOK
startChannelMediaRelayupdateChannelMediaRelaystartChannelMediaRelayExupdateChannelMediaRelayExdidReceiveChannelMediaRelayEventAgoraChannelMediaRelayEvent
v4.2.6
该版本于 2023 年 11 月 16 日发布。
该版本修复了以下问题：
- 在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。
v4.2.3
该版本于 2023 年 10 月 12 日发布。
为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动：
AgoraContentInspectType中新增AgoraContentInspectTypeImageModeration枚举值，代表使用声网云市场视频审核插件对视频截图并上传。AgoraContentInspectConfig中新增的serverConfig可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请联系技术支持。
此外，该版本还新增了 enableContentInspectEx:config:connection: 方法，支持同时对多条视频流截图并上传。
该版本新增了 isFeatureAvailableOnDevice: 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。
在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。
此外，自该版本起，调用 enableVirtualBackground 和 setBeautyEffectOptions 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 -4 表示该设备不支持开启该功能。
该版本升级了虚拟背景算法，降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。
该版本还进行了如下改进：
- 当调用
setPlaybackSpeed:设置音频文件的播放速度时，传入非法参数后会返回错误码-2，表示方法中设置了无效的参数，需要重新设置参数。 - 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。
该版本修复了以下问题：
- 加入频道偶现的崩溃。
- 本地系统时间不正确时，偶现加入频道失败。
- 调用
playEffect使用相同的soundId播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 - 调用一次
takeSnapshotEx:uid:filePath:获取视频截图会收到多次rtcEngine:snapshotTaken:filePath:width:height:errCode:视频截图结果回调。
enableContentInspectEx:config:connection:AgoraContentInspectType新增AgoraContentInspectTypeImageModerationAgoraContentInspectConfig中新增serverConfig可选参数isFeatureAvailableOnDevice:AgoraFeatureType
v4.2.2
该版本于 2023 年 7 月 27 日发布。
该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见使用通配 Token。
声网 4.x RTC SDK 均支持使用通配 Token。
该版本新增 preloadChannelByToken:channelId:uid: 和 preloadChannelByTokenWithUserAccount:channelId:userAccount: 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。
在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见使用通配 Token。
该版本在 AgoraRtcVideoCanvas 中增加了 backgroundColor 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。
为支持用户选择不同类型的视频源进行本地视频预览，该版本新增 startPreview: 和 stopPreview: 方法。你可以调用 startPreview: 并设置 sourceType 指定待预览的视频源类型；然后调用 stopPreview: 关闭视频预览。
该方法中设置的视频源类型需要跟 setupLocalVideo 中 AgoraRtcVideoCanvas 的视频源类型一致。
该版本在 AgoraRtcChannelMediaOptions 中新增下列成员，支持你发布第三个、第四个摄像头和屏幕采集到的视频流：
publishThirdCameraTrack：发布第三个摄像头采集的视频。publishFourthCameraTrack：发布第四个摄像头采集的视频。publishThirdScreenTrack：发布第三个屏幕采集的视频。publishFourthScreenTrack：发布第四个屏幕采集的视频。
目前 SDK 支持在同一时间、同一 AgoraRtcConnection 中发布多路音频流、一路视频流。
该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。
该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 startOrUpdateChannelMediaRelay: 和 startOrUpdateChannelMediaRelayEx:connection: 时，你可以指定最多 6 个目标频道。
为提升设备编解码能力查询功能，该版本在 CodecCapAgoraVideoCodecCapInfoInfo 中新增 codecLevels 成员。当成功调用 queryCodecCapability 后，可通过 codecLevels 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。
- 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。
- 为帮助用户了解更多类型的远端视频状态改变的原因，
rtcEngine:remoteVideoStateChangedOfUid:state:reason:elapsed:回调中新增了AgoraVideoRemoteReasonCodecNotSupport枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。
该版本修复了以下问题：
- 加入频道后，偶现本地用户听自己及远端的声音时出现杂音。
- 网络异常导致频道连接断开后，频道连接恢复较慢。
- 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。
- 自采集场景下，
setBeautyEffectOptions、setLowlightEnhanceOptions、setVideoDenoiserOptions和setColorEnhanceOptions无法自动加载插件。
startPreview:stopPreview:preloadChannelByToken:channelId:uid:preloadChannelByTokenWithUserAccount:channelId:userAccount:updatePreloadChannelToken:AgoraRtcChannelMediaOptions中增加下列成员：publishThirdCameraTrackpublishFourthCameraTrackpublishThirdScreenTrackpublishFourthScreenTrack
AgoraVideoCodecCapLevelsAgoraVideoCodecCapabilityLevelAgoraRtcVideoCanvas中增加backgroundColor成员CodecCapAgoraVideoCodecCapInfoInfo中增加codecLevels成员AgoraVideoRemoteReason中增加AgoraVideoRemoteReasonCodecNotSupport枚举
v4.2.1
该版本于 2023 年 6 月 21 日发布。
该版本改进了网络传输策略，提升了音视频交互的流畅度。
该版本修复了以下问题：
- SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。
- 发送端调用
setAINSMode:mode:开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。
- 发送端启用屏幕共享功能后，偶现接收端看到共享画面的延迟较高。
v4.2.0
该版本于 2023 年 5 月 24 日发布。
该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。
onCaptureVideoFrame:sourceType:和onPreEncodeVideoFrame:sourceType:回调中新增了sourceType参数，用于表示具体的视频源类型。- 以下回调已删除，请通过
onPreEncodeVideoFrame:sourceType:和onCaptureVideoFrame:sourceType:中的sourceType参数得知视频源类型。onScreenCaptureVideoFrameonPreEncodeScreenVideoFrame
AgoraRtcChannelMediaOptions中的publishCustomAudioTrackEnableAec已删除，请改用publishCustomAudioTrack。AgoraRtcChannelMediaOptions中的成员publishTrancodedVideoTrack变更为publishTranscodedVideoTrack。AgoraRtcChannelMediaOptions中的成员publishCustomAudioSourceId变更为publishCustomAudioTrackId。
- 删除
sharedMediaRecorderWithRtcEngine方法，可通过该版本新增的createMediaRecorder:方法来创建录制对象。 - 删除
startRecording:、stopRecording、setMediaRecorderDelegate:中的connection参数。 - 删除
AgoraMediaRecorder类中的destroy方法，你可直接调用该版本新增的destroyMediaRecorder:方法来销毁录制对象以释放资源。
自该版本起，SDK 新增对第三方虚拟声卡的支持，你可以将第三方虚拟声卡作为 SDK 的音频输入或输出设备。你可以通过 rtcEngine:device:type:stateChanged: 回调来了解当前 SDK 选择的输入输出设备是否为虚拟声卡。
加频道时如果设置 AgoraALD、Soundflower 作为系统的默认输入或输出设备，会造成无声。
didApiCallExecute已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。enableDualStreamMode:和enableDualStreamMode:streamConfig:已废弃，请改用setDualStreamMode:和setDualStreamMode:streamConfig:。startChannelMediaRelay、updateChannelMediaRelay、startChannelMediaRelayEx和updateChannelMediaRelayEx已废弃，请改用startOrUpdateChannelMediaRelay:和startOrUpdateChannelMediaRelayEx:connection:。
该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 setAINSMode:mode: 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。
为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 enableVirtualBackground 方法时，将自定义背景设置为更多类型：
- 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。
- 将背景替换为多种格式的本地视频。
该版本新增 setVideoScenario: 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化：
- 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。
- 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。
该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 mediaRecorder:stateDidChanged:uid:state:reason: 、mediaRecorder:informationDidUpdated:uid:info: 中新增 channelId 和 uid 参数，用于表示录制的音视频流的具体信息，并新增 createMediaRecorder: 方法，用于创建本地或远端的录制对象。
你可以通过如下方法体验本地录制远端音视频功能：
createMediaRecorder:：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。setMediaRecorderDelegate:：设置录制回调对象。startRecording:：开始录制。stopRecording：停止录制。destroyMediaRecorder:：销毁录制对象。
该版本新增本地合图功能，用户可以调用 startLocalVideoTranscoder: 方法，在本地将多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）混合和渲染，以实现自定义布局和效果。通过这项功能，你可以轻松创建个性化的视频显示效果，满足各种场景需求，如远程会议、直播、在线教育场景，同时支持人像画中画等功能。
另外，SDK 还提供了updateLocalTranscoderConfiguration: 方法和 rtcEngine:didLocalVideoTranscoderErrorWithStream:errorCode: 回调。当你在开启本地合图后，可以调用 updateLocalTranscoderConfiguration: 更新合图的配置；当你在开启本地合图或者更新本地合图配置失败时，可通过 rtcEngine:didLocalVideoTranscoderErrorWithStream:errorCode: 回调得知合图失败的原因。
本地合图对 CPU 的消耗较高，声网建议你在性能较高的设备上开启该功能。
在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 getNtpWallTimeInMs 方法获取当前的 NTP (网络时间协议) 时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。
该版本新增了 setLocalVoiceFormant: 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 setLocalVoicePitch: 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。
针对自定义视频和音频采集场景，该版本新增 getCurrentMonotonicTimeInMs 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。
该版本新增 startCameraCapture:config: 和 startScreenCapture:config: 方法，通过多次调用并指定 sourceType 参数可以开启多路摄像头采集的视频流和多路屏幕采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头和显示器的场景。
该版本新增 startOrUpdateChannelMediaRelay: 和 startOrUpdateChannelMediaRelayEx:connection: 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。
为更好地满足音频自采集的场景需求，该版本新增了 createCustomAudioTrack:config: 和 destroyCustomAudioTrack: 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性：
- 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。
- 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。
该版本修复了以下问题：
- 当快速切换身份角色时，观众端听不到声音。
- 接收端默认接收小流几秒后自动变为大流。
- 调用
getdefaultaudiodevice后返回值中的type字段信息错误。 - 屏幕共享偶现共享画面抖动。
startCameraCapture:config:stopCameraCapture:startScreenCapture:config:stopScreenCapture:startOrUpdateChannelMediaRelay:startOrUpdateChannelMediaRelayEx:connection:getNtpWallTimeInMssetVideoScenario:getCurrentMonotonicTimeInMsrtcEngine:didLocalVideoTranscoderErrorWithStream:errorCode:startLocalVideoTranscoder:updateLocalTranscoderConfiguration:setAINSMode:mode:createCustomAudioTrack:config:destroyCustomAudioTrack:createMediaRecorder:destroyMediaRecorder:AudioTrackConfigAgoraRecorderStreamInfoAUDIO_AINS_MODEAgoraAudioTrackTypeAgoraApplicationScenarioTypeAgoraScreenCaptureFrameRateCapabilityAgoraRtcEngineConfig中新增domainLimit和autoRegisterAgoraExtensions属性mediaRecorder:stateDidChanged:uid:state:reason:、mediaRecorder:informationDidUpdated:uid:info:中新增channelId和uid参数onCaptureVideoFrame:sourceType:和onPreEncodeVideoFrame:sourceType:中增加sourceType参数AgoraVirtualBackgroundSourceType中新增AgoraVirtualBackgroundNone和AgoraVirtualBackgroundVideo
enableDualStreamMode:enableDualStreamMode:streamConfig:startChannelMediaRelaystartChannelMediaRelayExupdateChannelMediaRelayupdateChannelMediaRelayExdidReceiveChannelMediaRelayEventAgoraChannelMediaRelayEvent
startPrimaryScreenCapturestartSecondaryScreenCapturestopPrimaryScreenCapturestopSecondaryScreenCapturestartPrimaryCameraCapturestartSecondaryCameraCapturestopPrimaryCameraCapturestopSecondaryCameraCapturedidApiCallExecuteAgoraRtcChannelMediaOptions中的publishCustomAudioTrackEnableAecsharedMediaRecorderWithRtcEngineAgoraMediaRecorder类中的destroystartRecording:、stopRecording、setMediaRecorderDelegate:中删除connection参数onScreenCaptureVideoFrameonPreEncodeScreenVideoFrame
v4.1.1
该版本于 2023 年 2 月 8 日发布。
自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。
如果你想自定义视频编码分辨率，可调用 setVideoEncoderConfiguration: 方法，重新设置视频编码参数配置中的视频编码分辨率。
由于默认分辨率的提升，会影响集合分辨率从而导致费用变更。详见计费策略。
该版本起，setRemoteVideo 更名为 setRemoteVideoSubscriptionOptions:options:；setRemoteVideoEx 更名为 setRemoteVideoSubscriptionOptionsEx:options:connection:。如果你将 SDK 升级至该版本或更高版本，请在调用处同步修改以上两个方法的名称。
该版本新增 enableInstantMediaRendering 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。
该版本新增 startMediaRenderingTracing 和 startMediaRenderingTracingEx: 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo: 回调报告相关事件的信息。
声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo: 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。
自该版本起，SDK 对 onRenderVideoFrame:uid:channelId: 回调进行了优化，在不同的视频处理模式下返回值的意义不同：
- 当视频处理模式为
AgoraVideoFrameProcessModeReadOnly时，返回值无实际含义。 - 当视频处理模式为
AgoraVideoFrameProcessModeReadWrite时，返回YES代表设置 SDK 接收视频帧；返回NO代表设置 SDK 丢弃视频帧。
该版本修复了以下问题：
- 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。
- 把播放器的渲染视图设为
UIViewController的视图后，使用播放器播放视频，视频窗口切到全屏时视频画面会从左下角开始逐渐放大。 - 加入频道后接入外接摄像头，调用
setDevice:deviceId:指定视频采集设备为该外接摄像头，方法未生效。 - 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。
- 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。
enableInstantMediaRenderingstartMediaRenderingTracingstartMediaRenderingTracingEx:rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:AgoraMediaTraceEventAgoraVideoRenderingTracingInfo
setRemoteVideo更名为setRemoteVideoSubscriptionOptions:options:setRemoteVideoEx更名为setRemoteVideoSubscriptionOptionsEx:options:connection:
enableRemoteSuperResolutionAgoraRtcRemoteVideoStats中删除superResolutionType
v4.1.0
该版本于 2022 年 12 月 19 日发布。
该版本新增 setHeadphoneEQParameters:highGain: 方法，用于调节耳机均衡器的低频和高频参数，主要应用于空间音频场景。如果在调用 setHeadphoneEQPreset: 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。
该版本在 AgoraRtcEngineKit 及 AgoraRtcEngineKitEx 中新增 setRemoteVideo 方法，当你调用 setEncodedVideoFrameDelegate 方法为编码后的视频注册视频帧观测器时，SDK 默认订阅编码后的视频帧。如果你想要修改订阅选项，可以调用该新增的方法进行设置。
有关更多注册视频观测器和订阅选项的介绍，详见 API 参考。
自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在移动端和桌面端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。
如果你希望体验该功能，请联系 sales@shengwang.cn。
该版本新增了一系列回调，帮助你更好地了解音视频设备的状态。
onVideoDeviceStateChanged（C++）：当视频设备的状态发生改变时上报。onAudioDeviceStateChanged（C++）：当音频设备的状态发生改变时上报。onAudioDeviceVolumeChanged（C++）：当音频设备或 App 的音量发生改变时上报。
该版本在 AgoraCameraCapturerConfiguration 中增加了 followEncodeDimensionRatio 成员，你可以在使用摄像头采集视频时，通过该成员设置是否跟随 setVideoEncoderConfiguration: 中已经设置的视频宽高比。
该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。
- 新增
muteLocalAudioStreamEx:connection:和muteLocalVideoStreamEx:connection:方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增
muteAllRemoteAudioStreamsEx:connection:和muteAllRemoteVideoStreamsEx:connection:方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增
startRtmpStreamWithoutTranscodingEx:connection:、startRtmpStreamWithTranscodingEx:transcoding:connection:、updateRtmpTranscodingEx:connection:和stopRtmpStreamEx:connection:方法，用于实现多频道场景下的旁路推流。 - 新增
startChannelMediaRelayEx、updateChannelMediaRelayEx、pauseAllChannelMediaRelayEx:、resumeAllChannelMediaRelayEx:和stopChannelMediaRelayEx:方法，用于实现多频道场景下的跨频道媒体流转发。 - 新增
leaveChannelEx:options:leaveChannelBlock:方法，相较于leaveChannelEx:leaveChannelBlock:方法新增了options参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。
一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 AgoraVideoEncoderConfiguration 中新增 advancedVideoOptions 成员，用于视频编码属性的进阶设置：
compressionPreference：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。encodingPreference：视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。
使用声网私有媒体服务器的场景下，为支持用户在调用 setLocalAccessPoint: 方法时的进阶设置，该版本在 AgoraLocalAccessPointConfiguration 中新增 advancedConfig 成员参数，该参数支持如下设置：
logUploadServer：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。
为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 rtcEngine:didClientRoleChanged:newRole:newRoleOptions: 回调中新增 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 的其他窗口。
-
在屏幕共享场景下偶现系统声音音量变小。
-
在屏幕共享场景下，当共享的窗口为半屏模式时，对窗口的描边不正确。
-
在屏幕共享场景下，远端用户看到的画面偶现黑屏、卡顿、崩溃。
-
在屏幕共享场景下，偶现
rtcEngine:networkQuality:txQuality:rxQuality:回调报告频道内指定用户的上下行网络状态不准确。 -
启动并停止音频采集设备测试后，启动音频播放设备测试时必现无声。
-
在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。
-
rtcEngine:didVideoPublishStateChange:sourceType:oldState:newState:elapseSinceLastState:回调报告的视频源类型不准确。 -
调用
getExtensionPropertyWithVendor失败，返回空字符串。 -
当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。
setHeadphoneEQParameters:highGain:setRemoteVideoSubscriptionOptions:options:setRemoteVideoSubscriptionOptionsEx:options:connection:AgoraVideoSubscriptionOptionsmuteLocalAudioStreamEx:connection:muteLocalVideoStreamEx:connection:muteAllRemoteAudioStreamsEx:connection:muteAllRemoteVideoStreamsEx:connection:startRtmpStreamWithoutTranscodingEx:connection:startRtmpStreamWithTranscodingEx:transcoding:connection:updateRtmpTranscodingEx:connection:stopRtmpStreamEx:connection:startChannelMediaRelayExupdateChannelMediaRelayExpauseAllChannelMediaRelayEx:resumeAllChannelMediaRelayEx:stopChannelMediaRelayEx:AgoraCameraCapturerConfiguration中增加followEncodeDimensionRatioAgoraRtcLocalVideoStats中增加hwEncoderAcceleratingleaveChannelEx:options:leaveChannelBlock:AgoraVideoEncoderConfiguration中增加advancedVideoOptions成员AgoraLocalAccessPointConfiguration中增加advancedConfig成员rtcEngine:didClientRoleChanged:newRole:newRoleOptions:中增加newRoleOptionsadjustUserPlaybackSignalVolumeEx:volume:connection:enableAudioVolumeIndicationEx:smooth:reportVad:connection:
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:sourceType:streamConfig:和enableDualStreamModeEx:sourceType:streamConfig:connection:中的sourceType参数以及enableDualStreamMode:streamConfig:方法，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。
该本版新增耳返功能。你可以调用 enableInEarMonitoring 开启耳返功能。
成功开启耳返功能后，你可以调用 setAudioFrameDelegate: 注册音频观测器，SDK 会触发 onEarMonitoringAudioFrame: 回调报告耳返原始音频数据。你可以使用自己的音效处理模块对耳返音频数据进行前处理，实现自定义音效，声网推荐你在如下两种方式中选其一来设置耳返音频数据格式：
- 调用
setEarMonitoringAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:方法设置耳返音频数据格式，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: 或 setDualStreamMode:streamConfig: 方法，将 mode 参数设置为 AgoraDisableSimulcastStream （始终不发送小流）或 AgoraEnableSimulcastStream （始终发送小流）。
该版本新增了如下适用于空间音频场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。
- 隔声区域：你可以通过调用
setZones:设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用setPlayerAttenuation:playerId:forceSet:和setRemoteAudioAttenuation:userId:forceSet:方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖setZones:中的声音衰减系数。 - 多普勒音效：你可以通过设置
SpatialAudioParams中的enable_doppler参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下（比如赛车游戏场景），接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用
setHeadphoneEQPreset:方法使用预设的耳机均衡效果，以改善耳机的听感。
该版本优化了 videoSizeChangedOfUid 的触发逻辑，当单独调用 startPreview 时，也可触发该回调并上报本地视频大小发生改变。
该版本修复了以下问题：
-
通过摄像头采集视频时，如果在
AgoraCameraCapturerConfiguration中设置的视频宽高比例和在setVideoEncoderConfiguration:中设置的不一致，导致本地视频预览的画面比例未按照后者的设置呈现。 -
在频道内调用
setVideoEncoderConfigurationEx:connection:将视频的分辨率调高时，偶现失效。 -
使用媒体播放器播放视频，先调用
play再调用pause暂停播放后，调用seek指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用resume恢复播放后，偶现视频画面出现快进。
enableInEarMonitoringsetEarMonitoringAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:onEarMonitoringAudioFrame:setInEarMonitoringVolume:getEarMonitoringAudioParamsgetNetworkTypeAgoraRtcChannelMediaOptions中新增isAudioFilterablesetDualStreamMode:setDualStreamMode:streamConfig:setDualStreamModeEx:streamConfig:connection:AgoraSimulcastStreamModesetZones:setPlayerAttenuation:playerId:forceSet:setRemoteAudioAttenuation:userId:forceSet:muteRemoteAudioStream:mute:SpatialAudioParamssetHeadphoneEQPreset:AgoraHeadphoneEQPreset
enableDualStreamMode:sourceType:streamConfig:enableDualStreamModeEx:sourceType:streamConfig:connection:
startEchoTestWithInterval:interval:successBlock:
enableDualStreamMode:streamConfig:
v4.0.0
该版本于 2022 年 8 月 3 日发布。
v4.0.0 SDK 对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见迁移指南。
- 多频道
- 媒体流发布控制
- 自定义视频采集与渲染（Media IO 方式）
- 警告码
该版本通过设置 AgoraRtcEngineKitEx 和 AgoraRtcChannelMediaOptions 实现一个 AgoraRtcEngineKit 实例同时采集多组音视频流并发布到远端：
调用 joinChannelByToken 加入首个频道后，多次调用 joinChannelExByToken 加入多个频道，通过不同的用户 ID (localUid) 和 AgoraRtcChannelMediaOptions 设置发布指定的流到不同的频道。
支持通过设置 AgoraRtcChannelMediaOptions 中的 publishSecondaryCameraTrack 和 publishSecondaryScreenTrack 同时发布多路摄像头采集或者屏幕共享的视频流。
同时，该版本支持通过 createCustomVideoTrack 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流：
-
创建自采集视频轨道：调用
createCustomVideoTrack方法创建一个自定义视频轨道，并获得视频轨道 ID。 -
设置频道中待发布的自采集视频轨道：在每个频道的
AgoraRtcChannelMediaOptions中，将customVideoTrackId参数设置为你想要发布的视频轨道 ID，并将publishCustomVideoTrack设置为YES。 -
推送外部视频源：调用
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:axisForward:axisRight:axisUp:和updateRemotePosition:positionInfo:更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音频。 -
该方案通过 SDK 计算媒体播放器的空间坐标。你需要在
AgoraCloudSpatialAudioKit或AgoraLocalSpatialAudioKit类中分别调用updateSelfPosition:axisForward:axisRight:axisUp:和updatePlayerPositionInfo:positionInfo:更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音频。
该版本为实时合唱赋予了如下能力：
- 支持两人及两人以上合唱。
- 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。
- 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。
该版本在 AgoraAudioScenario 中新增 AgoraAudioScenarioChorus 枚举设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。
为在声网 SDK 的基础上增强实时音视频互动性，该版本支持声网云市场插件的一站式解决方案：
- 方便集成：只需执行简单统一的 API 即可实现模块化功能的集成，将实时互动模块集成效率提高约 95%。
- 可扩展性设计：模块化和可扩展的 SDK 设计风格赋予了声网 SDK 良好的可扩展性，更有利于开发者基于声网云市场插件生态快速搭建好用的实时互动应用。
- 打造生态系统：可容纳众多开发者的实时音视频 App 社区，提供多种扩展组合。添加并开启云市场插件后，开发者可以实现更为丰富的实时音视频互动功能。
- 助力服务商：支持服务商将技术产品以插件的形式与声网 SDK 做技术上的融合，在声网云市场中展示并售卖，与声网一起共建开发者的实时互动生态系统。如何开发和发布插件详见云市场-开发插件。
为满足各类业务场景对频道管理的需求，该版本在 AgoraRtcChannelMediaOptions 中新增了如下功能：
- 设置或切换多种音视频源的发布
- 设置或切换频道场景、用户角色
- 设置或切换订阅视频的大小流类型
- 控制音频发布时延
在调用 joinChannelByToken 或 joinChannelExByToken 时设置 AgoraRtcChannelMediaOptions，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 updateChannelWithMediaOptions: 随时更新 AgoraRtcChannelMediaOptions 中的设置，例如，切换发布的音视频源。
该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享：
- 在加入频道前调用
startScreenCaptureByDisplayId:regionRect:captureParams:，然后调用joinChannelByToken:channelId:uid:mediaOptions:joinSuccess:加入频道并设置publishScreenTrack或publishSecondaryScreenTrack为YES，即可开始屏幕共享。 - 在加入频道后调用
startScreenCaptureByDisplayId:regionRect:captureParams:，然后调用updateChannelWithMediaOptions:设置publishScreenTrack或publishSecondaryScreenTrack为YES，即可开始屏幕共享。
该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通 AgoraRtcEngineKitEx 类下的同名方法来实现该功能。
setSubscribeAudioBlacklist：设置音频订阅黑名单。setSubscribeAudioWhitelist：设置音频订阅白名单。setSubscribeVideoBlacklist：设置视频订阅黑名单。setSubscribeVideoWhitelist：设置视频订阅白名单。
如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。
为方便用户灵活修改音频场景，该版本新增 setAudioScenario: 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (AgoraAudioScenarioDefault) 切换为高音质场景 (AgoraAudioScenarioGameStreaming)，你可以调用该方法。
该本版新增 setLocalAccessPoint: 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。
该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 enableVideoImageSource:options: 来开启该功能，并通过 options 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。
该版本通过 leaveChannel 和 joinChannelByToken 切换频道即可实现和 v3.7.0 中 switchChannelByToken 一样的切换速度，无需额外调用 switchChannelByToken 方法。
该版本新增支持推送 I422 格式的外部视频帧，你可以通过 pushExternalVideoFrame 方法将 I422 格式的外部视频帧推送至 SDK。
该版本在 rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: 的 AgoraRtcAudioVolumeInfo 中新增 voicePitch 参数。你可以通过 voicePitch 获取本地用户的人声音调，从而实现唱歌评分等业务功能。
该版本优化了 startPreview 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 startPreview 方法来开启视频预览，无调用时序要求。
你可以通过 setRemoteDefaultVideoStreamType: 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。