发版说明
鸿蒙 OS 音频路由切换行为问题
使用鸿蒙 OS 的设备播放音乐时，先插入有线耳机，再连接蓝牙耳机，声音从有线耳机而不是蓝牙耳机播放。
Android 14 系统屏幕共享问题 (Android)
部分系统版本为 Android 14 的机型（例如一加 11）在 targetSdkVersion 为 34 时，会出现屏幕共享不可用问题，例如：共享画面的一半为黑屏。为规避该问题，声网建议你将 targetSdkVersion 设置为 34 以下，但仍可能会出现切换横竖屏模式时屏幕共享进程中断的问题，此时设备上会弹出一个询问是否开始录制屏幕的窗口，确认后即可重新开始屏幕共享。
AirPods Pro 蓝牙连接问题 (iOS)
由于 AirPods Pro 不支持在通话音量模式下使用 A2DP 协议，可能会导致该设备在该模式下无法成功连接。
v4.4.0
该版本于 2024 年 8 月 29 日发布。
该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。
-
为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的
ExtensionContext了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。原有回调 现有回调 onExtensionEventonExtensionEventWithContextonExtensionStartedonExtensionStartedWithContextonExtensionStoppedonExtensionStoppedWithContextonExtensionErroronExtensionErrorWithContext -
该版本修改了
ExternalVideoFrame中的以下成员名称：d3d11_texture_2d更名为d3d11Texture2d。texture_slice_index更名为textureSliceIndex。metadata_buffer更名为metadataBuffer。metadata_size更名为metadataSize。
该版本新增 Alpha 透明特效功能，支持在 SDK 采集和自定义采集视频的场景下，在发送端发布视频帧的 Alpha 通道、在接收端对 Alpha 通道进行渲染处理，实现透明礼物特效、接收端自定义主播背景等：
VideoFrame和ExternalVideoFrame中新增alphaBuffer：设置 Alpha 通道数据。ExternalVideoFrame中新增fillAlphaBuffer：对于 BGRA 或 RGBA 格式的视频数据，设置是否自动提取 Alpha 通道数据并填入到alphaBuffer中。VideoFrame和ExternalVideoFrame中新增alphaStitchMode：设置alphaBuffer和视频帧拼接的相对位置。
另外，AdvanceOptions 中新增成员 encodeAlpha，用于设置是否将 Alpha 信息编码并发送到远端。SDK 默认不对 Alpha 信息进行编码发送；如果需要对 Alpha 信息编码发送至远端（例如开启了虚拟背景功能），请显式调用 setVideoEncoderConfiguration 设置视频编码属性，并将 encodeAlpha 设置为 true。
该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 enableVoiceAITuner 方法并传入 VoiceAiTunerType 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。
该版本在 VideoApplicationScenarioType 类下新增枚举 ApplicationScenario1v1（1v1 视频通话）。你可以调用 setVideoScenario 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。
-
该版本新增
setPlayMode方法，用于设置音乐资源的播放模式。在在线 K 歌房等场景下，你可以根据需求启用伴唱、原唱或导唱模式。 -
该版本新增
destroyMusicPlayer方法，用于销毁音乐播放器并释放相应的资源。
该版本新增自适应硬解支持，改进了低端机的渲染流畅性，有效降低系统负载。
为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。
该版本还进行了如下改进：
- 优化了传输策略，调用
enableInstantMediaRendering不再对传输链路的安全性产生影响。 - 该版本在
Metadata中新增channelId参数，用于获取发送 Metadata 的源频道名称。 - 废弃了
ClientRoleChangeFailedReason中的冗余枚举值ClientRoleChangeFailedRequestTimeOut、ClientRoleChangeFailedConnectionFailed。
该版本修复了以下问题：
- 在实时互动过程中，当多个远端同时加入频道时 App 偶现崩溃。(iOS)
- App 切后台一段时间、然后返回前台时，远端视频画面偶现卡住或花屏。(iOS)
- 发送端调用
startDirectCdnStreaming开始直接向 CDN 推流后，频繁开关或切换网络，偶现接收端黑屏但发送端未收到推流失败回调。(iOS) - 调用
pushAudioFrame推送外部音频数据，外部音频渲染的采样率如果不是 SDK 推荐的值时，比如 22050 Hz 和 11025 Hz，声音播放失败。
v4.3.2
该版本于 2024 年 6 月 6 日发布。
该版本修改了播放版权音乐的行为，当调用 IMusicPlayer 中的 play 方法播放版权音乐媒体文件时，存在以下行为变更：
- v4.3.2 以前版本：SDK 默认播放当前音频文件的第一个音轨。
- v4.3.2：SDK 默认播放伴奏。
提升了 setRemoteSubscribeFallbackOption 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 setRemoteSubscribeFallbackOption 动态切换弱网环境下的音视频流回退选项。
该版本修复了以下问题：
- App 长时间切后台再返回前台时，远端视频画面卡住或花屏。(iOS)
- 部分 iPad 设备上的本地预览画面旋转 90°，不符合预期。(iOS)
- 音视频互动过程中偶现视频流畅度不佳。
- 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。
- 首次安装 App 或重启系统后，打开 App 并开启屏幕共享时出现崩溃。(Android)
- 接听系统电话时加入频道，挂断电话后，本地音频采集失败，远端用户听不到声音。(Android)
- 在部分机型（例如：红米 Note8）上进行互动的过程中接听系统来电并挂断后，本地播放媒体文件无声、听远端无声。(Android)
- 远端用户离开频道时偶现崩溃。
- 调用 播放音乐文件，音乐文件播放结束后偶现无法触发
onAudioMixingStateChanged(AudioMixingStateStopped,AudioMixingReasonAllLoopsCompleted) 回调报告音乐文件播放完毕。(iOS) - 调用
playEffect播放时长不足 1 秒的音效文件并设置不循环播放（loopCount为 0 ）时，出现无声。(iOS) - 使用媒体播放器播放视频，暂停播放后恢复播放，偶现短暂无声。(iOS)
v4.3.1
该版本于 2024 年 5 月 9 日发布。
为满足 Apple 对于 App 发布的安全合规要求，SDK 自该版本起新增隐私清单文件 PrivacyInfo.xcprivacy，其中包含 SDK 中需要访问或使用用户数据的 API 调用说明和 SDK 采集的数据类型说明。
注： 如果你需要将集成 v4.3.1 之前的 SDK 版本的 App 发布到苹果应用商店，则需要在 Xcode 工程中手动添加 PrivacyInfo.xcprivacy 文件。详见如何在 App 中增加隐私清单？
为提升在线会议、秀场、在线教育等场景中的主播演讲效果，该版本新增 enableCameraCenterStage 方法开启人像锁定功能。该功能可确保主播无论移动与否，始终位于画面中心，以取得良好的演讲效果。
在开启人像锁定前，建议你先调用 isCameraCenterStageSupported 查询当前设备性能是否支持该功能。支持的设备清单可参考 API 文档。
为改善在移动拍摄、暗光环境拍摄、手持拍摄等场景下的视频画面稳定性，该版本新增摄像头防抖功能。你可以调用 setCameraStabilizationMode 开启该功能并设置适合的防抖模式，以获得更加稳定、清晰的视频画面。
为了让用户捕捉到更宽阔的视野和更完整的画面内容，该版本新增了对广角和超广角摄像头的支持。你可以先调用 queryCameraFocalLengthCapability 查询设备支持的焦距能力，然后调用 setCameraCapturerConfiguration 并将 cameraFocalLengthType 设置为支持的焦距类型，包括广角、超广角等。
该版本针对 Android 摄像头采集新增以下功能：
-
支持第三个和第四个摄像头视频流的采集和发布。
VideoSourceType中的VideoSourceCameraThird(11) 和VideoSourceCameraFourth(12) 枚举新增对 Android 的支持，分别用于指定视频源为第三个和第四个摄像头。此项改动允许你在调用startCameraCapture开启摄像头采集时，指定最多 4 路摄像头采集的视频流。ChannelMediaOptions中的publishThirdCameraTrack和publishFourthCameraTrack成员新增对 Android 的支持。调用joinChannel加入频道时，将这两个成员参数设置为true即可在频道内发布第三个和第四个摄像头采集的视频流。
-
支持通过摄像头 ID 指定摄像头。
在
CameraCapturerConfiguration中新增cameraId成员。对于多摄像头的设备，cameraDirection无法识别或访问全部可用摄像头。这种情况下，你通过系统 API 获取摄像头 ID，再调用startCameraCapture并传入cameraId指定摄像头。
该版本在 EncryptionConfig 中新增 datastreamEncryptionEnabled 成员用于启用数据流加密。你可以在调用 enableEncryption 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 EncryptionErrorDatastreamDecryptionFailure 和 EncryptionErrorDatastreamEncryptionFailure 枚举得知。
该版本新增视频小流的自适应配置功能，当你调用 setDualStreamMode 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示：
- 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。
- 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。
- 新增
enableEncryptionEx方法，用于多频道场景下开启媒体流或数据流加密。 - 新增
setAudioMixingPlaybackSpeed方法，用于设置音乐文件的播放速度。 - 新增
getCallIdEx方法，用于多频道场景下获取通话 ID。
为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法：
- 支持识别任意纯色背景，不再局限于绿幕。
- 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。
- 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。
该版本在 EarMonitoringFilterType 中新增 EarMonitoringFilterReusePostProcessingFilter(1 << 15) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。
该版本还进行了如下改进：
- 优化了非屏幕共享场景的视频编解码策略，节省系统性能开销。(iOS)
- 提升了本地合图功能的性能和稳定性，并降低了该功能对 CPU 的占用率。(Android)
- 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。
- 在
AudioEffectPreset中新增RoomAcousticsChorus（合唱音效），可使人声在合唱场景下更具空间立体感。 - 在
RemoteAudioStats中新增e2eDelay，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。
该版本修复了以下问题：
- 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。
- 主播使用部分型号设备在扬声器下进行音视频互动，之后切换 App 进程到后台再切回前台，偶现本地音频采集失败，远端用户听不到主播的声音。(Android)
- 在 Android 8.0 系统的设备上，启用屏幕共享功能时 App 偶现崩溃。(Android)
- 使用摄像头采集本地视频场景下，在 App 切后台时已调用
disableVideo或 关闭视频采集，但将 App 再切回前台时，摄像头采集被打开，不符合预期。(Android) - 当发送端用户的网络环境恶化（例如弱网）时，接收端偶现视频流畅度降低、卡顿增加。
enableCameraCenterStage(iOS)isCameraCenterStageSupported(iOS)setCameraStabilizationMode(iOS)CameraStabilizationMode(iOS)EncryptionConfig中新增datastreamEncryptionEnabledEncryptionErrorType中新增如下枚举：EncryptionErrorDatastreamDecryptionFailureEncryptionErrorDatastreamEncryptionFailure
RemoteAudioStats新增e2eDelayErrorCodeType新增ErrDatastreamDecryptionFailedAudioEffectPreset新增RoomAcousticsChorusgetCallIdExenableEncryptionExsetAudioMixingPlaybackSpeedqueryCameraFocalLengthCapabilityFocalLengthInfoCameraFocalLengthTypeCameraCapturerConfiguration新增成员cameraFocalLengthTypeCameraCapturerConfiguration新增成员cameraId(Android)EarMonitoringFilterType新增枚举EarMonitoringFilterBuiltInAudioFilters(1 << 15)
v4.3.0-build.1
该版本于 2024 年 3 月 18 日发布。
该版本修复了如下问题：
在未调用 engine.unregisterEventHandler 删除已添加的所有回调事件时，直接调用 engine.release 销毁引擎可能导致 App 崩溃。(Android)
v4.3.0
该版本于 2024 年 2 月 28 日发布。
该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。
为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。
| 回调 | 原有参数名 | 现有参数名 |
|---|---|---|
onLocalAudioStateChanged | error | reason |
onLocalVideoStateChanged | error | reason |
onDirectCdnStreamingStateChanged | error | reason |
onMusicChartsResult | errorCode | reason |
onPreLoadEvent |
|
|
onMusicCollectionResult | errorCode | reason |
onLyricResult | errorCode | reason |
onSongSimpleInfoResult | errorCode | reason |
onRtmpStreamingStateChanged | errCode | reason |
| 原有枚举类 | 现有枚举类 |
|---|---|
LocalAudioStreamError | LocalAudioStreamReason |
LocalVideoStreamError | LocalVideoStreamReason |
DirectCdnStreamingError | DirectCdnStreamingReason |
MediaPlayerError | MediaPlayerReason |
RtmpStreamPublishErrorType | RtmpStreamPublishReason |
MusicContentCenterStatusCode | MusicContentCenterStateReason |
有关具体枚举的改名详见 API 变更。
为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项：
| 已删除的方法和回调 | 替代的方法和回调 |
|---|---|
| startOrUpdateChannelMediaRelay |
| startOrUpdateChannelMediaRelayEx |
onChannelMediaRelayEvent | onChannelMediaRelayStateChanged |
该版本起，AudioRoute 中的RouteBluetooth 更名为 RouteBluetoothDeviceHFP，表示音频路由为使用 HFP 协议的蓝牙设备，新增 RouteBluetoothDeviceA2DP(10) 表示音频路由为使用 A2DP 协议的蓝牙设备。
该版本对 LocalVideoStreamReason 枚举类中的枚举进行了如下修改：
LocalVideoStreamErrorCodecNotSupport的枚举名变更为LocalVideoStreamReasonCodecNotSupport。
出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案：
- 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。
- 如有其他特殊需求，请联系技术支持并附上对应的加密日志。
为支持接收端自定义多路合图流的布局，该版本新增了 onTranscodedStreamLayoutInfo 回调。当接收端收到合图服务器发送的频道内合图视频流时，该回调会被触发，上报合图视频流的布局信息、以及合图流中每一路子视频流的布局信息。接收端可以在调用 方法时，为合图视频流中的子视频流（通过 subviewUid 区分）设置单独的 view 进行渲染，从而达到自定义视频布局的效果。
当合图视频流中的子视频流布局发生变化时，该回调也会被触发，实时上报最新的布局信息。
通过该特性，接收端可以灵活调整本地的视图布局。当在多人视频场景下应用时，接收端只需接收并解码一路合图视频流，可以有效降低接收端解码多路视频时的 CPU 占用率和网络带宽。
关于该特性在多主播场景下的最佳实践，详见多主播场景下的视频体验优化。
该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下：
- 创建第一个视图，在
VideoCanvas中设置position参数为PositionPostCapturerOrigin（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。 - 创建第二个视图，在
VideoCanvas中设置position参数为PositionPostCapturer，此处观测到的视频具备视频前处理的效果。 - 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。
该版本新增 queryDeviceScore 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请联系技术支持。
该版本新增 selectMultiAudioTrack 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 openWithMediaSource 打开媒体文件，并通过 MediaSource 中新增的 enableMultiAudioTrack 成员来开启音轨控制。
该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。
setRemoteSubscribeFallbackOption：设置弱网环境下订阅的音视频流回退选项。onRemoteSubscribeFallbackToAudioOnly：订阅流已回退为音频流或恢复为音视频流回调。setPlayerOptionInInt和setPlayerOptionInString：设置媒体播放器选项，用于提供技术预览或特别定制功能。enableCustomAudioLocalPlayback：设置是否在本地播放外部音频源。
该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面：
- 远端及本地的首帧出图与出声速度均有明显提升。
- API 的调用耗时和响应耗时缩短 50% 以上。
- SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。
- SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。
该版本为用户提供更灵活的耳返音频调整选项，支持调用 setInEarMonitoringVolume 将耳返音量设置为原始音量的 4 倍。
- 该版本优化了
setZones方法的设计，支持将zones参数设置为NULL，表示清除所有隔声区域。 - 自该版本起，在调用
ILocalSpatialAudioEngine中的方法之前，无需先取消订阅频道内所有远端用户的音频流。
该版本还进行了如下改进：
- 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。
- 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用
setLocalAccessPoint解析域名时的稳定性。 - 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。
LocalAudioStats新增earMonitorDelay和aecEstimatedDelay成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。- 新增
onPlayerCacheStats回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。 - 新增
onPlayerPlaybackStats回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过PlayerPlaybackStats来获取当前音、视频的码率等信息。 MusicContentCenterStateReason中新增状态码kMusicContentCenterReasonHttpInternalError表示 HTTP 内部发生错误，请稍后重试。
该版本修复了以下问题：
- 当同时共享两路屏幕共享视频流时，
onLocalVideoStats回调上报的captureFrameRate为 0，不符合预期。
onTranscodedStreamLayoutInfoVideoLayoutVideoCanvas新增subviewUid和uid成员enableCustomAudioLocalPlaybackqueryDeviceScoreMediaSourceType中新增CustomVideoSource枚举AudioRoute中新增RouteBluetoothDeviceA2DP枚举LocalAudioStats新增earMonitorDelay和aecEstimatedDelay成员selectMultiAudioTrackonPlayerCacheStatsonPlayerPlaybackStatsPlayerPlaybackStatsMusicContentCenterStateReason中新增kMusicContentCenterReasonHttpInternalError
RouteBluetooth枚举名变更为RouteBluetoothDeviceHFP- 以下枚举名中的
error字段全部修改为reason：LocalAudioStreamErrorOkLocalAudioStreamErrorFailureLocalAudioStreamErrorDeviceNoPermissionLocalAudioStreamErrorDeviceBusyLocalAudioStreamErrorRecordFailureLocalAudioStreamErrorEncodeFailureLocalVideoStreamErrorOkLocalVideoStreamErrorFailureLocalVideoStreamErrorDeviceNoPermissionLocalVideoStreamErrorDeviceBusyLocalVideoStreamErrorCaptureFailureLocalVideoStreamErrorCodecNotSupportLocalVideoStreamErrorCaptureInbackground(iOS)LocalVideoStreamErrorCaptureMultipleForegroundApps(iOS)LocalVideoStreamErrorDeviceNotFoundLocalVideoStreamErrorDeviceDisconnectedLocalVideoStreamErrorDeviceInvalidIdDirectCdnStreamingErrorOkDirectCdnStreamingErrorFailedDirectCdnStreamingErrorAudioPublicationDirectCdnStreamingErrorVideoPublicationDirectCdnStreamingErrorNetConnectDirectCdnStreamingErrorBadNamePlayerErrorNonePlayerErrorInvalidArgumentsPlayerErrorInternalPlayerErrorNoResourcePlayerErrorInvalidMediaSourcePlayerErrorUnknownStreamTypePlayerErrorObjNotInitializedPlayerErrorCodecNotSupportedPlayerErrorVideoRenderFailedPlayerErrorInvalidStatePlayerErrorUrlNotFoundPlayerErrorInvalidConnectionStatePlayerErrorSrcBufferUnderflowPlayerErrorInterruptedPlayerErrorNotSupportedPlayerErrorTokenExpiredPlayerErrorUnknownRtmpStreamPublishErrorOkRtmpStreamPublishErrorInvalidArgumentRtmpStreamPublishErrorEncryptedStreamNotAllowedRtmpStreamPublishErrorConnectionTimeoutRtmpStreamPublishErrorInternalServerErrorRtmpStreamPublishErrorRtmpServerErrorRtmpStreamPublishErrorTooOftenRtmpStreamPublishErrorReachLimitRtmpStreamPublishErrorNotAuthorizedRtmpStreamPublishErrorStreamNotFoundRtmpStreamPublishErrorFormatNotSupportedRtmpStreamPublishErrorNotBroadcasterRtmpStreamPublishErrorTranscodingNoMixStreamRtmpStreamPublishErrorNetDownRtmpStreamPublishErrorInvalidPrivilegeRtmpStreamUnpublishErrorOk
MusicContentCenterStatusCode修改为MusicContentCenterStateReason，其中的枚举名的StatusErr字段全部修改为Reason：kMusicContentCenterStatusErrGatewaykMusicContentCenterStatusErrPermissionAndResourcekMusicContentCenterStatusErrInternalDataParsekMusicContentCenterStatusErrMusicLoadingkMusicContentCenterStatusErrMusicDecryption
KMusicContentCenterStatusErr修改为KMusicContentCenterReasonError
startChannelMediaRelayupdateChannelMediaRelaystartChannelMediaRelayExupdateChannelMediaRelayExonChannelMediaRelayEventChannelMediaRelayEvent
v4.2.6
该版本于 2023 年 11 月 21 日发布。
该版本修复了在使用 Android 14 系统版本时可能出现的问题：
- 在屏幕共享过程中切换横竖屏模式导致当前屏幕共享进程中断，需要在弹出窗口中点击确认录制屏幕才可重新开始屏幕共享。(Android)
- 在集成 SDK 时，如果将 Android
targetSdkVersion设置为 34，导致屏幕共享不可用甚至 App 崩溃。(Android) - 先调用
startScreenCapture但不共享视频（设置captureVideo为false）、后调用updateScreenCaptureParameters共享视频（设置captureVideo为true）时，接收端看到的屏幕共享画面冻结。(Android) - 采用横屏模式进行屏幕共享时，观众端看到的共享画面被拆分成两部分：一侧的画面被压缩；另一侧为黑屏。(Android)
该版本还修复了以下问题：
- 使用 iOS 16 版本或以上设备在加入频道前连接了蓝牙耳机，在加入频道后的音频路由不符合预期：音频从扬声器播放、而非蓝牙耳机。(iOS)
- 在直播场景下，观众端看到的画面偶现变形。(Android)
- 在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。
v4.2.5
该版本于 2023 年 10 月 30 日发布。
该版本修复了如下问题：
因 package.json 中 types 字段定义的路径有误，导致集成 SDK 到 Typescript 项目时报错：Could not find a declaration file for module 'react-native-agora'。
v4.2.4
该版本于 2023 年 10 月 24 日发布。
该版本修复了如下问题：
AgoraRtcWrapper 中的 CFBundleShortVersionString 版本号错误，导致 App 无法被提交至 App Store。(iOS)
v4.2.3
该版本于 2023 年 10 月 17 日发布。
-
该版本删除了
IMusicContentCenter类下的preload方法中的jsonOption参数，请在升级到该版本后更新 App 代码。 -
该版本优化了 SDK 采集和自定义视频采集场景下 Texture Buffer 的管理方式，有效消除丢帧和崩溃隐患。自该版本起，TextureBuffer 类型的纹理格式不再包括 OES 格式，仅为 RGB 格式。你需要在处理视频数据时增加对 I420、RGB 纹理格式的适配。(Android)
为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动：
ContentInspectType中新增ContentInspectImageModeration枚举值，代表使用声网云市场视频审核插件对视频截图并上传。ContentInspectConfig中新增的serverConfig可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请联系技术支持。
此外，该版本还新增了 enableContentInspectEx 方法，支持同时对多条视频流截图并上传。
该版本新增了 isFeatureAvailableOnDevice 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。
在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。
此外，自该版本起，调用 enableVirtualBackground 和 setBeautyEffectOptions 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 -4: ErrNotSupported 表示该设备不支持开启该功能。
该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见使用通配 Token。
声网 4.x RTC SDK 均支持使用通配 Token。
该版本新增 preloadChannel 和 preloadChannelWithUserAccount 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。
在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见使用通配 Token。
该版本在 VideoCanvas 中增加了 backgroundColor 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。
该版本新增 getInternalSongCode 方法，如果你仅需要播放某一音乐资源的副歌片段，在播放前你需要调用该方法来为该副歌片段创建一个内部歌曲编号，作为该资源的唯一标识。你可以查看在线 K 歌房文档了解更多 K 歌场景方案。
该版本从以下几个方面提升了摄像头采集效果：
-
支持摄像头采集曝光调节
新增
isCameraExposureSupported和setCameraExposureFactor方法，用于查询当前设备是否支持曝光调节和设置摄像头的曝光增益。 -
优化默认摄像头选择 (iOS)
自该版本起，SDK 的默认摄像头选择对齐 iOS 系统相机行为。如果设备拥有多个后置摄像头，则在视频采集时可以获得更好的拍摄视野、变焦能力、低光性能和深度感应，从而提高视频采集的质量。
该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。
此外，该版本还降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。
该版本优化了屏幕共享场景下的视频编码配置。当用户自定义视频的 width 和 height 属性时，SDK 会在保持视频与屏幕的宽高比一致的前提下，对实际的编码分辨率进行向下取整，确保最终编码分辨率不超过用户自定义的编码分辨率，从而提升了对屏幕共享流的计费准确性。
该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 startOrUpdateChannelMediaRelay 和 startOrUpdateChannelMediaRelayEx 时，你可以指定最多 6 个目标频道。
为提升设备编解码能力查询功能，该版本在 CodecCapInfo 中新增 codecLevels 成员。当成功调用 queryCodecCapability 后，可通过 codecLevels 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。
该版本还进行了如下改进：
- 当调用
setPlaybackSpeed设置音频文件的播放速度时，传入非法参数后会返回错误码-2，表示方法中设置了无效的参数，需要重新设置参数。 - 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。
- 为了提升多种音频路由之间的切换体验，该版本新增了
setRouteInCommunicationMode方法，用于在通话音量模式 (MODE_IN_COMMUNICATION) 下，将音频路由从蓝牙耳机切换为听筒、有线耳机或扬声器。 (Android) - 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。
- 为帮助用户了解更多类型的远端视频状态改变的原因，
onRemoteVideoStateChanged回调中新增了remoteVideoStateReasonCodecNotSupport枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。 - 版权音乐新增
getSongSimpleInfo方法，可用于获取某一指定歌曲的详细信息，你可以通过触发的onSongSimpleInfoResult回调来获取歌曲信息。
该版本修复了以下问题：
- 本地系统时间不正确时，偶现加入频道失败。
- 调用
playEffect使用相同的soundId播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 - 主播调用
startAudioMixing播放音乐文件时，偶现主播本地无法听见音乐，远端用户可以正常听见。(Android) - 合唱场景下，调用
preload加载音乐，偶现加载失败。 - 在特定机型上开启 AI 降噪偶现崩溃。(Android)
- 当本地系统时间不准确时，歌曲榜单加载失败。
- 调用一次
takeSnapshotEx获取视频截图会收到多次onSnapshotTaken视频截图结果回调。 - 在仅调用
joinChannelEx加入的频道中，调用setEnableSpeakerphone无法将音频路由从扬声器切换至听筒。(Android) - 网络异常导致频道连接断开后，频道连接恢复较慢。
- 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。
- 自采集场景下，
setBeautyEffectOptions、setLowlightEnhanceOptions、setVideoDenoiserOptions和setColorEnhanceOptions无法自动加载插件。
enableContentInspectExContentInspectType新增ContentInspectImageModerationContentInspectConfig中新增serverConfig可选参数isFeatureAvailableOnDeviceFeatureTypesetCameraExposureFactorisCameraExposureSupportedpreloadChannelpreloadChannelWithUserAccountupdatePreloadChannelTokengetSongSimpleInfoonSongSimpleInfoResultgetInternalSongCodeonLyricResult中增加songCodeonPreLoadEvent中增加requestIdsetRouteInCommunicationMode(Android)CodecCapLevelsVideoCodecCapabilityLevelVideoCanvas中增加backgroundColor成员CodecCapInfo中增加codecLevels成员RemoteVideoStateReason中增加remoteVideoStateReasonCodecNotSupport枚举
IMusicContentCenter类下的preload方法中的jsonOption参数
v4.2.1
该版本于 2023 年 6 月 21 日发布。
该版本改进了网络传输策略，提升了音视频交互的流畅度。
该版本修复了以下问题：
- SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。
- 发送端调用
setAINSMode开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。
- 调用
destroyMediaPlayer销毁媒体播放器时偶现崩溃。 (iOS) - 屏幕共享场景下，部分机型必现接收端看到共享的画面卡顿。 (Android)
v4.2.0
该版本于 2023 年 5 月 26 日发布。
该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。
原有用于摄像头和屏幕采集的方法已删除，请改用下表中列出的替代方法，并通过设置 sourceType 来指定视频源。
| 已删除方法 | 替代方法 |
|---|---|
startSecondaryCameraCapture | startCameraCapture |
stopSecondaryCameraCapture | stopCameraCapture |
onCaptureVideoFrame 和 onPreEncodeVideoFrame 回调中新增了 sourceType 参数，用于表示具体的视频源类型。
ChannelMediaOptions中的publishCustomAudioTrackEnableAec已删除，请改用publishCustomAudioTrack。ChannelMediaOptions中的成员publishTrancodedVideoTrack变更为publishTranscodedVideoTrack。ChannelMediaOptions中的成员publishCustomAudioSourceId变更为publishCustomAudioTrackId。
- 删除
getMediaRecorder方法，可通过该版本新增的createMediaRecorder方法来创建录制对象。 - 删除
startRecording、stopRecording、setMediaRecorderObserver中的connection参数。 - 删除
IMediaRecorder类中的release方法，你可直接调用该版本新增的destroyMediaRecorder方法来销毁录制对象以释放资源。
自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。
如果你想自定义视频编码分辨率，可调用 setVideoEncoderConfiguration 方法，重新设置视频编码参数配置中的视频编码分辨率。
onApiCallExecuted已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。startChannelMediaRelay、updateChannelMediaRelay、startChannelMediaRelayEx和updateChannelMediaRelayEx已废弃，请改用startOrUpdateChannelMediaRelay和startOrUpdateChannelMediaRelayEx。
该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 setAINSMode 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。
为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 enableVirtualBackground 方法时，将自定义背景设置为更多类型：
- 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。
- 将背景替换为多种格式的本地视频。
该版本新增 setVideoScenario 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化：
- 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。
- 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。
该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 onRecorderStateChanged、onRecorderInfoUpdated 中新增 channelId 和 uid 参数，用于表示录制的音视频流的具体信息，并新增 createMediaRecorder 方法，用于创建本地或远端的录制对象。
你可以通过如下方法体验本地录制远端音视频功能：
createMediaRecorder：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。setMediaRecorderObserver：设置录制回调对象。startRecording：开始录制。stopRecording：停止录制。destroyMediaRecorder：销毁录制对象。
该版本新增本地合图功能，用户可以调用 startLocalVideoTranscoder 方法，在本地将多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）混合和渲染，以实现自定义布局和效果。通过这项功能，你可以轻松创建个性化的视频显示效果，满足各种场景需求，如远程会议、直播、在线教育场景，同时支持人像画中画等功能。
另外，SDK 还提供了updateLocalTranscoderConfiguration 方法和 onLocalVideoTranscoderError 回调。当你在开启本地合图后，可以调用 updateLocalTranscoderConfiguration 更新合图的配置；当你在开启本地合图或者更新本地合图配置失败时，可通过 onLocalVideoTranscoderError 回调得知合图失败的原因。
本地合图对 CPU 的消耗较高，声网建议你在性能较高的设备上开启该功能。
在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 getNtpWallTimeInMs 方法获取当前的 NTP (网络时间协议) 时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。
该版本新增 enableInstantMediaRendering 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。
该版本新增 startMediaRenderingTracing 和 startMediaRenderingTracingEx 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 onVideoRenderingTracingResult 回调报告相关事件的信息。
声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 onVideoRenderingTracingResult 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。
该版本新增了 setLocalVoiceFormant 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 setLocalVoicePitch 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。
该版本新增 queryScreenCaptureCapability 方法，用于查询当前设备的屏幕捕获能力。如果你想在屏幕共享时启用高帧率（如 60 fps）、但不确定设备是否支持时，可以调用该方法、然后从返回值中得知设备支持的最高帧率是否满足需求。
该版本新增 setScreenCaptureScenario 方法，用于设置屏幕共享的场景类型，SDK 会根据场景类型自动调整共享画面的的流畅度和清晰度。
该版本提升了音频文件类型兼容性，你可以通过 startAudioMixing、playEffect、openWithMediaSource 方法来打开以 content:// 开头的 URI 文件。
针对自定义视频和音频采集场景，该版本新增 getCurrentMonotonicTimeInMs 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。
该版本新增 startCameraCapture 方法，通过多次调用并指定 sourceType 参数可以同时开启多路摄像头采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头的场景。
针对在线 K 歌房场景，改版本新增 getCaches 和 removeCache 方法，用于获取、删除音乐资源缓存，并新增状态码和错误码，可方便用户排查问题。
该版本新增 startOrUpdatechannelMediaRelay 和 startOrUpdatechannelMediaRelayEx 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。
为更好地满足音频自采集的场景需求，该版本新增了 createCustomAudioTrack 和 destroyCustomAudioTrack 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性：
- 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。
- 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。
自该版本起，SDK 对 onRenderVideoFrame 回调进行了优化，在不同的视频处理模式下返回值的意义不同：
- 当视频处理模式为
ProcessModeReadOnly时，返回值无实际含义。 - 当视频处理模式为
ProcessModeReadWrite时，返回true代表设置 SDK 接收视频帧；返回false代表设置 SDK 丢弃视频帧。
该版本提升了超分辨率的性能表现。为提升超分辨率易用性，该版本删除了 enableRemoteSuperResolution，超分辨率不再需要手动开启，SDK 将自动根据用户设备性能优化远端视频的分辨率。
该版本修复了以下问题：
- 加入或退出频道时，安卓设备端偶现的崩溃。 (Android)
- 当快速切换身份角色时，观众端听不到声音。
- 偶现耳返开启无效。(Android)
- 跨频道连麦时
firstRemoteVideoFrameOfUid回调偶现丢失。(iOS) - 接收端主动订阅大流但是异常接收小流。(iOS)
- 偶现回声。(Android)
- 由于
onRemoteAudioStateChanged回调异常造成客户端状态异常。 - 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。
- 在红米 9A 上进行 CDN 推流，将推流的视频分辨率设置为 3840 × 2160 必现崩溃。 (Android)
- 合唱模式下，OPPO R11 设备外放加入频道后，对端听到明显杂声和回音。(Android)
- 本地音乐文件结束播放时，未能触发 onAudioMixingFinished 回调。(Android)
- 接收端通过视频观测器接收的第一帧视频帧偶现丢包。(Android)
- 在多频道场景下开启屏幕共享，偶现远端看到的本地屏幕共享画面为黑屏。(Android)
- 开启虚拟背景时切换至后置摄像头会导致背景倒置。 (Android)
- 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。
- 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。
-
IMusicContentCenter中新增如下方法 -
RtcEngineContext中新增domainLimit和autoRegisterAgoraExtensions属性 -
onRecorderStateChanged、onRecorderInfoUpdated中新增channelId和uid参数 -
onCaptureVideoFrame和onPreEncodeVideoFrame中增加sourceType参数 -
BackgroundSourceType中新增BackgourndNone和BackgroundVideo -
PreloadStatusCode中增加KPreloadStatusRemoved -
MusicContentCenterStatusCode中增加如下枚举：KMusicContentCenterStatusErrGatewayKMusicContentCenterStatusErrPermissionAndResourceKMusicContentCenterStatusErrInternalDataParseKMusicContentCenterStatusErrMusicLoadingKMusicContentCenterStatusErrMusicDecryption
-
MusicContentCenterConfiguration中新增maxCacheSize
onMusicChartsResult中的status修改为errorCodeonMusicCollectionResult中的status修改为errorCodeonLyricResult中的status修改为errorCodeonPreLoadEvent中的msg修改为errorCode
startChannelMediaRelaystartChannelMediaRelayExupdateChannelMediaRelayupdateChannelMediaRelayExonChannelMediaRelayEventChannelMediaRelayEvent
onApiCallExecutedChannelMediaOptions中的publishCustomAudioTrackEnableAecgetMediaRecorderIMediaRecorder类中的releasestartRecording、stopRecording、setMediaRecorderObserver中删除connection参数enableRemoteSuperResolutionRemoteVideoStats中删除superResolutionType
v4.1.0
该版本于 2022 年 12 月 20 日发布。
如果你已经使用了以下类或方法，请在升级到该版本后重新调用方法并更新参数设置：
删除了 enableDualStreamMode 中的 sourceType 参数，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。
该本版新增耳返功能。你可以调用 enableInEarMonitoring 开启耳返功能。
如需调节耳返音量，你可以调用 setInEarMonitoringVolume。
该版本支持加入频道前测试本地音频采集设备。你可以调用 startRecordingDeviceTest 开启音频采集设备测试，测试完成后，调用 stopPlaybackDeviceTest 方法停止音频采集设备测试。
为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 getNetworkType 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 onNetworkTypeChanged 回调，报告当前的网络连接类型。
声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请联系技术支持。
同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗，详见音强选流。
该版本新增音强选流功能，如需开启该功能，请联系技术支持。
该版本对双流模式做了优化，在加入频道前后均可调用 enableDualStreamMode 和 enableDualStreamModeEx。
扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式 (即：默认不主动发送小流)，可通过以下步骤开启发送小流：
- 接收端主播调用
setRemoteVideoStreamType或setRemoteDefaultVideoStreamType发起接收小流申请。 - 发送端收到申请后自动切换为发送小流模式。
如果你想修改上述发送端的默认行为，可以调用 setDualStreamMode 方法，将 mode 参数设置为 disableSimulcastStream (始终不发送小流) 或 enableSimulcastStream (始终发送小流)。
该版本新增了如下适用于空间音频场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。
- 隔声区域：你可以通过调用
setZones设置隔声区域和声音衰减系数。当音源 (可以为用户或媒体播放器) 跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用setPlayerAttenuation和setRemoteAudioAttenuation方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖setZones中的声音衰减系数。 - 多普勒音效：你可以通过设置
SpatialAudioParams中的enableDoppler参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下 (比如赛车游戏场景)，接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用
setHeadphoneEQPreset方法使用预设的耳机均衡效果，以改善耳机的听感。
该版本新增多路摄像头视频采集功能，你可以通过调用 enableMultiCamera 开启多路摄像头采集模式，再调用 startSecondaryCameraCapture 通过第二个摄像头采集视频，然后将采集到的视频发布到多频道中。
如需停止多路摄像头采集，需要先调用 stopSecondaryCameraCapture 停止第二个摄像头采集，然后调用 enableMultiCamera 并将 enabled 设置为 false。
为解决直播、语聊房、在线 K 歌房等场景下歌曲的应用版权问题，该版本新增版权音乐相关 API。你可以通过调用 MusicContentCenter 类、IMusicPlayer 类、MusicContentCenterEventHandler 类下的相关 API 实现在实时互动场景中播放版权音乐以及相关功能，例如检索音乐资源、获取音乐榜单及榜单详情、预加载及播放音乐资源、下载歌词及海报等功能。你还可以参考在线 K 歌房来体验搭配了演唱评分、美声音效等一系列功能的线上 K 歌场景化解决方案。
该版本新增 setHeadphoneEQParameters 方法，用于调节耳机均衡器的低频和高频参数，主要应用于空间音频场景。如果在调用 setHeadphoneEQPreset 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。
自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在不同终端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。
如果你希望体验该功能，请联系 sales@shengwang.cn。
该版本在 CameraCapturerConfiguration 中增加了 followEncodeDimensionRatio 成员参数，你可以在使用摄像头采集视频时，通过该成员参数设置是否跟随 setVideoEncoderConfiguration 中已经设置的视频宽高比。
该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。
- 新增
muteLocalAudioStreamEx和muteLocalVideoStreamEx方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增
muteAllRemoteAudioStreamsEx和muteAllRemoteVideoStreamsEx方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增
startRtmpStreamWithoutTranscodingEx、startRtmpStreamWithTranscodingEx、updateRtmpTranscodingEx和stopRtmpStreamEx方法，用于实现多频道场景下的旁路推流。 - 新增
startChannelMediaRelayEx、updateChannelMediaRelayEx、pauseAllChannelMediaRelayEx、resumeAllChannelMediaRelayEx和stopChannelMediaRelayEx方法，用于实现多频道场景下的跨频道媒体流转发。 leaveChannelEx方法新增options参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。
一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 VideoEncoderConfiguration 中新增 advanceOptions 成员参数，用于视频编码属性的进阶设置：
compressionPreference：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。encodingPreference：视频编码器偏好设置，用于进阶设置视频编码属性，视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。
使用声网私有媒体服务器的场景下，为支持用户在调用 setLocalAccessPoint 方法时的进阶设置，该版本在 LocalAccessPointConfiguration 中新增 advancedConfig 成员参数，该参数支持如下设置：
logUploadServer：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。
为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 onClientRoleChanged 回调中新增 newRoleOptions 参数，该参数取值如下：
audienceLatencyLevelLowLatency(1): 低延时，属于极速直播。audienceLatencyLevelUltraLowLatency(2): 超低延时，属于互动直播。
该版本优化了 onVideoSizeChanged 的触发逻辑，当单独调用 startPreview 时，也可触发该回调并上报本地视频大小发生改变。
为简化集成步骤，自该版本起，SDK 支持你在不添加 BLUETOOTH_CONNECT 权限的情况下，也能让 Android 用户正常使用蓝牙。
为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 onDirectCdnStreamingStats 回调报告推送的视频流的实际分辨率。
该版本对 updateChannelMediaRelay 方法做了如下优化：
- 4.1.0 版本前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码
relayEventPacketUpdateDestChannelRefused(8)，你需要重新调用updateChannelMediaRelay方法。 - 4.1.0 版本及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。
该版本基于 AI 方法重构了 AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。
该版本对虚拟背景算法做了如下优化：
- 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。
- 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。
- 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。
- 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。
- 降低了推送外部音频源时的上行延迟。
- 提升了会议场景 (
audioScenarioMeeting) 默认参数配置下的回声消除性能。 - 提升了 SDK 视频渲染的流畅度。
- 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。
该版本修复了以下问题：
- 在频道内调用
setVideoEncoderConfigurationEx将视频的分辨率调高时，偶现失效。 - 使用媒体播放器播放视频，先调用
play再调用pause暂停播放后，调用seek指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用resume恢复播放后，偶现视频画面出现快进。 - 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。
- 调用
getExtensionProperty失败，返回空字符串。 - 当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。
- 在多人会议场景下，本地用户接听并挂断电话后，偶现本地用户和远端用户无法听见对方的声音。
- 调用
setCloudProxy设置云代理后，调用joinChannelEx加入多频道失败。
- 调用
startAudioMixing播放ipod-library://item路径的音乐文件失败。 - 同时通过
onRecordAudioFrame和onCaptureVideoFrame回调分别获取的音频和视频数据时间戳不同。
getNativeHandlegetMusicContentCentergetPlaybackDefaultDevicegetRecordingDefaultDeviceenableDualStreamModeExsetDualStreamModesetDualStreamModeExSimulcastStreamModegetNetworkTypesetZonessetPlayerAttenuationsetRemoteAudioAttenuationsetHeadphoneEQPresetsetHeadphoneEQParametersHeadphoneEqualizerPresetenableMultiCamera(iOS)setRemoteVideoSubscriptionOptionssetRemoteVideoSubscriptionOptionsExVideoSubscriptionOptionsAdvancedOptionsEncodingPreferenceCompressionPreferenceadjustUserPlaybackSignalVolumeExonRhythmPlayerStateChangedRhythmPlayerStateTypeRhythmPlayerErrorTypeenableAudioVolumeIndicationExmuteLocalAudioStreamExmuteLocalVideoStreamExmuteAllRemoteAudioStreamsExmuteAllRemoteVideoStreamsExstartRtmpStreamWithoutTranscodingExstartRtmpStreamWithTranscodingExupdateRtmpTranscodingExstopRtmpStreamExstartChannelMediaRelayExupdateChannelMediaRelayExpauseAllChannelMediaRelayExresumeAllChannelMediaRelayExstopChannelMediaRelayExLocalAccessPointConfigurationAdvancedConfigInfoLogUploadServerInfoIMusicContentCenter接口类及其中方法IMusicPlayer接口类及其中方法IMusicContentCenterEventHandler接口类及其中回调MusicChartInfo类ClimaxSegment类Music类MusicContentCenterConfiguration类MusicChartCollection类 (iOS)MusicCollection类 (iOS)PreloadStatusCode(iOS)MusicContentCenterStatusCode(iOS)
enableDualStreamMode：删除sourceTypeChannelMediaOptions：新增isAudioFilterableSpatialAudioParams：新增enableDopplerScreenCaptureSourceInfo：新增minimizeWindowCameraCapturerConfiguration：新增followEncodeDimensionRatioleaveChannelEx：新增optionsVideoEncoderConfiguration：新增advanceOptionsLocalAccessPointConfiguration：新增advancedConfigonClientRoleChanged：新增newRoleOptionsVideoCanvas：新增setupMode、mediaPlayerId和cropAreaLocalVideoStats：新增hwEncoderAccelerating
onApiCallExecutedChannelMediaRelayEvent：废弃relayEventPacketUpdateDestChannelRefused(8)
v4.0.0
该版本于 2022 年 9 月 29 日发布。
v4.0.0 SDK 包名由 react-native-agora-rtc-ng 变更为 react-native-agora，且对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。如下为存在兼容性变更的主要功能：
- 多频道
- 媒体流发布控制
- 警告码
升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见迁移指南。
该版本支持通过设置 RtcEngineEx 和 ChannelMediaOptions，实现一个 IRtcEngine 实例同时采集多路音视频源并发布到远端，适应各种业务场景。例如：
- 调用
joinChannel加入首个频道后，多次调用joinChannelEx加入多个频道，通过不同的用户 ID 和ChannelMediaOptions设置发布指定的流到不同的频道。 - 支持通过设置
ChannelMediaOptions中的publishSecondaryCameraTrack和publishSecondaryScreenTrack同时发布多路摄像头采集或者屏幕共享的视频流。
同时，该版本支持通过 createCustomVideoTrack 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流：
- 创建自采集视频轨道：调用
createCustomVideoTrack方法创建一个自定义视频轨道，并获得视频轨道 ID。 - 设置频道中待发布的自采集视频轨道：在每个频道的
ChannelMediaOptions中，将customVideoTrackId参数设置为你想要发布的视频轨道 ID，并将publishCustomVideoTrack设置为true。 - 推送外部视频源：调用
pushVideoFrame，并将videoTrackId指定为你想要发布的自定义视频轨道 ID，即可根据步骤 2 的设置，实现在多个频道中发布对应的自定义视频源。
结合多频道能力，你还可以体验如下功能：
- 将多组音视频流通过不同的用户 ID (
uid) 发布到远端。 - 将多路音频流混音后通过一个用户 ID (
uid) 发布到远端。 - 将多组视频频流通过不同的用户 ID (
uid) 发布到远端。 - 将多路视频流合图后通过一个用户 ID (
uid) 发布到远端。
为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持全高清 (FHD) 和超高清 (UHD) 视频分辨率。你可以在调用 setVideoEncoderConfiguration 方法时，将 dimensions 参数设置为 1920 × 1080 或更高的分辨率。如果你的设备不支持高分辨率，SDK 支持自动回退到适合的分辨率。
为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 createMediaPlayer 创建媒体播放器后，你可以通过 IMediaPlayer 类的一系列方法体验内置媒体播放器的各类功能：
- 自动播放本地、在线、自定义的媒体资源。
- 预先加载待播放的媒体资源。
- 根据网络情况切换媒体资源的播放线路。
- 将媒体播放器的音视频流推送到任意频道、分享给远端用户。
- 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。
自该版本起，SDK 支持新版 AI 降噪（相对于 v3.7.0 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。 如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。
为还原音频的细节、提升音频的清晰度，该版本新增 UltraHighQualityVoice。在语聊、歌唱等以人声为主的场景中，你可以调用 setVoiceBeautifierPreset 并使用该枚举体验超高音质。
空间音频功能当前处于实验阶段，请联系 sales@shengwang.cn 开通空间音频功能，如果需要技术支持，请提交工单。
该版本提供本地直角坐标系计算方案实现空间音频：
-
使用
ILocalSpatialAudioEngine类实现空间音频，通过 SDK 计算远端用户的空间坐标。你需要分别调用updateSelfPosition和updateRemotePosition更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音频。 -
通过 SDK 计算媒体播放器的空间坐标。你需要在
ILocalSpatialAudioEngine类中分别调用updateSelfPosition和updatePlayerPositionInfo更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音频。
该版本为实时合唱赋予了如下能力：
- 支持两人及两人以上合唱。
- 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。
- 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。
该版本新增 AudioScenarioChorus 枚举来设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。
为满足各类业务场景对频道管理的需求，该版本在 ChannelMediaOptions 结构体中新增了如下功能：
- 设置或切换多种音视频源的发布
- 设置或切换频道场景、用户角色
- 设置或切换订阅视频的大小流类型
- 控制音频发布时延
在调用 joinChannel 或 joinChannelEx 时设置 ChannelMediaOptions，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 updateChannelMediaOptions 随时更新 ChannelMediaOptions 中的设置，例如，切换发布的音视频源。
该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享：
-
- 在加入频道前调用
startScreenCapture，然后调用joinChannel[2/2] 加入频道并设置publishScreenCaptureVideo为true，即可开始屏幕共享。 - 在加入频道后调用
startScreenCapture，然后调用updateChannelMediaOptions设置publishScreenCaptureVideo为true，即可开始屏幕共享。
- 在加入频道前调用
该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通 IRtcEngineEx 类下的同名方法来实现该功能。
setSubscribeAudioBlocklist：设置音频订阅黑名单。setSubscribeAudioAllowlist：设置音频订阅白名单。setSubscribeVideoBlocklist：设置视频订阅黑名单。setSubscribeVideoAllowlist：设置视频订阅白名单。
如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。
为方便用户灵活修改音频场景，该版本新增 setAudioScenario 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (AudioScenarioDefault) 切换为高音质场景 (AudioScenarioGameStreaming)，你可以调用该方法。
该本版新增 setLocalAccessPoint 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。
该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 enableVideoImageSource 来开启该功能，并通过 options 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。
该版本通过 leaveChannel 和 joinChannel 切换频道即可实现和 v3.7.0 中 switchChannel 一样的切换速度，无需额外调用 switchChannel 方法。
该版本新增支持推送 I422 格式的外部视频帧，你可以通过 pushVideoFrame[1/2] 方法将 I422 格式的外部视频帧推送至 SDK。
该版本在 onAudioVolumeIndication 的 AudioVolumeInfo 中新增 voicePitch 参数。你可以通过 voicePitch 获取本地用户的人声音调，从而实现唱歌评分等业务功能。
该版本优化了 startPreview 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 startPreview 方法来开启视频预览，无调用时序要求。
你可以通过 setRemoteDefaultVideoStreamType 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。
该版本新增 onPermissionError 方法，当获取音频采集设备或摄像头权限失败时自动上报，用户可根据该回调的提示开启相应的设备权限。