# 发版说明 (/zh-CN/realtime-media/rtc/reference/release-notes) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" /> :::caution[注意] 自 2026 年 9 月 14 日开始，通过 Gradle 自动集成 Android SDK 时，需要额外配置声网 Maven CDN 仓库。具体配置方式请参考[下载 SDK](/zh-CN/realtime-media/rtc/reference/downloads/android#通过-gradle-自动集成-sdk)。 通过 Gradle 自动集成并升级至 v4.6.0 及以上版本时，除更新版本号外，还需将包名从 `io.agora.rtc` 修改为 `cn.shengwang.rtc`。 ::: ## v4.7.0 [#v470] 该版本于 2026 年 9 月 22 日发布。 ### 新增特性 [#新增特性] #### 声网高级美颜 2.1 [#声网高级美颜-21] 该版本支持声网高级美颜 2.1 API，并新增美颜人脸检测能力。使用声网高级美颜功能的客户可以检测人脸置信度。使用 RTC SDK v4.7.0 及以上版本集成声网高级美颜时，请参考[实现声网高级美颜](/zh-CN/realtime-media/rtc/build/video/advanced-beauty)；如果仍使用 RTC SDK v4.6.x，请继续参考[声网高级美颜 2.0 文档](/zh-CN/realtime-media/rtc/build/video/advanced-beauty-460)。 ### 改进 [#改进] #### 声网高级美颜场景性能优化 [#声网高级美颜场景性能优化] 该版本针对启用声网高级美颜的场景进行专项性能优化，720p 15fps 满帧开播的机型覆盖率大幅提高，更多中低端设备能稳定输出高清流畅的美颜画面。 #### 音视频链路性能优化 [#音视频链路性能优化] 该版本针对音视频链路与线程调度机制做了专项优化，显著降低各音视频场景 CPU 消耗，同步提升长时间运行稳定性。 #### 音频 SDK FFmpeg 插件集成优化 [#音频-sdk-ffmpeg-插件集成优化] 该版本调整了音频 SDK 中 FFmpeg player 插件的加载方式。`libagora-ffmpeg.so` 已更名为 `libagora_ffmpeg_extension.so`，并由必需库调整为可选插件。SDK 包中默认包含该插件，你可以根据业务需要选择是否集成。未加载 FFmpeg player 插件时，MediaPlayer 使用系统原生播放能力，实际支持的音频文件格式取决于系统支持的容器格式和音频编解码器，不同系统版本或设备厂商可能存在差异；集成并加载 FFmpeg player 插件后，MediaPlayer 可支持更多音频格式和播放能力。 #### 视频首帧体验优化 [#视频首帧体验优化] 该版本优化了视频帧传输调度机制，提升了频道内首个用户订阅流的出图速度。 #### R8/ProGuard 混淆规则配置优化 [#r8proguard-混淆规则配置优化] 该版本优化了 Android SDK 的 R8/ProGuard 混淆规则配置。如果你的 app 未开启 R8/ProGuard 缩减和混淆，无需额外配置；如果开启了 R8/ProGuard 缩减和混淆，则需配置声网 SDK 相关混淆规则，以避免 Native 层通过 JNI 访问的 Java 类、成员或方法被移除或重命名。你可以继续使用 `-keep class io.agora.**{*;}` 快速配置，或使用 SDK 提供的 `consumer-proguard-rules.pro` 做精细化配置。 #### 1v1 连麦延时体验优化 [#1v1-连麦延时体验优化] 该版本优化了视频1v1等实时互动场景下的音视频策略，在保障画质的前提下改善端到端延迟，并提升突发抖动等弱网场景下的播放流畅性。 #### 音频场景码率优化 [#音频场景码率优化] 该版本优化了音频场景下的码率开销，保障音质的前提下提升了音频流传输效率。 #### Native 与 Web 互通弱网体验优化 [#native-与-web-互通弱网体验优化] 该版本优化了视频 1v1 弱网场景下 Native 与 Web 互通的音视频体验。 #### 媒体文件播放兼容性优化 [#媒体文件播放兼容性优化] 该版本针对不合规 MP3 文件做了针对性兼容适配，提升了媒体文件播放的鲁棒性。 ### 问题修复 [#问题修复] 该版本修复了以下问题： - 修复了开启音频裸数据后，从观众切换为主播时低概率出现残留上一段声音的问题。 - 修复了多人音频情况下行压力比较大时，特定 Android 设备升级后播放音频时偶现电流声或杂音的问题。 - 修复了预加载音效场景下，调用 `stopEffect` 停止播放后再次调用 `playEffect` 时，上一段音效仍有残留的问题。 - 修复了部分场景下人脸检测回调未按预期触发的现象，解决了人脸信息获取不稳定的问题。 - 修复了设备处于系统通话或音频占用状态时，本地音频状态回调异常的现象，解决了应用无法准确感知本地音频状态的问题。 ## v4.6.4 [#v464] 该版本于 2026 年 8 月 31 日发布。 ### 新增特性 [#新增特性-1] 该版本新增以下特性： - 新增两个回调事件，用于通知 Android 广角 / 超广角摄像头采集开启的成功或失败。 ### 问题修复 [#问题修复-1] 该版本修复了以下问题： - 修复了断网后 `onNetworkQuality` 回调报告的网络质量可能不准确的问题。 - 修复了接收端设置音频场景为`AUDIO_SCENARIO_AI_CLIENT`，发送端频繁停止和恢复发送音频流，当接收端网络不佳时偶现无声问题。 - 修复了使用有线耳机进行音视频互动时，在特定音频路由配置场景下偶现音质变差的问题。 - 修复了自渲染视频帧场景下，本地预览画面偶现卡住的问题。 - 修复了在 Android 模拟器上部分场景下偶现回声的问题。 - 修复了启用 Google 安全加固后，音视频互通过程中偶现 App 崩溃或无响应（ANR）的问题。 - 修复了 Android 手表连接蓝牙耳机时，音频路由可能切换到外放的问题。 - 修复了 App 集成调用 `setExternalVideoSource` 设置推送的外部视频源类型为已编码的视频帧（`ENCODED_VIDEO_FRAME`），推送的已编码视频帧包含的 SEI 信息长度如果与编码协议规定不匹配，偶现崩溃问题。 - 修复了音视频互动场景下偶现 App 崩溃的问题。 - 修复了 Web 与 Native 音视频互通场景下，偶现视频编码失败、远端视频卡顿或花屏的问题。 - 修复了开启媒体播放器缓存后，在断网场景下播放已缓存资源时，可能延迟约 10 秒并回调错误的问题。 - 修复了使用媒体播放器播放 CDN 流时，分辨率变化后偶现花屏的问题。 - 修复了 App 以通信模式（`CHANNEL_PROFILE_COMMUNICATION`）加入频道后，调用 `updateChannelMediaOptions` 更新频道媒体选项后，NCS 和 RESTful API 返回的频道信息被错误识别为互动直播模式的问题。 ## v4.6.3 [#v463] 该版本于 2026 年 2 月 9 日发布。 :::warning[注意] - 通过 Maven Central 集成并升级至 v4.6.0 及以上版本时，除更新版本号外，还需将包名从 `io.agora.rtc` 修改为 `cn.shengwang.rtc`。 - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.so` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.so` 库。 - 4.6.3 RTC SDK `libaosl.so` 库版本为 1.3.5。 ::: ### 问题修复 [#问题修复-2] 该版本修复了以下问题： - 部分机型开启美颜功能进行音视频互动场景下，偶现发送端黑屏或 App 崩溃。 - 音视频互动场景下偶现 App 崩溃。 ## v4.6.2 [#v462] 该版本于 2026 年 1 月 16 日发布。 :::warning[注意] - 通过 Maven Central 集成并升级至 v4.6.0 及以上版本时，除更新版本号外，还需将包名从 `io.agora.rtc` 修改为 `cn.shengwang.rtc`。 - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.so` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.so` 库。 - 4.6.2 RTC SDK `libaosl.so` 库版本为 1.3.5。 ::: ### 升级必看 [#升级必看] #### EncodedVideoFrameInfo 结构体删除参数 uid [#encodedvideoframeinfo-结构体删除参数-uid] 该版本删除了 `EncodedVideoFrameInfo` 结构体中的 `uid` 参数。你可以直接从 [`onEncodedVideoFrameReceived`](/zh-CN/api-reference/rtc/android/video/video-encoded#callback_ivideoencodedframeobserver_onencodedvideoframereceived) 回调中获取远端用户的 `remoteUid` 信息。如果你之前集成过相关代码，请相应更新集成逻辑。 #### Lite 和 Voice 包中去除音频频谱功能 [#lite-和-voice-包中去除音频频谱功能] 为进一步优化 SDK 包体积，该版本将音频频谱（Audio Spectrum）功能从 Lite 和 Voice SDK 包中移除。如果你需要使用音频频谱功能，请集成完整（Full）包。 #### 其他 [#其他] - 为保证整体解码兼容性，相关解码器插件已内置在 SDK 中。 ### 新增特性 [#新增特性-2] #### 新增支持共享单个 App [#新增支持共享单个-app] 从 Android 14 开始，系统支持用户在屏幕共享时选择共享整个屏幕或共享单个 App，以提升隐私保护和多任务处理能力。 该版本适配了该系统能力，在支持共享整个屏幕的基础上，新增支持共享单个 App。同时，为便于管理相关事件，新增 [`onLocalVideoEvent`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideoevent) 回调，用于报告本地视频，尤其是屏幕共享相关的事件。 #### 新增权限被授予回调 [#新增权限被授予回调] 为便于确认屏幕共享场景下的权限授权情况，该版本新增 [`onPermissionGranted`](/zh-CN/api-reference/rtc/android/network#callback_irtcengineeventhandler_onpermissiongranted) 回调。你可以通过该回调判断当前用户授予的是相机（Camera）权限还是屏幕（Screen）权限。 #### Media Player 支持获取音频缓冲延迟 [#media-player-支持获取音频缓冲延迟] 为解决 K 歌场景中可能会出现的主唱与伴唱伴奏不同步的问题，该版本在 Media Player 模块中新增 [`getAudioBufferDelay`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-info#api_imediaplayer_getaudiobufferdelay) 方法，用于获取播放媒体文件时毫秒级的音频缓冲延迟。 ### 改进 [#改进-1] #### playEffect 支持无缝切换 [#playeffect-支持无缝切换] 该版本新增支持音效文件的无缝切换。对于同一个音效文件，如果先调用 `preloadEffect` 再调用 `playEffect`，在播放完成或通过 `stopEffect` 停止播放后，SDK 不会关闭该音效文件。当再次调用 `playEffect` 时，SDK 会直接复用已加载的文件进行播放，从而实现循环播放和无缝切换。该能力同样适用于多频道场景。 #### onNetworkQuality 准确性提升 [#onnetworkquality-准确性提升] 该版本提升了 `onNetworkQuality` 回调中网络质量评估的准确性，使回调数据更贴近用户的主观体验。 #### onPlaybackAudioFrame 支持 24k 采样率的音频帧 [#onplaybackaudioframe-支持-24k-采样率的音频帧] 该版本在 `onPlaybackAudioFrame` 中新增支持采样率为 **24000 Hz** 的音频数据。在调用 [`setPlaybackAudioFrameParameters`](/zh-CN/api-reference/rtc/android/audio/audio-raw#api_irtcengine_setplaybackaudioframeparameters) 设置播放音频数据格式时，可以将 `sampleRate` 设为 `24000`。 #### onEncodedVideoFrameReceived 回调支持获取频道 ID [#onencodedvideoframereceived-回调支持获取频道-id] 该版本在 `onEncodedVideoFrameReceived` 回调中新增 `channelId` 参数，方便你在获取编码后视频数据时识别其所属频道。 #### 其他改进 [#其他改进] 该版本还进行了如下改进： - 新增错误码 `ERR_PCMSEND_FORMAT (200)` 和 `ERR_PCMSEND_BUFFEROVERFLOW (201)`，用于报告 PCM 数据发送相关错误。 - 在弱光或暗光场景下，优化了部分设备的视频采集效果，使画面更亮。 - 录制模块 Media Recorder 新增支持录制 Media Player 和 Audio Mixing 的声音。 ### 问题修复 [#问题修复-3] 该版本修复了以下问题： - 接收端使用部分机型（如 Redmi 14C）进行音视频互通时，偶现发送端用户画面出现黑边的问题。 - `startLocalTranscoder` 接口中设置的 `bitrate` 不生效。 - 在部分模拟器（如雷电 9）上进行音视频互通时，接收端偶现听到电流声的问题。 - 在直播 PK 场景中，观众端启用合图视频流单独渲染功能时，偶现单独渲染的用户画面显示异常。 - 音视频互通场景下，本地调用 `playEffect` 播放音效后，当远端用户换为主播角色并开始说话时，本地偶现听到电流声。 - 在部分 vivo 机型上，运行 Android 15 系统的设备在关闭摄像头时，偶现 App 崩溃。 - 用户以主播身份在音频 Scenario 为 `AUDIO_SCENARIO_CHATROOM` 的情况下加入频道且未发布本地音频，调用 `startAudioMixing` 播放音乐文件后，再将音频 Scenario 切换为 `AUDIO_SCENARIO_GAMESTREAMING` 时，偶现听到杂音。 - 在音视频互通场景下，偶现 App 无响应（ANR）的问题。 - 修复了音视频互通过程中偶现崩溃的问题。 - 美颜功能在部分场景下不生效。 ## v4.6.1 [#v461] 该版本于 2025 年 11 月 21 日发布。 :::warning[注意] - 通过 Maven Central 集成并升级至 v4.6.0 及以上版本时，除更新版本号外，还需将包名从 `io.agora.rtc` 修改为 `cn.shengwang.rtc`。 - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.so` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.so` 库。 - 4.6.1 RTC SDK `libaosl.so` 库版本为 1.3.0。 ::: ### 问题修复 [#问题修复-4] - 音视频互通过程中，偶现接收端用户看到图像黑屏。 - App 通过 VPN 连接网络进行音视频互通，互通过程中偶现崩溃。 - 使用媒体播放器播放分辨率为 4K 的视频源时，出现花屏图像。 - 音视频互通过程中偶现崩溃。 - 多频道场景下，App 进行音视频互通时偶现闪退。 - 使用音频 SDK 时，`onRtcStats` 回调报告 `memoryAppUsageRatio` 值始终为 0。 ## v4.6.0 [#v460] 该版本于 2025 年 8 月 18 日发布。 :::warning[注意] - 通过 Maven Central 集成并升级至 v4.6.0 及以上版本时，除更新版本号外，还需将包名从 `io.agora.rtc` 修改为 `cn.shengwang.rtc`。 - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.so` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.so` 库。 - 4.6.0 RTC SDK `libaosl.so` 库版本为 1.3.0。 ::: ### 升级必看 [#升级必看-1] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的废弃及删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 各版本废弃及删除的 API 信息。详见 [API 下架说明](/zh-CN/api-reference/rtc/android/rtc-api-sunset)。 #### 直推 CDN 相关接口废弃 [#直推-cdn-相关接口废弃] 该版本废弃直推 CDN 功能的相关接口，并会在后续版本中删除，请改用[服务端旁路推流](/zh-CN/realtime-media/media-push)。 - `setDirectCdnStreamingAudioConfiguration` - `setDirectCdnStreamingVideoConfiguration` - `startDirectCdnStreaming` - `stopDirectCdnStreaming` - `DirectCdnStreamingMediaOptions` - `DirectCdnStreamingStats` - `DirectCdnStreamingState` - `DirectCdnStreamingReason` #### 虚拟节拍器接口废弃 [#虚拟节拍器接口废弃] 该版本废弃虚拟节拍器功能的相关接口，并会在后续版本中删除。 - [`startRhythmPlayer`](/zh-CN/api-reference/rtc/android/play/rhythmplayer#api_irtcengine_startrhythmplayer) - [`configRhythmPlayer`](/zh-CN/api-reference/rtc/android/play/rhythmplayer#api_irtcengine_configrhythmplayer) - [`onRhythmPlayerStateChanged`](/zh-CN/api-reference/rtc/android/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) #### 水印接口废弃 [#水印接口废弃] 该版本废弃水印功能的相关接口，推荐使用该版本新增的水印接口。 - [`addVideoWatermark`](/zh-CN/api-reference/rtc/android/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2)[2/3] - [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/android/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex)[1/2] #### 冗余接口删除 [#冗余接口删除] 该版本删除了下列冗余接口及参数： - `setLocalPublishFallbackOption` - `onLocalPublishFallbackToAudioOnly` - `onDownlinkNetworkInfoUpdated` - `onWlAccStats` - `enableWirelessAccelerate` #### 美妆功能实现变更 [#美妆功能实现变更] 受美颜重构的影响，自 v4.6.0 起，不再支持调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/android/extension#api_irtcengine_setextensionproperty) 启用美妆功能，改用 `STYLE_MAKEUP` 节点实现。 #### 新增域名白名单 [#新增域名白名单] 如果你由之前的版本升级到 v4.6.0 且使用了域名白名单功能（`RtcEngineConfig` 下的 `mdomainLimit` 为 `true`），请在白名单中添加以下域名，以确保互通顺畅： - `*.rtnsvc.com` - `*.realtimemesh.com` ### 新增特性 [#新增特性-3] #### 多路分辨率视频流 [#多路分辨率视频流] 该版本新增多路分辨率视频流（Adaptive Bitrate Video Streaming，简称 ABR）功能，支持对同一视频源设置同时发送多路不同分辨率的视频流，并支持多频道场景。接收端通过自动/手动订阅目标分辨率的视频流。 启用 ABR 后，你可以配置不同分辨率的视频流（最多四层分辨率，即一个最高分辨率的主流和三层其他较低分辨率的视频流），并设置视频流的分辨率、码率、是否启用分层推流回退等选项来灵活控制流的发布。启用分层推流回退后，SDK 会在弱网环境下自动回退到低分辨率的视频流，确保流畅的观看体验。订阅端可根据实际需求选择想要接收的视频流。适用于会议场景、大班课、互动直播等多终端、多网络环境，可显著提升弱网下的观看体验。 具体实现方法以及和视频双流的对比可以参考进阶功能[发布多路视频流 (ABR)](/zh-CN/realtime-media/rtc/build/video/simulcast)。 #### 多路径网络传输 [#多路径网络传输] 该版本新增多路径传输功能，适用于终端支持多网卡传输（比如 5G、Wi-Fi、LAN）的设备，可以有效降低甚至消除弱网带来的体验回退，适用于弱网环境、对传输稳定性要求高的实时音视频通信场景，如车载、IoT、火车、高速公路等复杂网络环境。通过在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 中设置 `enableMultipath` 为 `true`，可开启多路径传输能力。支持两种传输模式（[`MultipathMode`](/zh-CN/api-reference/rtc/android/enum-multipathmode)）： - 动态模式：（默认）根据网络状况动态选择最佳路径进行传输，适用于流量敏感、对体验要求比较高的场景，如会议、教育等。动态模式下，你可以通过 `preferMultipathType` 指定首选的网络传输路径（如优先 Wi-Fi 或移动网络）。 - 全冗余模式：数据会在所有可用网络路径上同时传输，适用于流量不敏感，对体验有极致要求的场景，如户外采播、平行操控等。该模式会产生额外费用，如需使用请[联系技术支持](https://ticket.shengwang.cn/)。 上下行还可分别通过 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 中的 `uplinkMultipathMode`、`downlinkMultipathMode` 配置。启用后，SDK 会通过回调 [`onMultipathStats`](/zh-CN/api-reference/rtc/android/network#callback_irtcengineeventhandler_onmultipathstats) 实时上报各路径的传输统计信息，包括每一个传输路径的流量消耗，便于开发者监控和优化网络表现。 #### 视频质量评分 [#视频质量评分] 该版本在 [`RemoteVideoStats`](/zh-CN/api-reference/rtc/android/class-remotevideostats) 中新增 `mosValue` 成员，报告声网实时视频 MOS（平均主观意见分）评估系统对接收到的远端视频流的质量评分。评分共有 5 个档次，5 分表示视频画质优秀，画面清晰无噪点，1 分表示视频画质极差，画面严重模糊。你可以通过该参数实时观测远端视频流的主观画质表现，便于动态调整视频参数、优化用户体验，或用于质量监控和告警等场景。如需启用该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 支持添加多个水印 [#支持添加多个水印] 该版本废弃了 [`addVideoWatermark`](/zh-CN/api-reference/rtc/android/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2)[2/3] 和 [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/android/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex)[1/2] 方法，新增 [`addVideoWatermark`](/zh-CN/api-reference/rtc/android/video/video-prenpro/watermark#api_irtcengine_addvideowatermark3)[3/3] 和 [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/android/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex1)[2/2] 方法，支持通过水印 ID 来给视频添加多个水印，并可对水印进行排序。如果你需要移除指定水印，可调用 [`removeVideoWatermark`](/zh-CN/api-reference/rtc/android/video/video-prenpro/watermark#api_irtcengine_removevideowatermark) 方法。 #### 异步销毁引擎 [#异步销毁引擎] 该版本新增 `destroy` [2/2] 方法，用于销毁 RTC 引擎，且支持通过参数配置以同步或异步方式销毁引擎。异步销毁引擎时，SDK 会触发 `onEngineReleased` 回调。 #### 美颜功能拓展 [#美颜功能拓展] 新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。 #### Token 更新结果回调 [#token-更新结果回调] 该版本新增 [`onRenewTokenResult`](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调及 `RENEW_TOKEN_ERROR_CODE` 错误码。当调用 `renewToken` 方法更新 Token 后，SDK 会通过 [`onRenewTokenResult`](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调通知 Token 更新的结果，并通过 `RENEW_TOKEN_ERROR_CODE` 返回详细的错误码，开发者可在回调中根据错误码及时处理 Token 更新失败的场景。 #### 其他 [#其他-1] - 新增 [`setPlaybackAudioFrameBeforeMixingParameters`](/zh-CN/api-reference/rtc/android/audio/audio-raw#api_irtcengine_setplaybackaudioframebeforemixingparameters1)[2/2] 方法用于设置 [`onPlaybackAudioFrameBeforeMixing`](/zh-CN/api-reference/rtc/android/audio/audio-raw#callback_iaudioframeobserver_onplaybackaudioframebeforemixing) 回调中返回的音频帧格式，包括采样率、声道数以及每次回调的数据采样点数。调用此方法后，SDK 会按照设定的参数返回混音前的原始音频数据，便于开发者进行自定义处理或分析。 - 新增 `preloadEffectEx` 方法，用于将指定音效文件预加载到指定频道，支持本地或在线音效文件，便于后续快速播放，适合多频道场景。 - 新增 `playEffectEx` 方法，用于在指定频道播放音效文件，支持设置循环次数、音调、空间位置、音量、是否发布到频道及播放起始位置等参数，满足丰富的音效播放需求。 - 本地截图上传功能支持通过 [`ContentInspectModule`](/zh-CN/api-reference/rtc/android/class-contentinspectmodule) 中新增的 `position` 成员设置截图的视频观测位置，从而实现对原始视频数据或效果处理前后的视频流进行截图并上传。 - 为了提升用户使用绿幕或蓝幕开启虚拟背景功能时，人像分割的准确性和稳定性，该版本在 [`SegmentationProperty`](/zh-CN/api-reference/rtc/android/class-segmentationproperty) 中新增 `screenColorType` 属性，支持指定背景幕布的颜色为绿色、蓝色或自动识别。 ### 改进 [#改进-2] #### 美颜重构 [#美颜重构] 该版本对美颜功能进行了彻底重构和升级，不仅拓展了美颜功能，提升了美颜效果和性能，还解决了美颜参数配置复杂、集成成本高、美颜资源依赖网络易失效等痛点。主要改进包括： - **新增美颜功能**：新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。 - **API 大幅简化**：将过去版本中的基础美颜、美型、美妆、滤镜功能整合为 `BEAUTY`、`STYLE_MAKEUP`、`FILTER` 三个核心节点 (node)，通过 [`IVideoEffectObject`](/zh-CN/api-reference/rtc/android/class-ivideoeffectobject) 统一管理生命周期和参数设置，减少频繁 API 调用带来的性能负担。 - **预设模板开箱即用**：提供多套预设风格模板（如“自然美颜”、“学姐妆”、“冷白滤镜”），大幅简化集成流程，无需手动调试数十项参数。 - **美颜参数动态控制**：该版本新增实时获取美颜参数的能力，开发者可通过 key-value 方式动态读取或修改任意细粒度参数（如磨皮强度、口红类型）。同时支持：调用预设模板快速启用风格效果、保存主播自定义参数配置、随时重置参数至默认状态，极大提升了业务层状态同步的灵活性和开发效率。 - **美颜资源外置**：该版本通过美颜资源外置化设计，将所有美颜资源（特效、滤镜、妆容）均打包为本地 bundle 文件，彻底消除因网络下载失败导致美颜失效的风险。 #### 其他改进 [#其他改进-1] - 在与 Web 端互通时，新增对 g711 和 g722 音频编解码器的支持，进一步提升了跨平台音频播放的兼容性和清晰度。 - 优化了插件加载的方式，用 C++ 开发 Android App 支持自动加载 SDK 的动态库插件。 - 优化了屏幕共享文档场景下的共享视频清晰度。 ### 问题修复 [#问题修复-5] 该版本修复了以下问题： - 调用 `open` [1/2] 打开在线音效文件后，调用 [`playEffect`](/zh-CN/api-reference/rtc/android/play/audio-effect-file#api_irtcengine_playeffect3)[2/2] 开始播放，当调用 `seek` 指定播放位置后，音效文件会从头开始播放。 - 在媒体音量模式下，主播在频道中发布麦克风采集的音频流，同时调用 [`playEffect`](/zh-CN/api-reference/rtc/android/play/audio-effect-file#api_irtcengine_playeffect3)[2/2] 播放音效文件、调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/android/play/audio-mixing#api_irtcengine_startaudiomixing2)[2/2] 播放音乐文件，偶现回声。 - 在 [`setExternalVideoSource`](/zh-CN/api-reference/rtc/android/video/video-custom-capturenrendering#setexternalvideosource) 之后调用 [`registerMediaMetadataObserver`](/zh-CN/api-reference/rtc/android/metadata/metadata-observer#api_irtcengine_registermediametadataobserver) 注册媒体 metadata 观测器，SDK 没有触发 metadata 观测器的回调。 - 偶现的崩溃问题。 - 调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 加入频道，然后调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 开始跨频道媒体流转发，下麦、退出频道后重新加入频道开始连麦，偶现 [`onChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) 回调报告 `state` 为 `RELAY_STATE_FAILURE`，[`code`](/zh-CN/api-reference/rtc/android/play/rte-player#api_error_code) 为 `RELAY_ERROR_SERVER_ERROR_RESPONSE`。 - 加入频道前调用 [`setAudioScenario`](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_setaudioscenario) 设置音频场景为 `AUDIO_SCENARIO_CHATROOM`，加入频道后使用蓝牙耳机或有线耳机进行音视频互通，偶现听到杂音。 ## v4.5.2 [#v452] 该版本于 2025 年 4 月 22 日发布。 :::warning[注意] - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.so` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.so` 库。 - 4.5.2 RTC SDK `libaosl.so` 库版本为 1.2.13。 ::: ### 升级必看 [#升级必看-2] 该版本对部分功能的实现方式进行了优化，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 成员参数变更为方法 [#成员参数变更为方法] 为优化 API 设计，该版本将 [`PlayerInfo`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_rteplayerinfo) 中的所有成员参数变为方法。如果你的 App 中使用了 [`PlayerInfo`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_rteplayerinfo) 中的成员参数，请更新为对应的方法。 ### 改进 [#改进-3] #### URL 拉流播放 [#url-拉流播放] 该版本进一步拓展了 URL 拉流播放的功能，支持播放 CDN URL 和本地媒体资源文件，同时可以设置从指定位置开始播放、调节播放速度、设置播放音量、在播放过程中切换播放源等，详见[观众端 URL 拉流](/zh-CN/realtime-media/rtc/build/optimize-and-operate/playing-url)。 #### 媒体播放器信息属性可访问 [#媒体播放器信息属性可访问] 自该版本起，媒体播放器相关信息 [`PlayerUpdatedInfo`](/zh-CN/api-reference/rtc/android/class-playerupdatedinfo#PlayerUpdatedInfo) 中的所有属性访问修饰符已从 private 修改为 public。这一改进旨在提高类的可访问性，使得外部代码能够更方便地访问和修改这些属性。 ### 问题修复 [#问题修复-6] 该版本修复了以下问题： - 开启导唱功能播放多音轨歌曲时，调用 [`setAudioPitch`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setaudiopitch) 方法调整歌曲音调后出现杂音。 - 主播端调用 [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/android/audio/audio-custom-capturenrendering#createcustomaudiotrack) 创建自定义音频采集轨道并将 `trackType` 设为 `AUDIO_TRACK_DIRECT`，调用 [`pushExternalAudioFrame`](/zh-CN/api-reference/rtc/android/audio/audio-custom-capturenrendering#api_irtcengine_pushaudioframe2) 将自采集音频推送到频道内，然后调用 [`playEffect`](/zh-CN/api-reference/rtc/android/play/audio-effect-file#api_irtcengine_playeffect3)[2/2] 播放音效，频道内的观众听主播的音频有杂音。 - 集成了 SDK 的 App 在音视频互动过程中偶现主线程阻塞导致的 UI 卡顿。 - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/android/play/audio-mixing#api_irtcengine_startaudiomixing2)[2/2] 播放 EAC3 音频编码的 MP4 文件时偶现无声。 - 退出频道停止视频渲染后出现渲染内存泄漏。 - 调用 [`setCameraFocusPositionInPreview`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcamerafocuspositioninpreview) 设置手动对焦位置，摄像头拍摄缩放画面后，设置的对焦位置不准确。 - 调用 [`setExternalMediaProjection`](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_setexternalmediaprojection) 设置 SDK 外部的 MediaProjection 采集屏幕视频流，当屏幕变为横屏或竖屏时，发送的视频流宽、高没有随之变化。 - 调用 [`openWithMediaSource`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 并通过 `source` 参数将 `isLiveSource` 设为 `true` 并播放纯视频流，播放失败。 - 使用媒体播放器打开实际不存在的本地媒体文件时，播放器状态改变回调 [`onPlayerStateChanged`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) 不会报告 `PLAYER_STATE_FAILED`，不符合预期。 - 发送端传输多声道编码音频时，接收端偶现杂音。 - App 集成媒体播放器场景下，先后两次调用 `open` 打开不同媒体资源，第二次打开时，媒体播放器信息变化回调 [`onPlayerInfoUpdated`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerinfoupdated) 返回第一次媒体资源的信息，不符合预期。 - 调用 [`enableAudioVolumeIndication`](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 启用用户音量提示本地发流用户和远端用户音量相关信息，用户音量提示回调 `onAudioVolumeIndication` 返回的本地用户音量为 0。 - 音视频互通过程中偶现 App 卡死。 - 调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/android/extension#api_irtcengine_setextensionproperty) 设置 key 为 "makeup_options" 实现美妆效果失败。 - 发送端用户在光线较暗的环境中进行音视频互通，部分机型偶现本地预览的图像偏暗。 - App 调用 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/android/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 启用垫片推流功能，偶现发送端推流成功但是 [`onVideoPublishStateChanged`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 返回当前的发布状态不是 PUB_STATE_PUBLISHED，不符合预期。 - 多频道场景下，App 在调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 成功前调用 [`setupRemoteVideoEx`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengineex_setupremotevideoex) 初始化远端用户视图，偶现远端用户视图首帧图像显示延时大。 - 加入频道失败后，在没有调用 `leaveChannel` 离开频道的情况下，再次调用 `joinChannel` 加入频道时偶现崩溃。 ## v4.5.1 [#v451] 该版本于 2025 年 3 月 5 日发布。 :::warning[注意] - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.so` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.so` 库。 - 4.5.1 RTC SDK `libaosl.so` 库版本为 1.2.13。 ::: ### 新增特性 [#新增特性-4] #### AI 对话场景 [#ai-对话场景] 该版本新增了专为与[声网对话式 AI 引擎](/zh-CN/ai)创建的智能体互动设计的 `AUDIO_SCENARIO_AI_CLIENT` 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。 ### 问题修复 [#问题修复-7] 该版本修复了以下问题： - 集成 SDK 的 App 设置 `targetSdkVersion` 为 34，在 Android 14 系统上首次开启屏幕共享进行授权时出现崩溃。 - 同时加入两个及以上的频道，连续调用 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/android/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex)[1/2] 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。 - 使用媒体播放器时，调用 `pause` 暂停播放后，调用 `seek` 定位到指定播放位置、然后调用 `play` 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。 - 使用媒体播放器时，调用 [`switchSrc`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换媒体资源后，调用 [`getPlaySrc`](/zh-CN/api-reference/rtc/android/play/drm#api_imusicplayer_getplaysrc)[2/2] 获取当前正在播放的媒体资源的路径没有变化。 - 用户在特定机型上进行音视频互动并使用蓝牙耳机，偶现调整手机音量后改变的是媒体音量而非蓝牙音量。 - 音视频互动时，偶现接收端观看发送端画面出现黑屏。 - 在特定机型上，调用 [`setCameraExposureFactor`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcameraexposurefactor) 在设备的某个特定角度设置当前摄像头的曝光系数后，当设备移动到另一个角度时，偶现视频画面变暗。 - 播放 CDN 直播流时，直播流短暂中断后恢复，偶现播放画面长时间卡住。 - 在极速直播场景下，观众通过 `string` 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。 - 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。 ## v4.5.0 [#v450] 该版本于 2024 年 11 月 26 日发布。 ### 升级必看 [#升级必看-3] 该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 :::warning[注意] 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.so` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.so` 库。4.5.1 RTC SDK `libaosl.so` 库版本为 1.2.13。 ::: #### 强效视频降噪实现变更 [#强效视频降噪实现变更] 该版本调整了强效视频降噪的实现方式，删除了 `VIDEO_DENOISER_LEVEL_STRENGTH`，改为调用 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)[1/2] 启用视频降噪后，调用 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions)[1/2] 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)[1/2]。 此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 [`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)[1/2]。 #### 视频编码偏好变更 [#视频编码偏好变更] 为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好： - 在 [`COMPRESSION_PREFERENCE`](/zh-CN/api-reference/rtc/android/enum-compressionpreference) 枚举类中新增 `PREFER_COMPRESSION_AUTO` (-1) 枚举，并替代原有的 `PREFER_QUALITY` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `PREFER_LOW_LATENCY` 或 `PREFER_QUALITY`，以获得最佳的用户体验。 - 在 [`DEGRADATION_PREFERENCE`](/zh-CN/api-reference/rtc/android/enum-degradationpreference) 枚举类中新增 `MAINTAIN_AUTO` (-1) 枚举，并替代原有的 `MAINTAIN_QUALITY` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `MAINTAIN_FRAMERATE`、`MAINTAIN_BALANCED` 或 `MAINTAIN_RESOLUTION`，以获得最优的综合质量体验 (QoE)。 #### 16 KB 内存页大小 [#16-kb-内存页大小] 自 Android 15 起，系统新增了对 16 KB 内存页大小的支持，详见 [Support 16 KB page sizes](https://developer.android.com/guide/practices/page-sizes?hl=zh-cn)。为了保证 App 的稳定性和性能表现，自该版本起，SDK 支持 16 KB 内存页大小，确保可以在使用 4 KB 和 16 KB 内存页大小的设备上无缝运行，提升兼容性并避免崩溃。 ### 新增特性 [#新增特性-5] #### 高级美颜 [#高级美颜] 该版本新增以下两种高级美颜功能： - 美型：调用 [`setFaceShapeBeautyOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions)[1/2] 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 [`setFaceShapeAreaOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapeareaoptions)[1/2] 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。 - 美妆：调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/android/extension#api_irtcengine_setextensionproperty) 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。 有关美型和美妆的实现步骤，详见[实现高级美颜](/zh-CN/realtime-media/rtc/build/video/advanced-beauty)。 :::info[信息] 目前，高级美颜功能为**限时免费**，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 秀场直播场景 [#秀场直播场景] 该版本在 [`VideoScenario`](/zh-CN/api-reference/rtc/android/enum-videoapplicationscenariotype) 类下新增枚举 `APPLICATION_SCENARIO_LIVESHOW`(3)（秀场直播），你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为[秀场直播](/zh-CN/solutions/showroom)。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，例如，默认开启音视频帧加速渲染来提升首帧出图体验，无需再额外调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_enableinstantmediarendering)，同时增强了在弱网环境和低端设备上的画质和流畅度表现。 #### 限制视频渲染帧率 [#限制视频渲染帧率] 该版本新增 [`setLocalRenderTargetFps`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_setlocalrendertargetfps) 和 [`setRemoteRenderTargetFps`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_setremoterendertargetfps) 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。 在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。 #### URL 拉流播放 [#url-拉流播放-1] URL 拉流播放功能主要用于直播场景，观众端可以直接通过 [`openWithUrl`](/zh-CN/api-reference/rtc/android/play/rte-player#api_player_openwithurl) 打开特定的 URL 来播放实时媒体流，无需显示调用加入频道、订阅等 API，极大简化了观众端观看直播流的 API 调用。 在播放的过程中，观众端可以通过 [`setAbrSubscriptionLayer`](/zh-CN/api-reference/rtc/android/play/rte-player#api_playerconfig_setabrsubscriptionlayer) 设置订阅视频大小流，并可以在大小流之间实现平滑切换。如果对视频体验有更高要求，可以[联系技术支持](https://ticket.shengwang.cn/)开通 ABR（Adaptive Bitrate，自适应码率）功能。启用该功能后，可以自定义不同层级的视频流分辨率，观众可以实现不同分辨率视频流的平滑切换。 当网络情况不稳定时，观众端可以调用 [`setAbrFallbackLayer`](/zh-CN/api-reference/rtc/android/play/rte-player#api_playerconfig_setabrfallbacklayer) 来设置订阅的视频流的回退选项。SDK 会以你指定的最低质量层级对应的视频流分辨率为下限，在此范围内根据网络状况动态调整分辨率。实现细节详见[观众端 URL 拉流](/zh-CN/realtime-media/rtc/build/optimize-and-operate/playing-url)。 #### 滤镜效果 [#滤镜效果] 该版本新增 [`setFilterEffectOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setfiltereffectoptions)[1/2] 方法，你可以在 **config** 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 `built_in_whiten_filter.cube` 文件，用于快速实现美白滤镜效果。 #### 本地音频合流 [#本地音频合流] 该版本新增本地音频合流功能，你可以调用 [`startLocalAudioMixer`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/audiomixer#api_irtcengine_startlocalaudiomixer) 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 [`stopLocalAudioMixer`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/audiomixer#api_irtcengine_stoplocalaudiomixer) 方法停止本地音频合流；在合流过程中，可以调用 [`updateLocalAudioMixerConfiguration`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/audiomixer#api_irtcengine_updatelocalaudiomixerconfiguration) 方法更新正在合流的音频流配置。 该功能的使用场景示例如下： - 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。 - 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。 - 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。 #### 外部 MediaProjection [#外部-mediaprojection] 该版本新增 [`setExternalMediaProjection`](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_setexternalmediaprojection) 方法，该方法支持你自行设置外部 `MediaProjection`，并取代 SDK 申请的 `MediaProjection`。 如果你具备自行申请 `MediaProjection` 的开发能力，可通过该功能实现更加灵活的屏幕采集。 #### EGL 环境上下文 [#egl-环境上下文] 该版本新增了 [`setExternalRemoteEglContext`](/zh-CN/api-reference/rtc/android/video/video-custom-capturenrendering#api_irtcengine_setexternalremoteeglcontext) 方法，用于设置远端视频流渲染的 EGL 环境上下文。使用 Texture 格式的视频数据进行远端视频自渲染时，你可以通过该方法替换 SDK 默认的远端 EGL 环境上下文，实现统一的 EGL 上下文管理。 #### 色彩空间设置 [#色彩空间设置] 该版本在 `VideoFrame` 和 `ExternalVideoFrame` 中新增了 **colorSpace**，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。 ### 改进 [#改进-4] #### 虚拟背景算法优化 [#虚拟背景算法优化] 该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。 #### 录制本地预览视频 [#录制本地预览视频] 该版本在 [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/android/class-recorderstreaminfo) 中新增 **type** 成员。当调用 [`createMediaRecorder`](/zh-CN/api-reference/rtc/android/recording#api_irtcengine_createmediarecorder) 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 [`MediaRecorderConfiguration`](/zh-CN/api-reference/rtc/android/class-mediarecorderconfiguration) 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 [`startRecording`](/zh-CN/api-reference/rtc/android/recording#api_imediarecorder_startrecording) 即可开始录制本地预览的视频。 #### 指定视频观测位置截图 [#指定视频观测位置截图] 该版本新增 [`takeSnapshot`](/zh-CN/api-reference/rtc/android/video/video-prenpro/snapshot#api_irtcengine_takesnapshot2)[2/2] 和 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/android/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex2)[2/2] 方法，你可以在调用该方法时通过 **config** 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。 #### 自定义音频采集改进 [#自定义音频采集改进] 该版本在 [`AudioTrackConfig`](/zh-CN/api-reference/rtc/android/class-audiotrackconfig) 中新增了 `enableAudioProcessing` 成员参数，用于控制是否对 `AUDIO_TRACK_DIRECT` 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 `false`，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。 #### 其他改进 [#其他改进-2] - 通过拼接视频帧和 Alpha 数据实现 Alpha 透明特效的应用场景下，提升了接收端的渲染性能，有效减少卡顿和延迟。 - 优化了调用 [`queryDeviceScore`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_querydevicescore) 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。 - 调用 [`switchSrc`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 [`onPlayerEvent`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent) 回调报告 `PLAYER_EVENT_SWITCH_ERROR` 事件，表示媒体资源切换时发生错误。 - 调用 `setPlaybackSpeed` 设置音频文件的播放速度时，最低支持 0.3 倍速播放。 ### 问题修复 [#问题修复-8] 该版本修复了以下问题： - 当发送端视频源类型为 JPEG 格式时，偶现接收端帧率低于预期。 - 在播放音乐内容中心的音乐资源时，偶现杂音和卡顿。 - 在 App 没有获取麦克风权限时，通过 [`IAgoraMusicPlayer`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer) 播放伴奏音乐偶现卡顿。 - 音视频互动过程中被系统来电打断后，通过 `onAudioVolumeIndication` 回调上报的用户音量错误。 - 在接收端默认订阅视频小流、加入频道时不自动订阅任何视频流的前提下，加入频道后调用 `muteRemoteVideoStream(uid,false)` 恢复接收视频流，但接收到的视频流为视频大流，不符合预期。 - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/android/play/audio-mixing#api_irtcengine_startaudiomixing)[1/2] 后，立即调用 [`pauseAudioMixing`](/zh-CN/api-reference/rtc/android/play/audio-mixing#api_irtcengine_pauseaudiomixing) 暂停播放音乐文件不生效。 - 音视频互动过程中偶现崩溃。 ## v4.4.1 [#v441] 该版本于 2024 年 8 月 8 日发布。 ### 问题修复 [#问题修复-9] 修复了因上传错误导致 `io.agora.rtc:full-rtc-basic:4.4.0` 和 `io.agora.rtc:voice-rtc-basic:4.4.0` 在 Maven Central 上无法正常使用的问题。 ## v4.4.0 [#v440] 该版本于 2024 年 8 月 5 日发布。 ### 升级必看 [#升级必看-4] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 :::warning[注意] 自 v4.4.0 起，RTC SDK 提供 API 下架说明，包含各版本废弃及删除的 API 信息。详见 [API 下架说明](/zh-CN/api-reference/rtc/android/rtc-api-sunset)。 ::: 1. 为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的 [`ExtensionContext`](/zh-CN/api-reference/rtc/android/class-extensioncontext) 了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。 | 原有回调 | 现有回调 | | -------------------- | ---------------------- | | [`onEvent`](/zh-CN/api-reference/rtc/android/play/rte-player#callback_playerobserver_onevent) | [`onEventWithContext`](/zh-CN/api-reference/rtc/android/extension#callback_irtcengineeventhandler_onextensioneventwithcontext) | | `onStarted` | [`onStartedWithContext`](/zh-CN/api-reference/rtc/android/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) | | `onStopped` | [`onStoppedWithContext`](/zh-CN/api-reference/rtc/android/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext) | | `onError ` | [`onErrorWithContext`](/zh-CN/api-reference/rtc/android/extension#callback_irtcengineeventhandler_onextensionerrorwithcontext) | 2. 该版本删除了 [`onMetadataReceived`](/zh-CN/api-reference/rtc/android/metadata/metadata-observer#callback_imetadataobserver_onmetadatareceived) 回调中的 `buffer`、`uid`、`timeStampMs` 参数，你可以通过新增的 `metadata` 参数来获取 Metadata 的相关信息，包括 `timeStampMs`（发送数据的时间戳）、`uid`（用户 ID）、`channelId`（源频道名称）等。 ### 新增特性 [#新增特性-6] #### Lite SDK [#lite-sdk] 自该版本起，声网推出 Lite 版 SDK，该 SDK 中仅包含音视频基础能力、对高阶音视频处理的功能进行部分裁剪，可有效减少集成 SDK 后的 App 体积。 - Lite SDK 支持手动集成或三方仓库集成，详见[下载](/zh-CN/realtime-media/rtc/reference/downloads)和[集成 SDK](/zh-CN/realtime-media/rtc/get-started/quick-start#集成-sdk)。 - Lite SDK 包含的动态库信息详见[减小 App 体积](/zh-CN/realtime-media/rtc/build/optimize-and-operate/reduce-app-size)。 - Lite SDK 支持的 API 清单详见 [Lite SDK API 列表](/zh-CN/api-reference/rtc/android/rtc-lite-api)。 - 使用 Lite SDK 播放媒体文件时的限制和注意事项详见 [RTC SDK 支持播放哪些格式的音频文件？](/zh-CN/reference/faq/product/audio_format) :::warning[注意] Lite SDK 默认无法与 [RTC 小程序 SDK](/zh-CN/realtime-media/rtc) 互通。如果需要与小程序互通，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: #### Alpha 透明特效 [#alpha-透明特效] 该版本新增 Alpha 透明特效功能，支持在 SDK 采集和自定义采集视频的场景下，在发送端发布视频帧的 Alpha 通道、在接收端对 Alpha 通道进行渲染处理，实现透明礼物特效、接收端自定义主播背景等： - [`VideoFrame`](/zh-CN/api-reference/rtc/android/class-videoframe) 和 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/android/class-externalvideoframe) 中新增 `alphaBuffer`：设置 Alpha 通道数据。 - [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/android/class-externalvideoframe) 中新增 `fillAlphaBuffer`：对于 BGRA 或 RGBA 格式的视频数据，设置是否自动提取 Alpha 通道数据并填入到 `alphaBuffer` 中。 - [`VideoFrame`](/zh-CN/api-reference/rtc/android/class-videoframe) 和 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/android/class-externalvideoframe) 中新增 `alphaStitchMode`：设置 `alphaBuffer` 和视频帧拼接的相对位置。 另外，[`AdvanceOptions`](/zh-CN/api-reference/rtc/android/class-advanceoptions) 中新增成员 `encodeAlpha`，用于设置是否将 Alpha 信息编码并发送到远端。SDK 默认不对 Alpha 信息进行编码发送；如果需要对 Alpha 信息编码发送至远端（例如开启了虚拟背景功能），请显式调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 设置视频编码属性，并将 `encodeAlpha` 设置为 `true`。 :::info[信息] 如需了解在各场景下实现 Alpha 特效的最佳实践，详见[实现 Alpha 透明特效](/zh-CN/realtime-media/rtc/build/video/alpha-effect)。 ::: #### AI 调音器 [#ai-调音器] 该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 [`enableVoiceAITuner`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/audio-effect#api_irtcengine_enablevoiceaituner) 方法并传入 [`VOICE_AI_TUNER_TYPE`](/zh-CN/api-reference/rtc/android/enum-voiceaitunertype) 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。 #### 版权音乐优化 [#版权音乐优化] - 该版本在 [`IAgoraMusicPlayer`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer) 类下新增 [`setPlayMode`](/zh-CN/api-reference/rtc/android/play/drm#api_imusicplayer_setplaymode) 方法，用于设置音乐资源的播放模式。在在线 K 歌房等场景下，你可以根据需求启用伴唱、原唱或导唱模式。 - 该版本废弃了 [`IAgoraMusicPlayer`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer) 类下的 `destroy`[1/2] 方法。如需销毁音乐播放器，请改用[`IAgoraMusicContentCenter`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter) 类下新增 [`destroyMusicPlayer`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_destroymusicplayer) 方法。 #### 1v1 视频通话场景 [#1v1-视频通话场景] 该版本在 [`VideoScenario`](/zh-CN/api-reference/rtc/android/enum-videoapplicationscenariotype) 类下新增枚举 `APPLICATION_SCENARIO_1V1`（1v1 视频通话）。你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。 ### 改进 [#改进-5] #### 自适应硬解支持 [#自适应硬解支持] 该版本新增自适应硬解支持，改进了低端机的渲染流畅性，有效降低系统负载。 #### 人脸区域美颜 [#人脸区域美颜] 为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。 #### 其他改进 [#其他改进-3] 该版本还进行了如下改进： - 优化了传输策略，调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_enableinstantmediarendering) 不再对传输链路的安全性产生影响。 - 废弃了冗余枚举值 `CLIENT_ROLE_CHANGE_FAILED_REQUEST_TIME_OUT`、`CLIENT_ROLE_CHANGE_FAILED_CONNECTION_FAILED`。 - 优化了以下 API 的参数类型。此改进有助于提升代码的可读性，减少潜在的错误，并便于后续维护。 - 废弃了 `option` 参数为 int 类型的 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_setremotesubscribefallbackoption)[1/2]，新增了 `option` 参数为 [`StreamFallbackOptions`](/zh-CN/api-reference/rtc/android/enum-streamfallbackoptions) 类型的重载函数 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_setremotesubscribefallbackoption2)[2/2]。 - 废弃了 `streamType` 参数为 int 类型的 [`setRemoteVideoStreamType`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setremotevideostreamtype)[1/2]、[`setRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype)[1/2]、[`setRemoteVideoStreamTypeEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_setremotevideostreamtypeex)[1/2]，新增了 `streamType` 参数为 [`VideoStreamType`](/zh-CN/api-reference/rtc/android/enum-videostreamtype) 类型的重载函数 [`setRemoteVideoStreamType`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setremotevideostreamtype2)[2/2]、[`setRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype2)[2/2]、[`setRemoteVideoStreamTypeEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_setremotevideostreamtypeex2)[2/2]。 ### 问题修复 [#问题修复-10] 该版本修复了以下问题： - 调用 [`pushExternalAudioFrame`](/zh-CN/api-reference/rtc/android/audio/audio-custom-capturenrendering#api_irtcengine_pushaudioframe2) 推送外部音频数据，外部音频渲染的采样率如果不是 SDK 推荐的值时，比如 22050 Hz 和 11025 Hz，声音播放失败。 ## v4.3.2 [#v432] 该版本于 2024 年 6 月 4 日发布。 ### 升级必看 [#升级必看-5] 该版本修改了播放版权音乐的行为，当调用 [`IAgoraMusicPlayer`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer) 中的 `play` 方法播放版权音乐媒体文件时，存在以下行为变更： - v4.3.2 以前版本：SDK 默认播放当前音频文件的第一个音轨。 - v4.3.2： SDK 默认播放伴奏。 ### 改进 [#改进-6] 1. 提升了 `setRemoteSubscribeFallbackOption` 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 `setRemoteSubscribeFallbackOption` 动态切换弱网环境下的音视频流回退选项。 2. 媒体播放器支持播放带有 Alpha 通道的 MP4 文件。 3. 媒体播放器全面支持播放 `/assets/` 目录下或以 `content://` 开头的音乐资源文件。 ### 问题修复 [#问题修复-11] 该版本修复了以下问题： - 音视频互动过程中偶现视频流畅度不佳。 - 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。 - 首次安装 App 或重启系统后，打开 App 并开启屏幕共享时出现崩溃。 - 接听系统电话时加入频道，挂断电话后，本地音频采集失败，远端用户听不到声音。 - 在部分机型（例如：红米 Note8）上进行互动的过程中接听系统来电并挂断后，本地播放媒体文件无声、听远端无声。 - 远端用户离开频道时偶现崩溃。 - 调用 [`queryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 返回的 [`AgoraFocalLengthInfo`](/zh-CN/api-reference/rtc/android/class-focallengthinfo) 中，`cameraDirection` 和 `focalLengthType` 的值无法被直接读取。 ## v4.3.1 [#v431] 该版本于 2024 年 4 月 29 日发布。 ### 升级必看 [#升级必看-6] 为确保参数命名的一致性，该版本该版本将 [`joinChannel`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_joinchannel)[1/2] 中的 `channelName` 改为 `channelId`，将 `optionalUid` 改为 `uid`。为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 ### 新增特性 [#新增特性-7] #### 摄像头广角和超广角 [#摄像头广角和超广角] 为了让用户捕捉到更宽阔的视野和更完整的画面内容，该版本新增了对广角和超广角摄像头的支持。你可以先调用 [`queryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 查询设备支持的焦距能力，然后调用 [`setCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 并将 `cameraFocalLengthType` 设置为支持的焦距类型，包括广角、超广角等。 #### 摄像头多路采集 [#摄像头多路采集] 该版本针对 Android 摄像头采集新增以下功能： 1. 支持第三个和第四个摄像头视频流的采集和发布。 - 在 [`VideoSourceType`](/zh-CN/api-reference/rtc/android/enum-videosourcetype) 中新增 `VIDEO_SOURCE_CAMERA_THIRD`(11) 和 `VIDEO_SOURCE_CAMERA_FOURTH`(12) 枚举，分别用于指定视频源为第三个和第四个摄像头。此项改动允许你在调用 [`startCameraCapture`](/zh-CN/api-reference/rtc/android/video/camera-capture#api_irtcengine_startcameracapture) 开启摄像头采集时，指定最多 4 路摄像头采集的视频流。 - 在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 中新增 `publishThirdCameraTrack` 和 `publishFourthCameraTrack` 成员。调用 [`joinChannel`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_joinchannel2)[2/2] 加入频道时，将这两个成员参数设置为 `true` 即可在频道内发布第三个和第四个摄像头采集的视频流。 2. 支持通过摄像头 ID 指定摄像头。 - 在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/android/class-cameracapturerconfiguration) 中新增 `cameraId` 成员。对于多摄像头的设备，`cameraDirection` 无法识别或访问全部可用摄像头。这种情况下，你可以通过 Android 原生系统 API 获取摄像头 ID，再调用 [`startCameraCapture`](/zh-CN/api-reference/rtc/android/video/camera-capture#api_irtcengine_startcameracapture) 并传入 `cameraId` 指定所需的摄像头。 - 新增 [`switchCamera`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_switchcamera2)[2/2]，支持通过 `cameraId` 切换摄像头，允许 App 在运行期间基于可用摄像头的实际情况动态调整摄像头使用。 #### 数据流加密 [#数据流加密] 该版本在 [`EncryptionConfig`](/zh-CN/api-reference/rtc/android/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` 成员用于启用数据流加密。你可以在调用 [`enableEncryption`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_enableencryption) 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` 和 `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` 枚举得知。 #### 本地视频渲染 [#本地视频渲染] 该版本在 [`VideoCanvas`](/zh-CN/api-reference/rtc/android/class-videocanvas) 中新增如下成员，以支持更多本地渲染功能。 - `surfaceTexture`：设置一个 Android 原生的 `SurfaceTexture` 对象作为提供视频图像的容器，然后使用 SDK 外部的方法自行实现 OpenGL 中的纹理绘制。 - `enableAlphaMask`：可以通过该成员设置接收端是否开启 Alpha 遮罩渲染。Alpha 遮罩渲染功能可以创建具有透明效果的图像或提取视频中的人像。 #### 视频小流自适应配置 [#视频小流自适应配置] 该版本新增视频小流的自适应配置功能，当你调用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2] 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示： - 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。 - 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。 #### 其他 [#其他-2] - 新增 [`enableEncryptionEx`](/zh-CN/api-reference/rtc/android/network#api_irtcengineex_enableencryptionex) 方法，用于多频道场景下开启媒体流或数据流加密。 - 新增 [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/android/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) 方法，用于设置音乐文件的播放速度。 - 新增 [`getCallIdEx`](/zh-CN/api-reference/rtc/android/network#api_irtcengineex_getcallidex) 方法，用于多频道场景下获取通话 ID。 ### 改进 [#改进-7] #### 本地视频状态回调优化 [#本地视频状态回调优化] 该版本新增如下枚举，你可以通过 [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调了解更多本地视频状态发生改变的原因： - `LOCAL_VIDEO_STREAM_REASON_DEVICE_INTERRUPT` (14)：由于摄像头被其他 App 占用或 App 切后台等原因导致的视频采集中断。 - `LOCAL_VIDEO_STREAM_REASON_DEVICE_FATAL_ERROR` (15)：视频采集设备出错，可能由于摄像头设备故障导致。 #### 摄像头采集改进 [#摄像头采集改进] 优化了摄像头采集的视频处理机制，减少噪点、提高亮度、改善色彩，使采集到的图形更加清晰、明亮和真实。 #### 虚拟背景算法优化 [#虚拟背景算法优化-1] 为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法： - 支持识别任意纯色背景，不再局限于绿幕。 - 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。 - 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。 #### 降低耳返的 CPU 消耗 [#降低耳返的-cpu-消耗] 该版本新增 `EAR_MONITORING_FILTER_REUSE_POST_PROCESSING_FILTER`(`1 << 15`) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。 #### 其他改进 [#其他改进-4] 该版本还进行了如下改进： - 提升了本地合图功能的性能和稳定性，并降低了该功能对 CPU 的占用率。 - 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。 - 新增 `ROOM_ACOUSTICS_CHORUS`（合唱音效），可使人声在合唱场景下更具空间立体感。 - 在 [`RemoteAudioStats`](/zh-CN/api-reference/rtc/android/class-remoteaudiostats) 中新增 `e2eDelay`，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。 ### 问题修复 [#问题修复-12] 该版本修复了以下问题： - 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。 - 加入频道后调用 [`disableAudio`](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_disableaudio) 关闭音频模块，音频播放没有立即停止。 - 主播使用部分型号设备在扬声器下进行音视频互动，之后切换 App 进程到后台再切回前台，偶现本地音频采集失败，远端用户听不到主播的声音。 - 在 Android 8.0 系统的设备上，启用屏幕共享功能时 App 偶现崩溃。 - 使用摄像头采集本地视频场景下，在 App 切后台时已调用 [`disableVideo`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_disablevideo) 或 [`stopPreview`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_stoppreview)[1/2] 关闭视频采集，但将 App 再切回前台时，摄像头采集被打开，不符合预期。 - 当发送端用户的网络环境恶化（例如弱网）时，接收端偶现视频流畅度降低、卡顿增加。 ### API 变更 [#api-变更] #### 新增 [#新增] - [`VideoCanvas`](/zh-CN/api-reference/rtc/android/class-videocanvas) 中新增 `surfaceTexture` 和 `enableAlphaMask` - `LOCAL_VIDEO_STREAM_REASON_DEVICE_INTERRUPT` - `LOCAL_VIDEO_STREAM_REASON_DEVICE_FATAL_ERROR` - [`EncryptionConfig`](/zh-CN/api-reference/rtc/android/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` - `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` - `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` - [`RemoteAudioStats`](/zh-CN/api-reference/rtc/android/class-remoteaudiostats) 新增 `e2eDelay` - `ERR_DATASTREAM_DECRYPTION_FAILED` - `ROOM_ACOUSTICS_CHORUS` - [`getCallIdEx`](/zh-CN/api-reference/rtc/android/network#api_irtcengineex_getcallidex) - [`enableEncryptionEx`](/zh-CN/api-reference/rtc/android/network#api_irtcengineex_enableencryptionex) - [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/android/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) - [`queryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) - [`AgoraFocalLengthInfo`](/zh-CN/api-reference/rtc/android/class-focallengthinfo) - [`CAMERA_FOCAL_LENGTH_TYPE`](/zh-CN/api-reference/rtc/android/enum-camerafocallengthtype) - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/android/class-cameracapturerconfiguration) 新增成员 `cameraFocalLengthType` - [`VideoSourceType`](/zh-CN/api-reference/rtc/android/enum-videosourcetype) 新增以下枚举： - `VIDEO_SOURCE_CAMERA_THIRD`(11) - `VIDEO_SOURCE_CAMERA_FOURTH`(12) - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 新增以下成员： - `publishThirdCameraTrack` - `publishFourthCameraTrack` - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/android/class-cameracapturerconfiguration) 新增成员 `cameraId` - [`CAMERA_DIRECTION`](/zh-CN/api-reference/rtc/android/enum-cameradirection) 中新增 `CAMERA_EXTRA`(2) - [`switchCamera`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_switchcamera2)[2/2] - `EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS`(`1 <<15`) ## v4.3.0 [#v430] 该版本于 2024 年 2 月 22 日发布。 ### 升级必看 [#升级必看-7] 该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 原始视频数据回调行为变更 [#原始视频数据回调行为变更] 自该版本起，原始视频数据相关的回调处理从原有的固定单线程变更为随机线程，即：回调处理可以在不同的线程上进行。由于 Android 系统限制，OpenGL 必须与线程强绑定，声网建议你采取以下两种方式之一修改你的代码： - （推荐）使用 `TextureBufferHelper` 类创建一个专门的 OpenGL 线程进行视频前处理或后处理（例如美颜、贴纸等效果）。 - 使用 `eglMakeCurrent` 方法，将每一个视频帧所需的 OpenGL 环境都关联到当前的线程中。 #### 回调中的参数改名 [#回调中的参数改名] 为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。 | 回调 | 原有参数名 | 现有参数名 | | --- | --- | --- | | [`onLocalAudioStateChanged`](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) | `error` | `reason` | | [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) | `error` | `reason` | | `onDirectCdnStreamingStateChanged` | `error` | `reason` | | [`onMusicChartsResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) | [`errorCode`](/zh-CN/api-reference/rtc/android/play/rte-player#api_rteexception_errorcode) | `reason` | | [`onPreLoadEvent`](/zh-CN/api-reference/rtc/android/play/drm#onpreloadevent) | [release-notes-android-html-0-5-1 details](#table-slot-release-notes-android-html-0-5-1) | [release-notes-android-html-0-5-2 details](#table-slot-release-notes-android-html-0-5-2) | | [`onMusicCollectionResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) | [`errorCode`](/zh-CN/api-reference/rtc/android/play/rte-player#api_rteexception_errorcode) | `reason` | | [`onLyricResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) | [`errorCode`](/zh-CN/api-reference/rtc/android/play/rte-player#api_rteexception_errorcode) | `reason` | | [`onSongSimpleInfoResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) | [`errorCode`](/zh-CN/api-reference/rtc/android/play/rte-player#api_rteexception_errorcode) | `reason` | | [`onPlayerStateChanged`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) | `error` | `reason` | | [`onRtmpStreamingStateChanged`](/zh-CN/api-reference/rtc/android/cloud-media-relay/media-push#callback_irtcengineeventhandler_onrtmpstreamingstatechanged) | `errCode` | `reason` | **release-notes-android-html-0-5-1 details** - `status` - `state` **release-notes-android-html-0-5-2 details** - [`errorCode`](/zh-CN/api-reference/rtc/android/play/rte-player#api_rteexception_errorcode) - `reason` | 原有枚举类 | 现有枚举类 | | -------------------------- | ----------------------------- | | `DirectCdnStreamingError` | `DirectCdnStreamingReason` | | `MediaPlayerError` | [`MediaPlayerReason`](/zh-CN/api-reference/rtc/android/enum-mediaplayerreason) | | `MusicContentCenterStatusCode` | [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/android/class-musiccontentcenterstatereason) | :::info[信息] 有关具体枚举的改名详见 [API 变更](#api-changes)。 ::: #### 跨频道媒体流转发 [#跨频道媒体流转发] 为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项： | 已删除的方法和回调 | 替代的方法和回调 | | --- | --- | | [release-notes-android-html-1-1-0 details](#table-slot-release-notes-android-html-1-1-0) | [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) | | [release-notes-android-html-1-2-0 details](#table-slot-release-notes-android-html-1-2-0) | [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) | | `onChannelMediaRelayEvent` | [`onChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) | **release-notes-android-html-1-1-0 details** - `startChannelMediaRelay` - `updateChannelMediaRelay` **release-notes-android-html-1-2-0 details** - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` #### 视频自采集 [#视频自采集] 该版本起，`pushExternalVideoFrameEx`[1/2] 和 `pushExternalVideoFrameEx`[2/2] 方法分别更名为 [`pushExternalVideoFrameById`](/zh-CN/api-reference/rtc/android/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe)[1/2] 和 [`pushExternalVideoFrameById`](/zh-CN/api-reference/rtc/android/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe3)[2/2] ，并从 [`RtcEngineEx`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex) 接口类迁移到 [`RtcEngine`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) 接口类。 #### 音频路由 [#音频路由] 该版本起，`ROUTE_BLUETOOTH` 更名为 `AUDIO_ROUTE_BLUETOOTH_DEVICE_HFP`，表示音频路由为使用 HFP 协议的蓝牙设备，新增 `AUDIO_ROUTE_BLUETOOTH_DEVICE_A2DP`(10) 表示音频路由为使用 A2DP 协议的蓝牙设备。 #### 远端视频流状态 [#远端视频流状态] 为使枚举的名称便于理解，该版本将 `REMOTE_VIDEO_STATE_PLAYING` 枚举名变更为 `REMOTE_VIDEO_STATE_DECODING`，枚举的含义不变。 #### 本地视频状态改变原因 [#本地视频状态改变原因] `LOCAL_VIDEO_STREAM_ERROR_ENCODE_FAILURE` 的枚举名变更为 `LOCAL_VIDEO_STREAM_REASON_CODEC_NOT_SUPPORT`。 #### 日志加密行为变更 [#日志加密行为变更] 出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案： - 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。 - 如有其他特殊需求，请[联系技术支持](https://ticket.shengwang.cn/)并附上对应的加密日志。 #### `IAgoraEventHandler` 接口类删除 [#iagoraeventhandler-接口类删除] 该版本删除了 `IAgoraEventHandler` 接口类，该类下的所有回调事件现均通过 [`IRtcEngineEventHandler`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) 接口类进行处理。 ### 新增特性 [#新增特性-8] #### 接收端自定义合图布局 [#接收端自定义合图布局] 为支持接收端自定义多路合图流的布局，该版本新增了 [`onTranscodedStreamLayoutInfo`](/zh-CN/api-reference/rtc/android/video/video-rendering#callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo) 回调。当接收端收到合图服务器发送的频道内合图视频流时，该回调会被触发，上报合图视频流的布局信息、以及合图流中每一路子视频流的布局信息。接收端可以在调用 [`setupRemoteVideo`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_setupremotevideo) 方法时，为合图视频流中的子视频流（通过 `subviewUid` 区分）设置单独的 `view` 进行渲染，从而达到自定义视频布局的效果。 当合图视频流中的子视频流布局发生变化时，该回调也会被触发，实时上报最新的布局信息。 通过该特性，接收端可以灵活调整本地的视图布局。当在多人视频场景下应用时，接收端只需接收并解码一路合图视频流，可以有效降低接收端解码多路视频时的 CPU 占用率和网络带宽。 :::info[信息] 关于该特性在多主播场景下的最佳实践，详见[多主播场景下的视频体验优化](/zh-CN/realtime-media/rtc/build/video/custom-layout)。 ::: #### 多视图本地预览 [#多视图本地预览] 该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下： 1. 调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第一个视图：在 [`VideoCanvas`](/zh-CN/api-reference/rtc/android/class-videocanvas) 中设置 `position` 参数为 `VIDEO_MODULE_POSITION_POST_CAPTURER_ORIGIN`（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。 2. 调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第二个视图：在 [`VideoCanvas`](/zh-CN/api-reference/rtc/android/class-videocanvas) 中设置 `position` 参数为 `VIDEO_MODULE_POSITION_POST_CAPTURER`，此处观测到的视频具备视频前处理的效果。 3. 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。 #### 查询设备评分等级 [#查询设备评分等级] 该版本新增 [`queryDeviceScore`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_querydevicescore) 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请[联系技术支持](https://ticket.shengwang.cn/)。 #### 本地播放及发布至远端的音轨控制 [#本地播放及发布至远端的音轨控制] 该版本新增 [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/android/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 [`openWithMediaSource`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并通过 [`MediaPlayerSource`](/zh-CN/api-reference/rtc/android/class-mediasource) 中新增的 `enableMultiAudioTrack` 成员来开启音轨控制。 #### 音频播放设备测试 [#音频播放设备测试] 该版本新增 [`startPlaybackDeviceTest`](/zh-CN/api-reference/rtc/android/device-management/audio-device#startplaybackdevicetest) 方法，用于在加入频道前测试音频播放设备能否正常工作。你可以通过 `testAudioFilePath` 参数指定需要播放的音频文件，测试者如果能听到声音，说明播放设备能正常工作。测试完毕后，你需要调用新增的 [`stopPlaybackDeviceTest`](/zh-CN/api-reference/rtc/android/device-management/audio-device#stopplaybackdevicetest) 方法停止测试。 #### 其他 [#其他-3] 该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。 - `setRemoteSubscribeFallbackOption`：设置弱网环境下订阅的音视频流回退选项。 - [`onRemoteSubscribeFallbackToAudioOnly`](/zh-CN/api-reference/rtc/android/network#callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly)：订阅流已回退为音频流或恢复为音视频流回调。 - [`setPlayerOption`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption) 和 [`setPlayerOptionString`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption2)：设置媒体播放器选项，用于提供技术预览或特别定制功能。 - [`enableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/android/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback)：设置是否在本地播放外部音频源。 ### 改进 [#改进-8] #### SDK 任务处理调度优化 [#sdk-任务处理调度优化] 该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面： - 远端及本地的首帧出图与出声速度提升了 10% 到 20%。 - API 的调用耗时和响应耗时缩短了 5% 到 50%。 - SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。 - SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。 #### 耳返音量提升 [#耳返音量提升] 该版本为用户提供更灵活的耳返音频调整选项，支持调用 [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/android/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) 将耳返音量设置为原始音量的 4 倍。 #### 空间音频易用性提升 [#空间音频易用性提升] - 该版本优化了 [`setZones`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 方法的设计，支持将 `zones` 参数设置为 `NULL`，表示清除所有隔声区域。 - 自该版本起，在调用 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) 中的方法之前，无需先取消订阅频道内所有远端用户的音频流。 #### 视频前处理方法优化 [#视频前处理方法优化] 该版本对以下 5 个视频前处理方法新增了带 `souceType` 参数的重载方法，支持通过传入 `sourceType` 来指定视频前处理特效应用的媒体源类型（例如应用在自定义的视频采集媒体源上）： - [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions2)[2/2] - [`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions2)[2/2] - [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions2)[2/2] - [`setColorEnhanceOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions2)[2/2] - [`enableVirtualBackground`](/zh-CN/api-reference/rtc/android/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground2)[2/2] #### 其他改进 [#其他改进-5] 该版本还进行了如下改进： - 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。 - [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/android/class-videoencoderconfiguration) 中新增 `codecType` 成员，用于设置视频编码类型。 - [`AudioCaptureParameters`](/zh-CN/api-reference/rtc/android/class-screenaudioparameters) 中新增 `allowCaptureCurrentApp` 成员，用于设置在屏幕共享时是否采集当前 App 中的音频。该成员默认值为 `true`，即：默认采集当前 App 中的音频。在个别场景下，屏幕共享采集到的 App 音频可能由于信号延迟等原因引起远端出现回声，声网建议你在此场景下将该成员设置为 `false`，以消除屏幕共享进程中引入的远端回声。 - 新增 [`onPlayerCacheStats`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) 回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。 - 新增 [`onPlayerPlaybackStats`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) 回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过 [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/android/class-playerplaybackstats) 来获取当前音、视频的码率等信息。 - [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/android/class-musiccontentcenterstatereason) 中新增状态码 `MUSIC_CONTENT_CENTER_STATE_REASON_HTTP_INTERNAL` 表示 HTTP 内部发生错误，请稍后重试。 - 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_setlocalaccesspoint) 解析域名时的稳定性。 - 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。 - [`LocalAudioStats`](/zh-CN/api-reference/rtc/android/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。 ### 问题修复 [#问题修复-13] 该版本修复了以下问题： - 当同时共享两路屏幕共享视频流时，[`onLocalVideoStats`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostats) 回调上报的 `captureFrameRate` 为 0，不符合预期。 - 会议场景下，本地听远端用户说话偶现卡顿。 ### API 变更 [#api-变更-1] #### 新增 [#新增-1] - [`onTranscodedStreamLayoutInfo`](/zh-CN/api-reference/rtc/android/video/video-rendering#callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo) - [`VideoLayout`](/zh-CN/api-reference/rtc/android/class-videolayout) - [`VideoCanvas`](/zh-CN/api-reference/rtc/android/class-videocanvas) 新增 `subviewUid` 和 `uid` 成员 - [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/android/class-videoencoderconfiguration) 新增 `codecType` 成员 - [`AudioCaptureParameters`](/zh-CN/api-reference/rtc/android/class-screenaudioparameters) 新增 `allowCaptureCurrentApp` 成员 - [`enableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/android/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback) - [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/android/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) - [`onPlayerCacheStats`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) - [`onPlayerPlaybackStats`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) - [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/android/class-playerplaybackstats) - [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/android/class-musiccontentcenterstatereason) 中新增 `MUSIC_CONTENT_CENTER_STATE_REASON_HTTP_INTERNAL` - [`startPlaybackDeviceTest`](/zh-CN/api-reference/rtc/android/device-management/audio-device#startplaybackdevicetest) - [`stopPlaybackDeviceTest`](/zh-CN/api-reference/rtc/android/device-management/audio-device#stopplaybackdevicetest) - [`LocalAudioStats`](/zh-CN/api-reference/rtc/android/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员 - [`queryDeviceScore`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_querydevicescore) - [`MediaSourceType`](/zh-CN/api-reference/rtc/android/enum-mediasourcetype) 中新增 `CUSTOM_VIDEO_SOURCE` 枚举 - [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions2)[2/2] - [`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions2)[2/2] - [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions2)[2/2] - [`setColorEnhanceOptions`](/zh-CN/api-reference/rtc/android/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions2)[2/2] - [`enableVirtualBackground`](/zh-CN/api-reference/rtc/android/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground2)[2/2] - 新增 `AUDIO_ROUTE_BLUETOOTH_DEVICE_A2DP` 枚举 #### 修改 [#修改] - `pushExternalVideoFrameEx`[1/2] 和 `pushExternalVideoFrameEx`[2/2] 方法分别更名为 [`pushExternalVideoFrameById`](/zh-CN/api-reference/rtc/android/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe)[1/2] 和 [`pushExternalVideoFrameById`](/zh-CN/api-reference/rtc/android/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe3)[2/2]，并从 [`RtcEngineEx`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex) 接口类迁移到 [`RtcEngine`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) 接口类 - `REMOTE_VIDEO_STATE_PLAYING` 枚举名变更为 `REMOTE_VIDEO_STATE_DECODING` - `ROUTE_BLUETOOTH` 枚举名变更为 `AUDIO_ROUTE_BLUETOOTH_DEVICE_HFP` - 以下枚举名中的 `ERROR` 字段全部修改为 `REASON`： - `LOCAL_AUDIO_STREAM_ERROR_OK` - `LOCAL_AUDIO_STREAM_ERROR_FAILURE` - `LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION` - `LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY` - `LOCAL_AUDIO_STREAM_ERROR_CAPTURE_FAILURE` - `LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE` - `LOCAL_VIDEO_STREAM_ERROR_OK` - `LOCAL_VIDEO_STREAM_ERROR_FAILURE` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY` - `LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE` - `LOCAL_VIDEO_STREAM_ERROR_CODEC_NOT_SUPPORT` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND` - `PLAYER_ERROR_NONE` - `PLAYER_ERROR_INVALID_ARGUMENTS` - `PLAYER_ERROR_INTERNAL` - `PLAYER_ERROR_NO_RESOURCE` - `PLAYER_ERROR_INVALID_MEDIA_SOURCE` - `PLAYER_ERROR_UNKNOWN_STREAM_TYPE` - `PLAYER_ERROR_OBJ_NOT_INITIALIZED` - `PLAYER_ERROR_CODEC_NOT_SUPPORTED` - `PLAYER_ERROR_VIDEO_RENDER_FAILED` - `PLAYER_ERROR_INVALID_STATE` - `PLAYER_ERROR_URL_NOT_FOUND` - `PLAYER_ERROR_INVALID_CONNECTION_STATE` - `PLAYER_ERROR_SRC_BUFFER_UNDERFLOW` - `PLAYER_ERROR_INTERRUPTED` - `PLAYER_ERROR_NOT_SUPPORTED` - `PLAYER_ERROR_TOKEN_EXPIRED` - `PLAYER_ERROR_UNKNOWN` - `RTMP_STREAM_PUBLISH_ERROR_OK` - `RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT` - `RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED` - `RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT` - `RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR` - `RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR` - `RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN` - `RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT` - `RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED` - `RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND` - `RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED` - `RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER` - `RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM` - `RTMP_STREAM_PUBLISH_ERROR_NET_DOWN` - `RTMP_STREAM_PUBLISH_ERROR_INVALID_PRIVILEGE` - `RTMP_STREAM_UNPUBLISH_ERROR_OK` - `MusicContentCenterStatusCode` 修改为 [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/android/class-musiccontentcenterstatereason)，其中的枚举名的 `STATUS_ERR` 字段全部修改为 `STATE_REASON`： - `MUSIC_CONTENT_CENTER_STATUS_ERR_GATEWAY` - `MUSIC_CONTENT_CENTER_STATUS_ERR_PERMISSION_AND_RESOURCE` - `MUSIC_CONTENT_CENTER_STATUS_ERR_INTERNAL_DATA_PARSE` - `MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_LOADING` - `MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_DECRYPTION` - `MUSIC_CONTENT_CENTER_STATUS_OK` 修改为 `MUSIC_CONTENT_CENTER_STATE_REASON_OK` - `MUSIC_CONTENT_CENTER_STATUS_ERR` 修改为 `MUSIC_CONTENT_CENTER_STATE_REASON_ERROR` #### 删除 [#删除] - `startChannelMediaRelay` - `updateChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - `onChannelMediaRelayEvent` ## v4.2.6 [#v426] 该版本于 2023 年 11 月 16 日发布。 ### 问题修复 [#问题修复-14] 该版本修复了在使用 Android 14 系统版本时可能出现的问题： - 在屏幕共享过程中切换横竖屏模式导致当前屏幕共享进程中断，需要在弹出窗口中点击确认录制屏幕才可重新开始屏幕共享。 - 在集成 SDK 时，如果将 Android `targetSdkVersion` 设置为 34，导致屏幕共享不可用甚至 App 崩溃。 - 先调用 [`startScreenCapture`](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_startscreencapture) 但不共享视频（设置 `captureVideo` 为 `false`）、后调用 [`updateScreenCaptureParameters`](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_updatescreencaptureparameters) 共享视频（设置 `captureVideo` 为 `true`）时，接收端看到的屏幕共享画面冻结。 - 采用横屏模式进行屏幕共享时，观众端看到的共享画面被拆分成两部分：一侧的画面被压缩；另一侧为黑屏。 该版本还修复了以下问题： - 在直播场景下，观众端看到的画面偶现变形。 - 在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。 ## v4.2.3 [#v423] 该版本于 2023 年 10 月 12 日发布。 ### 升级必看 [#升级必看-8] #### 兼容性变更 [#兼容性变更] 该版本优化了 SDK 采集和自定义视频采集场景下 Texture Buffer 的管理方式，有效消除丢帧和崩溃隐患。自该版本起，TextureBuffer 类型的纹理格式不再包括 OES 格式，仅为 RGB 格式。你需要在处理视频数据时增加对 I420、RGB 纹理格式的适配。 ### 新增特性 [#新增特性-9] #### 本地截图上传更新 [#本地截图上传更新] 为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动： - [`ContentInspectModule`](/zh-CN/api-reference/rtc/android/class-contentinspectmodule) 中的 `type` 新增 `CONTENT_INSPECT_TYPE_IMAGE_MODERATION` 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。 - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/android/class-contentinspectconfig) 中新增的 `serverConfig` 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请[联系技术支持](https://ticket.shengwang.cn/)。 此外，该版本还新增了 [`enableContentInspectEx`](/zh-CN/api-reference/rtc/android/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) 方法，支持同时对多条视频流截图并上传。 #### 进阶功能查询 [#进阶功能查询] 该版本新增了 [`isFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_isfeatureavailableondevice) 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。 在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。 此外，自该版本起，调用 `enableVirtualBackground` 和 `setBeautyEffectOptions` 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 `-4: ERR_NOT_SUPPORTED` 表示该设备不支持开启该功能。 ### 改进 [#改进-9] #### 优化虚拟背景内存占用 [#优化虚拟背景内存占用] 该版本升级了虚拟背景算法，降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。 #### 屏幕共享场景优化 [#屏幕共享场景优化] 该版本优化了屏幕共享场景下的视频编码配置。当用户自定义视频的 `width` 和 `height` 属性时，SDK 会在保持视频与屏幕的宽高比一致的前提下，对实际的编码分辨率进行向下取整，确保最终编码分辨率不超过用户自定义的编码分辨率，从而提升了对屏幕共享流的计费准确性。 #### 其他改进 [#其他改进-6] 该版本还进行了如下改进： - 当调用 `setPlaybackSpeed` 设置音频文件的播放速度时，传入非法参数后会返回错误码 `-2`，表示方法中设置了无效的参数，需要重新设置参数。 - 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。 ### 问题修复 [#问题修复-15] 该版本修复了以下问题： - 在采用 H.265 编码模式时，如果 Web 端加入互动，会导致 Native 端出现冗余的 [`onUserEnableLocalVideo`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onuserenablelocalvideo) 回调：当主播调用 `enableLocalVideo(true)`时，接收端在收到 [`onUserEnableLocalVideo`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onuserenablelocalvideo) (`enabled` 为 `true`) 回调之前，会先收到一个 [`onUserEnableLocalVideo`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onuserenablelocalvideo) (`enabled` 为 `false`) 回调。 - 本地系统时间不正确时，偶现加入频道失败。 - 调用 [`playEffect`](/zh-CN/api-reference/rtc/android/play/audio-effect-file#api_irtcengine_playeffect3)[2/2] 使用相同的 `soundId` 播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 - 主播调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/android/play/audio-mixing#api_irtcengine_startaudiomixing2)[2/2] 播放音乐文件时，偶现主播本地无法听见音乐，远端用户可以正常听见。 - 合唱场景下，调用 [`preload`](/zh-CN/api-reference/rtc/android/play/drm#api_imusicontentcenter_preload)[1/2] 加载音乐，偶现加载失败。 - 在特定机型上开启 AI 降噪偶现崩溃。 - 当本地系统时间不准确时，歌曲榜单加载失败。 - 调用一次 `takeSnapshotEx` 获取视频截图会收到多次 [`onSnapshotTaken`](/zh-CN/api-reference/rtc/android/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 视频截图结果回调。 - 在仅调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 加入的频道中，调用 [`setEnableSpeakerphone`](/zh-CN/api-reference/rtc/android/device-management/audio-route#api_irtcengine_setenablespeakerphone) 无法将音频路由从扬声器切换至听筒。 ### API 变更 [#api-变更-2] #### 新增 [#新增-2] - [`enableContentInspectEx`](/zh-CN/api-reference/rtc/android/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) - [`ContentInspectModule`](/zh-CN/api-reference/rtc/android/class-contentinspectmodule) 中的 `type` 新增 `CONTENT_INSPECT_TYPE_IMAGE_MODERATION` - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/android/class-contentinspectconfig) 中新增 `serverConfig` 可选参数 - [`isFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_isfeatureavailableondevice) ## v4.2.2 [#v422] 该版本于 2023 年 7 月 27 日发布。 ### 升级必看 [#升级必看-9] 该版本废弃了 [`IAgoraMusicContentCenter`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter) 类下的 [`preload`](/zh-CN/api-reference/rtc/android/play/drm#api_imusicontentcenter_preload)[1/2] 方法并新增 [`preload`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_preload2)[2/2] 方法。如果你使用了 [`preload`](/zh-CN/api-reference/rtc/android/play/drm#api_imusicontentcenter_preload)[1/2] 方法实现预加载音乐资源，请在升级到该版本后更新 App 代码。 ### 新增特性 [#新增特性-10] #### 通配 Token [#通配-token] 该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 :::warning[注意] 声网 4.x RTC SDK 均支持使用通配 Token。 ::: #### 预加载频道 [#预加载频道] 该版本新增 `preloadChannel`[1/2] 和 `preloadChannel`[2/2] 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。 在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 #### 自定义视频画布背景颜色 [#自定义视频画布背景颜色] 该版本在 [`VideoCanvas`](/zh-CN/api-reference/rtc/android/class-videocanvas) 中增加了 `backgroundColor` 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。 #### 支持仅播放副歌片段 [#支持仅播放副歌片段] 该版本新增 [`getInternalSongCode`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getinternalsongcode) 方法，如果你仅需要播放某一音乐资源的副歌片段，在播放前你需要调用该方法来为该副歌片段创建一个内部歌曲编号，作为该资源的唯一标识。你可以查看[在线 K 歌房文档](/zh-CN/solutions/online-ktv)了解更多 K 歌场景方案。 ### 改进 [#改进-10] #### 摄像头采集效果提升 [#摄像头采集效果提升] 该版本支持摄像头采集曝光调节。新增 [`isCameraExposureSupported`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_iscameraexposuresupported) 和 [`setCameraExposureFactor`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcameraexposurefactor) 方法，用于查询当前设备是否支持曝光调节和设置摄像头的曝光增益。 #### 虚拟背景算法升级 [#虚拟背景算法升级] 该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。 #### 跨频道连麦优化 [#跨频道连麦优化] 该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 时，你可以指定最多 6 个目标频道。 #### 视频编解码查询能力增强 [#视频编解码查询能力增强] 为提升设备编解码能力查询功能，该版本在 [`CodecCapInfo`](/zh-CN/api-reference/rtc/android/class-codeccapinfo) 中新增 `codecLevels` 成员。当成功调用 [`queryCodecCapability`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_querycodeccapability) 后，可通过 `codecLevels` 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。 #### 其他改进 [#其他改进-7] - 为了提升多种音频路由之间的切换体验，该版本新增了 [`setRouteInCommunicationMode`](/zh-CN/api-reference/rtc/android/device-management/audio-route#api_irtcengine_setrouteincommunicationmode) 方法，用于在通话音量模式 ([`MODE_IN_COMMUNICATION`](https://developer.android.google.cn/reference/kotlin/android/media/AudioManager?hl=en#mode_in_communication)) 下，将音频路由从蓝牙耳机切换为听筒、有线耳机或扬声器。 - 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。 - 为帮助用户了解更多类型的远端视频状态改变的原因，[`onRemoteVideoStateChanged`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调中新增了 `REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT` 枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。 - 版权音乐新增 [`getSongSimpleInfo`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getsongsimpleinfo) 方法，可用于获取某一指定歌曲的详细信息，你可以通过触发的 [`onSongSimpleInfoResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) 回调来获取歌曲信息。 ### 问题修复 [#问题修复-16] 该版本修复了以下问题： - 网络异常导致频道连接断开后，频道连接恢复较慢。 - 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。 - 自采集场景下，`setBeautyEffectOptions`、`setLowlightEnhanceOptions`、`setVideoDenoiserOptions` 和 `setColorEnhanceOptions` 无法自动加载插件。 ### API 变更 [#api-变更-3] #### 新增 [#新增-3] - [`setCameraExposureFactor`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcameraexposurefactor) - [`isCameraExposureSupported`](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_iscameraexposuresupported) - `preloadChannel`[1/2] - `preloadChannel`[2/2] - [`updatePreloadChannelToken`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_updatepreloadchanneltoken) - [`getSongSimpleInfo`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getsongsimpleinfo) - [`onSongSimpleInfoResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) - [`getInternalSongCode`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getinternalsongcode) - [`preload`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_preload2)[2/2] - [`onLyricResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 中增加 `songCode` - [`onPreLoadEvent`](/zh-CN/api-reference/rtc/android/play/drm#onpreloadevent) 中增加 `requestId` - [`setRouteInCommunicationMode`](/zh-CN/api-reference/rtc/android/device-management/audio-route#api_irtcengine_setrouteincommunicationmode) - [`CodecCapLevels`](/zh-CN/api-reference/rtc/android/class-codeccaplevels) - `VideoCodecCapLevel` - [`VideoCanvas`](/zh-CN/api-reference/rtc/android/class-videocanvas) 中增加 `backgroundColor` 成员 - [`CodecCapInfo`](/zh-CN/api-reference/rtc/android/class-codeccapinfo) 中增加 `codecLevels` 成员 - 增加 `REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT` 枚举 #### 废弃 [#废弃] - [`preload`](/zh-CN/api-reference/rtc/android/play/drm#api_imusicontentcenter_preload)[1/2] ## v4.2.1 [#v421] 该版本于 2023 年 6 月 21 日发布。 ### 改进 [#改进-11] 该版本改进了网络传输策略，提升了音视频交互的流畅度。 ### 问题修复 [#问题修复-17] 该版本修复了以下问题： - SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。 - 发送端调用 [`setAINSMode`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。 - 屏幕共享场景下，部分机型必现接收端看到共享的画面卡顿。 ## v4.2.0 [#v420] 该版本于 2023 年 5 月 24 日发布。 ### 升级必看 [#升级必看-10] 该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。 #### 视频数据获取 [#视频数据获取] - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调中新增了 `sourceType` 参数，用于表示具体的视频源类型。 - 以下回调已删除，请通过 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 和 [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 中的 `sourceType` 参数得知视频源类型。 - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` #### 媒体发布选项 [#媒体发布选项] - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` 已删除，请改用 `publishCustomAudioTrack`。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 中的成员 `publishTrancodedVideoTrack` 变更为 `publishTranscodedVideoTrack`。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 中的成员 `publishCustomAudioSourceId` 变更为 `publishCustomAudioTrackId`。 #### 音视频录制 [#音视频录制] - 删除 `getMediaRecorder` 方法，可通过该版本新增的 [`createMediaRecorder`](/zh-CN/api-reference/rtc/android/recording#api_irtcengine_createmediarecorder) 方法来创建录制对象。 - 删除 [`startRecording`](/zh-CN/api-reference/rtc/android/recording#api_imediarecorder_startrecording) 、[`stopRecording`](/zh-CN/api-reference/rtc/android/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/android/recording#api_imediarecorder_setmediarecorderobserver) 中的 `connection` 参数。 - 删除 [`AgoraMediaRecorder`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imediarecorder) 类中的 `release ` 方法，你可直接调用该版本新增的 [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/android/recording#api_irtcengine_destroymediarecorder) 方法来销毁录制对象以释放资源。 #### 其他兼容性变更 [#其他兼容性变更] - `onApiCallExecuted` 已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。 - [`enableDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_enabledualstreammode)[1/2] 和 [`enableDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_enabledualstreammode3)[2/2] 已废弃，请改用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setdualstreammode)[1/2] 和 [`setDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2]。 - `startChannelMediaRelay`、`updateChannelMediaRelay`、`startChannelMediaRelayEx` 和 `updateChannelMediaRelayEx` 已废弃，请改用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex)。 ### 新增特性 [#新增特性-11] #### AI 降噪 [#ai-降噪] 该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 [`setAINSMode`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。 #### 增强虚拟背景 [#增强虚拟背景] 为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 `enableVirtualBackground` 方法时，将自定义背景设置为更多类型： - 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。 - 将背景替换为多种格式的本地视频。 #### 视频场景化设置 [#视频场景化设置] 该版本新增 [`setVideoScenario`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoscenario) 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化： - 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。 - 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。 #### 本地录制远端音视频 (Beta) [#本地录制远端音视频-beta] 该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 [`onRecorderStateChanged`](/zh-CN/api-reference/rtc/android/recording#callback_imediarecorderobserver_onrecorderstatechanged) 和 [`onRecorderInfoUpdated`](/zh-CN/api-reference/rtc/android/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数，用于表示录制的音视频流的具体信息，并新增 [`createMediaRecorder`](/zh-CN/api-reference/rtc/android/recording#api_irtcengine_createmediarecorder) 方法，用于创建本地或远端的录制对象。 你可以通过如下方法体验本地录制远端音视频功能： - [`createMediaRecorder`](/zh-CN/api-reference/rtc/android/recording#api_irtcengine_createmediarecorder)：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。 - [`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/android/recording#api_imediarecorder_setmediarecorderobserver)：设置录制回调对象。 - [`startRecording`](/zh-CN/api-reference/rtc/android/recording#api_imediarecorder_startrecording)：开始录制。 - [`stopRecording`](/zh-CN/api-reference/rtc/android/recording#api_imediarecorder_stoprecording)：停止录制。 - [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/android/recording#api_irtcengine_destroymediarecorder)：销毁录制对象。 #### 本地合图 [#本地合图] 该版本新增本地合图功能，用户可以调用 [`startLocalVideoTranscoder`](/zh-CN/api-reference/rtc/android/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) 方法，在本地将多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）混合和渲染，以实现自定义布局和效果。通过这项功能，你可以轻松创建个性化的视频显示效果，满足各种场景需求，如远程会议、直播、在线教育场景，同时支持人像画中画等功能。 另外，SDK 还提供了 [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/android/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 方法和 [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/android/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调。当你在开启本地合图后，可以调用 [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/android/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 更新合图的配置；当你在开启本地合图或者更新本地合图配置失败时，可通过 [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/android/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调得知合图失败的原因。 :::warning[注意] 本地合图对 CPU 的消耗较高，声网建议你在性能较高的设备上开启该功能。 ::: #### 多端同步 [#多端同步] 在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_getntpwalltimeinms) 方法获取当前的 NTP (网络时间协议) 时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。 ### 改进 [#改进-12] #### 优化变声 [#优化变声] 该版本新增了 [`setLocalVoiceFormant`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceformant) 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 [`setLocalVoicePitch`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch) 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。 #### 增强屏幕共享 [#增强屏幕共享] 该版本新增 [`queryScreenCaptureCapability`](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_queryscreencapturecapability) 方法，用于查询当前设备的屏幕捕获能力。如果你想在屏幕共享时启用高帧率（如 60 fps）、但不确定设备是否支持时，可以调用该方法、然后从返回值中得知设备支持的最高帧率是否满足需求。 该版本新增 [`setScreenCaptureScenario`](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_setscreencapturescenario) 方法，用于设置屏幕共享的场景类型，SDK 会根据场景类型自动调整共享画面的的流畅度和清晰度。 #### 提升音频文件类型兼容性 [#提升音频文件类型兼容性] 该版本提升了音频文件类型兼容性，你可以通过 [`startAudioMixing`](/zh-CN/api-reference/rtc/android/play/audio-mixing#api_irtcengine_startaudiomixing2)[2/2]、`playEffect`[3/3]、`open`[2/2]、[`openWithMediaSource`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 方法来打开以 `content://` 开头的 URI 文件。 #### 提升音视频同步能力 [#提升音视频同步能力] 针对自定义视频和音频采集场景，该版本新增 [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_getcurrentmonotonictimeinms) 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。 #### 优化多路摄像头采集 [#优化多路摄像头采集] 该版本新增 [`startCameraCapture`](/zh-CN/api-reference/rtc/android/video/camera-capture#api_irtcengine_startcameracapture) 方法，通过多次调用并指定 `sourceType` 参数可以同时开启多路摄像头采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头的场景。 #### 优化版权音乐 [#优化版权音乐] 针对在线 K 歌房场景，改版本新增 [`getCaches`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getcaches) 和 [`removeCache`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_removecache) 方法，用于获取、删除音乐资源缓存，并新增状态码和错误码，可方便用户排查问题。 #### 优化跨频道连麦 [#优化跨频道连麦] 该版本新增 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。 #### 多路音频自采集 [#多路音频自采集] 为更好地满足音频自采集的场景需求，该版本新增了 [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/android/audio/audio-custom-capturenrendering#createcustomaudiotrack) 和 [`destroyCustomAudioTrack`](/zh-CN/api-reference/rtc/android/audio/audio-custom-capturenrendering#destroycustomaudiotrack) 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性： - 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。 - 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。 ### 问题修复 [#问题修复-18] 该版本修复了以下问题： - 加入或退出频道时，安卓设备端偶现的崩溃。 - 当快速切换身份角色时，观众端听不到声音。 - 偶现耳返开启无效。 - 偶现回声。 - 由于 [`onRemoteAudioStateChanged`](/zh-CN/api-reference/rtc/android/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged) 回调异常造成客户端状态异常。 ### API 变更 [#api-变更-4] #### 新增 [#新增-4] - [`startCameraCapture`](/zh-CN/api-reference/rtc/android/video/camera-capture#api_irtcengine_startcameracapture) - [`stopCameraCapture`](/zh-CN/api-reference/rtc/android/video/camera-capture#api_irtcengine_stopcameracapture) - [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) - [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) - [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_getntpwalltimeinms) - [`setVideoScenario`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoscenario) - [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_getcurrentmonotonictimeinms) - [`startLocalVideoTranscoder`](/zh-CN/api-reference/rtc/android/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) - [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/android/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) - [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/android/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) - [`queryScreenCaptureCapability`](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_queryscreencapturecapability) - [`setScreenCaptureScenario`](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_setscreencapturescenario) - [`setAINSMode`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) - [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/android/audio/audio-custom-capturenrendering#createcustomaudiotrack) - [`destroyCustomAudioTrack`](/zh-CN/api-reference/rtc/android/audio/audio-custom-capturenrendering#destroycustomaudiotrack) - [`createMediaRecorder`](/zh-CN/api-reference/rtc/android/recording#api_irtcengine_createmediarecorder) - [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/android/recording#api_irtcengine_destroymediarecorder) - [`IAgoraMusicContentCenter`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter) 中新增如下方法： - [`getCaches`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getcaches) - [`removeCache`](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_removecache) - [`IAgoraMusicPlayer`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer) 中新增如下方法： - `open`[2/2] - `getPlaySrc` - [`stop`](/zh-CN/api-reference/rtc/android/play/rte-player#stop) - [`AudioTrackConfig`](/zh-CN/api-reference/rtc/android/class-audiotrackconfig) - [`AudioTrackType`](/zh-CN/api-reference/rtc/android/enum-audiotracktype) - [`MusicCacheInfo`](/zh-CN/api-reference/rtc/android/class-musiccacheinfo) - [`MusicCacheStatusType`](/zh-CN/api-reference/rtc/android/class-musiccachestatustype) - [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/android/class-recorderstreaminfo) - [`VideoScenario`](/zh-CN/api-reference/rtc/android/enum-videoapplicationscenariotype) - [`RtcEngineConfig`](/zh-CN/api-reference/rtc/android/class-rtcengineconfig) 中新增 `mDomainLimit` 和 `mAutoRegisterAgoraExtensions` 属性 - [`onRecorderStateChanged`](/zh-CN/api-reference/rtc/android/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`onRecorderInfoUpdated`](/zh-CN/api-reference/rtc/android/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数 - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 中增加 `sourceType` 参数 - [`MusicContentCenterConfiguration`](/zh-CN/api-reference/rtc/android/class-musiccontentcenterconfiguration) 中新增 `maxCacheSize` 属性 - `MUSIC_CONTENT_CENTER_STATUS_ERR_GATEWAY`(2) - `MUSIC_CONTENT_CENTER_STATUS_ERR_PERMISSION_AND_RESOURCE`(3) - `MUSIC_CONTENT_CENTER_STATUS_ERR_INTERNAL_DATA_PARSE`(4) - `MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_LOADING`(5) - `MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_DECRYPTION`(6) - `PRELOAD_STATUS_REMOVED`(3) - `BACKGROUND_NONE`(0) - `BACKGROUND_VIDEO`(4) #### 修改 [#修改-1] - [`onMusicChartsResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 中的 `status` 修改为 [`errorCode`](/zh-CN/api-reference/rtc/android/play/rte-player#api_rteexception_errorcode) - [`onMusicCollectionResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 中的 `status` 修改为 [`errorCode`](/zh-CN/api-reference/rtc/android/play/rte-player#api_rteexception_errorcode) - [`onLyricResult`](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 中的 `status` 修改为 [`errorCode`](/zh-CN/api-reference/rtc/android/play/rte-player#api_rteexception_errorcode) - [`onPreLoadEvent`](/zh-CN/api-reference/rtc/android/play/drm#onpreloadevent) 中的 `msg` 修改为 [`errorCode`](/zh-CN/api-reference/rtc/android/play/rte-player#api_rteexception_errorcode) #### 废弃 [#废弃-1] - [`enableDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_enabledualstreammode)[1/2] - [`enableDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_enabledualstreammode3)[2/2] - `startChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelay` - `updateChannelMediaRelayEx` - `onChannelMediaRelayEvent` #### 删除 [#删除-1] - `onApiCallExecuted` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` - `getMediaRecorder` - [`AgoraMediaRecorder`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imediarecorder) 类中的 `release ` - [`startRecording`](/zh-CN/api-reference/rtc/android/recording#api_imediarecorder_startrecording)、[`stopRecording`](/zh-CN/api-reference/rtc/android/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/android/recording#api_imediarecorder_setmediarecorderobserver) 中的 `connection` - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` ## v4.1.1 [#v411] 该版本于 2023 年 2 月 8 日发布。 ### 升级必看 [#升级必看-11] 自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。 如果你想自定义视频编码分辨率，可调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法，重新设置视频编码参数配置中的视频编码分辨率。 :::warning[注意] 由于默认分辨率的提升，会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: ### 新增特性 [#新增特性-12] #### 快速出图出声 [#快速出图出声] 该版本新增 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_enableinstantmediarendering) 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。 #### 视频渲染数据打点 [#视频渲染数据打点] 该版本新增 [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_startmediarenderingtracing) 和 [`startMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/android/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告相关事件的信息。 声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/android/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。 ### 改进 [#改进-13] #### 视频观测器 [#视频观测器] 自该版本起，SDK 对 [`onRenderVideoFrame`](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 回调进行了优化，在不同的视频处理模式下返回值的意义不同： - 当视频处理模式为 `PROCESS_MODE_READ_ONLY` 时，返回值无实际含义。 - 当视频处理模式为 `PROCESS_MODE_READ_WRITE` 时，返回 `true` 代表设置 SDK 接收视频帧；返回 `false` 代表设置 SDK 丢弃视频帧。 #### 超分辨率 [#超分辨率] 该版本提升了超分辨率的性能表现。为提升超分辨率易用性，该版本删除了 `enableRemoteSuperResolution`，超分辨率纳入画质增强线上策略的一部分，无需单独设置即可体验。 ### 问题修复 [#问题修复-19] 该版本修复了以下问题： - 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。 - 在红米 9A 上进行 CDN 推流，将推流的视频分辨率设置为 3840 × 2160 必现崩溃。 - 合唱模式下，OPPO R11 设备外放加入频道后，对端听到明显杂声和回音。 - 本地音乐文件结束播放时，未能触发 [`onAudioMixingFinished`](/zh-CN/api-reference/rtc/android/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingfinished) 回调。 - 接收端通过视频观测器接收的第一帧视频帧偶现丢包。 - 在多频道场景下开启屏幕共享，偶现远端看到的本地屏幕共享画面为黑屏。 - 开启虚拟背景时切换至后置摄像头会导致背景倒置。 - 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。 - 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。 ### API 变更 [#api-变更-5] #### 新增 [#新增-5] - [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_enableinstantmediarendering) - [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengine_startmediarenderingtracing) - [`startMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/android/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) - [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/android/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) - `MEDIA_RENDER_TRACE_EVENT` - [`VideoRenderingTracingInfo`](/zh-CN/api-reference/rtc/android/class-videorenderingtracinginfo) #### 删除 [#删除-2] - `enableRemoteSuperResolution` - [`RemoteVideoStats`](/zh-CN/api-reference/rtc/android/class-remotevideostats) 中删除 `superResolutionType` ## v4.1.0-1 [#v410-1] 该版本于 2022 年 12 月 19 日发布。 ### 新增特性 [#新增特性-13] #### 版权音乐 [#版权音乐] 为解决直播、语聊房、在线 K 歌房等场景下歌曲的应用版权问题，该版本新增版权音乐相关 API。你可以通过调用 [`IAgoraMusicContentCenter`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter) 类、[`IAgoraMusicPlayer`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer) 类、[`IMusicContentCenterEventHandler`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcentereventhandler) 类下的相关 API 实现在实时互动场景中播放版权音乐以及相关功能，例如检索音乐资源、获取音乐榜单及榜单详情、预加载及播放音乐资源、下载歌词及海报等功能。你还可以参考[在线 K 歌房](/zh-CN/solutions/online-ktv)来体验搭配了演唱评分、美声音效等一系列功能的线上 K 歌场景化解决方案。 #### 耳机均衡器 [#耳机均衡器] 该版本新增 [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) 方法，用于调节耳机均衡器的低频和高频参数，主要应用于空间音频场景。如果在调用 [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。 #### 已编码视频帧观测器 [#已编码视频帧观测器] 该版本新增 [`setRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) 和 [`setRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) 方法，当你调用 [`registerVideoEncodedFrameObserver`](/zh-CN/api-reference/rtc/android/video/video-encoded#registervideoencodedframeobserver) 方法为编码后的视频注册视频帧观测器时，SDK 默认订阅编码后的视频帧。如果你想要修改订阅选项，可以调用该新增的方法进行设置。 有关更多注册视频观测器和订阅选项的介绍，详见 [API 参考](/zh-CN/api-reference/rtc/android/video/video-encoded#registervideoencodedframeobserver)。 #### MPUDP (MultiPath UDP) [#mpudp-multipath-udp] 自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在移动端和桌面端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。 :::info[信息] 如果你希望体验该功能，请联系 sales@shengwang.cn。 ::: #### 摄像头采集选项 [#摄像头采集选项] 该版本在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/android/class-cameracapturerconfiguration) 中增加了 `followEncodeDimensionRatio` 成员，你可以在使用摄像头采集视频时，通过该成员设置是否跟随 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中已经设置的视频宽高比。 #### 多频道管理 [#多频道管理] 该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。 - 新增 [`muteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) 和 [`muteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) 方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增 [`muteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) 和 [`muteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) 方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增 [`startRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex)、[`startRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex)、[`updateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) 和 [`stopRtmpStreamEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) 方法，用于实现多频道场景下的旁路推流。 - 新增 `startChannelMediaRelayEx`、`updateChannelMediaRelayEx`、[`pauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex)、[`resumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) 和 [`stopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) 方法，用于实现多频道场景下的跨频道媒体流转发。 - 新增 [`leaveChannelEx`](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_leavechannelex2)[2/2] 方法，相较于 [`leaveChannelEx`](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_leavechannelex)[1/2] 方法新增了 `options` 参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。 #### 视频编码偏好 [#视频编码偏好] 一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/android/class-videoencoderconfiguration) 中新增 `advanceOptions` 成员，用于视频编码属性的进阶设置： - `compressionPreference`：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。 - `encodingPreference`：视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。 #### 日志上传 [#日志上传] 使用声网私有媒体服务器的场景下，为支持用户在调用 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_setlocalaccesspoint) 方法时的进阶设置，该版本在 [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/android/class-localaccesspointconfiguration) 类中新增 `advancedConfig` 成员参数，该参数支持如下设置： `logUploadServer`：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。 #### 用户角色切换 [#用户角色切换] 为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 [`onClientRoleChanged`](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调中新增 `newRoleOptions` 参数，该参数取值如下： - `AUDIENCE_LATENCY_LEVEL_LOW_LATENCY`(1): 低延时，属于极速直播。 - `AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY`(2): 超低延时，属于互动直播。 ### 改进 [#改进-14] #### 蓝牙权限 [#蓝牙权限] 为简化集成步骤，自该版本起，SDK 支持你在不添加 `BLUETOOTH_CONNECT` 权限的情况下，也能让 Android 用户正常使用蓝牙。 #### CDN 推流 [#cdn-推流] 为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 `onDirectCdnStreamingStats` 回调报告推送的视频流的实际分辨率。 #### 跨频道媒体流转发 [#跨频道媒体流转发-1] 该版本对 `updateChannelMediaRelay` 方法做了如下优化： - v4.1.0 前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码 `RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED`(8)，你需要重新调用 `updateChannelMediaRelay` 方法。 - v4.1.0 及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。 #### AIAEC [#aiaec] 该版本基于 AI 方法重构了AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。 #### 虚拟背景 [#虚拟背景] 该版本对虚拟背景算法做了如下优化： - 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。 - 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。 - 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。 - 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。 #### 其他改进 [#其他改进-8] - 降低了推送外部音频源时的上行延迟。 - 提升了会议场景 (`AUDIO_SCENARIO_MEETING`) 默认参数配置下的回声消除性能。 - 提升了 SDK 视频渲染的流畅度。 - 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。 ### 问题修复 [#问题修复-20] 该版本修复了以下问题： - 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。 - [`onVideoPublishStateChanged`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 回调报告的视频源类型不准确。 - 调用 `getExtensionProperty` 失败，返回空字符串。 - 当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。 ### API 变更 [#api-变更-6] #### 新增 [#新增-6] - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) - [`setRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) - [`setRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) - [`VideoSubscriptionOptions`](/zh-CN/api-reference/rtc/android/class-videosubscriptionoptions) - [`muteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) - [`muteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) - [`muteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) - [`muteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) - [`startRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex) - [`startRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex) - [`updateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) - [`stopRtmpStreamEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - [`pauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex) - [`resumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) - [`stopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/android/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) - [`leaveChannelEx`](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_leavechannelex2)[2/2] - [`enableAudioVolumeIndicationEx`](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengineex_enableaudiovolumeindicationex) - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/android/class-cameracapturerconfiguration) 中增加 `followEncodeDimensionRatio` - [`LocalVideoStats`](/zh-CN/api-reference/rtc/android/class-localvideostats) 中增加 `hwEncoderAccelerating` - [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/android/class-videoencoderconfiguration) 中增加 `advanceOptions` 成员 - [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/android/class-localaccesspointconfiguration) 中增加 `advancedConfig` 成员 - [`onClientRoleChanged`](/zh-CN/api-reference/rtc/android/channel#callback_irtcengineeventhandler_onclientrolechanged) 中增加 `newRoleOptions` - [`adjustUserPlaybackSignalVolumeEx`](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengineex_adjustuserplaybacksignalvolumeex) - [`IAgoraMusicContentCenter`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter) 接口类及其中方法 - [`IAgoraMusicPlayer`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer) 接口类及其中方法 - [`IMusicContentCenterEventHandler`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcentereventhandler) 接口类及其中回调 - [`Music`](/zh-CN/api-reference/rtc/android/class-music) 类 - [`MusicChartInfo`](/zh-CN/api-reference/rtc/android/class-musicchartinfo) 类 - [`MusicContentCenterConfiguration`](/zh-CN/api-reference/rtc/android/class-musiccontentcenterconfiguration) 类 - [`ClimaxSegment`](/zh-CN/api-reference/rtc/android/class-climaxsegment) 类 #### 废弃 [#废弃-2] - `onApiCallExecuted`，改用具体方法触发的回调。 #### 删除 [#删除-3] - 删除了 [`LiveTranscoding`](/zh-CN/api-reference/rtc/android/class-livetranscoding) 类中的废弃成员参数 `backgroundImage` 和 `watermark` - `onChannelMediaRelayEvent` 中删除 `RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED`(8) ## v4.0.1 [#v401] 该版本于 2022 年 9 月 29 日发布。 ### 升级必看 [#升级必看-12] 如果你已经使用了以下类或方法，请在升级到该版本后重新调用方法并更新参数设置。 该版本删除了 `enableDualStreamMode`[3/3] 和 [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_enabledualstreammodeex) 中的 `sourceType` 参数以及 `enableDualStreamMode`[2/3] 方法，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。 ### 新增特性 [#新增特性-14] #### 耳返 [#耳返] 该版本新增 [`getEarMonitoringAudioParams`](/zh-CN/api-reference/rtc/android/audio/audio-raw#getearmonitoringaudioparams) 回调，用于设置耳返音频数据格式，你可以使用自己的音效处理模块对耳返音频数据进行前处理，实现自定义音效。调用 `registerAudioFrameObserver` 注册音频观测器后，在 [`getEarMonitoringAudioParams`](/zh-CN/api-reference/rtc/android/audio/audio-raw#getearmonitoringaudioparams) 回调的返回值中设置耳返音频数据格式，SDK 会根据该回调的返回值计算采样间隔，并根据该采样间隔触发 [`onEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/android/audio/audio-raw#onearmonitoringaudioframe) 回调。 #### 音频采集设备测试 [#音频采集设备测试] 该版本支持加入频道前测试本地音频采集设备。你可以调用 [`startRecordingDeviceTest`](/zh-CN/api-reference/rtc/android/device-management/audio-device#startrecordingdevicetest) 开启音频采集设备测试，测试完成后，调用 [`stopPlaybackDeviceTest`](/zh-CN/api-reference/rtc/android/device-management/audio-device#stopplaybackdevicetest) 方法停止音频采集设备测试。 #### 本地网络连接类型 [#本地网络连接类型] 为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 [`getNetworkType`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_getnetworktype) 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 [`onNetworkTypeChanged`](/zh-CN/api-reference/rtc/android/network#callback_irtcengineeventhandler_onnetworktypechanged) 回调，报告当前的网络连接类型。 #### 音强选流 [#音强选流] :::info[信息] 如需开启音强选流功能，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: 该版本新增音强选流功能，该功能开启后，声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请[联系技术支持](https://ticket.shengwang.cn/)。 同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗，详见[音强选流](/zh-CN/realtime-media/rtc/build/audio/audio-stream-filter)。 #### 双流模式 [#双流模式] 该版本对双流模式做了优化，在加入频道前后均可调用 `enableDualStreamMode` 和 [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_enabledualstreammodeex)。 扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式（即：默认不主动发送小流），可通过以下步骤开启发送小流： 1. 接收端主播调用 `setRemoteVideoStreamType` 或 `setRemoteDefaultVideoStreamType` 发起接收小流申请。 2. 发送端收到申请后自动切换为发送小流模式。 如果你想修改上述发送端的默认行为，可以调用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setdualstreammode)[1/2] 或 [`setDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2] 方法，将 `mode` 参数设置为 `DISABLE_SIMULCAST_STREAM`（始终不发送小流）或 `ENABLE_SIMULCAST_STREAM`（始终发送小流）。 #### 空间音频 [#空间音频] 该版本新增了如下适用于空间音频场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。 - 隔声区域：你可以通过调用 [`setZones`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用 [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 和 [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) 方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖 [`setZones`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 中的声音衰减系数。 - 多普勒音效：你可以通过设置 [`SpatialAudioParams`](/zh-CN/api-reference/rtc/android/class-spatialaudioparams) 中的 `enable_doppler` 参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下（比如赛车游戏场景），接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用 [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 方法使用预设的耳机均衡效果，以改善耳机的听感。 ### 改进 [#改进-15] #### 视频信息发生改变回调 [#视频信息发生改变回调] 该版本优化了 [`onVideoSizeChanged`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged) 的触发逻辑，当单独调用 `startPreview` 时，也可触发该回调并上报本地视频大小发生改变。 ### 问题修复 [#问题修复-21] 该版本修复了以下问题： 1. 在频道内调用 [`setVideoEncoderConfigurationEx`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengineex_setvideoencoderconfigurationex) 将视频的分辨率调高时，偶现失效。 2. 在多人会议场景下，本地用户接听并挂断电话后，偶现本地用户和远端用户无法听见对方的声音。 3. 调用 [`setCloudProxy`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_setcloudproxy) 设置云代理后，调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 加入多频道失败。 8. 使用媒体播放器播放视频，先调用 `play` 再调用 `pause` 暂停播放后，调用 `seek` 指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用 [`resume`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-control#api_imediaplayer_resume) 恢复播放后，偶现视频画面出现快进。 ### API 变更 [#api-变更-7] #### 新增 [#新增-7] - [`getEarMonitoringAudioParams`](/zh-CN/api-reference/rtc/android/audio/audio-raw#getearmonitoringaudioparams) - [`startRecordingDeviceTest`](/zh-CN/api-reference/rtc/android/device-management/audio-device#startrecordingdevicetest) - [`stopRecordingDeviceTest`](/zh-CN/api-reference/rtc/android/device-management/audio-device#stoprecordingdevicetest) - [`getNetworkType`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_getnetworktype) - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 中新增 `isAudioFilterable` - [`setDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setdualstreammode)[1/2] - [`setDualStreamMode`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2] - [`setDualStreamModeEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_setdualstreammodeex) - [`SIMULCAST_STREAM_MODE`](/zh-CN/api-reference/rtc/android/enum-simulcaststreammode) - [`setZones`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) - [`muteRemoteAudioStream`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengine_muteremoteaudiostream) - [`SpatialAudioParams`](/zh-CN/api-reference/rtc/android/class-spatialaudioparams) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) #### 修改 [#修改-2] - `enableDualStreamMode`[3/3] - [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/android/publishnsubscribe#api_irtcengineex_enabledualstreammodeex) #### 废弃 [#废弃-3] - `startEchoTest`[2/3] #### 删除 [#删除-4] - `enableDualStreamMode`[2/3] ## v4.0.0 [#v400] 该版本于 2022 年 9 月 13 日发布。 ### 升级必看 [#升级必看-13] #### 兼容性变更 [#兼容性变更-1] v4.0.0 SDK 对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见[迁移指南](/zh-CN/realtime-media/rtc/reference/migration-guide)。 - 多频道 - 媒体流发布控制 - 自定义视频采集与渲染（Media IO 方式） - 警告码 #### 回调异常处理 [#回调异常处理] 自该版本起，为了方便开发者排查自身的集成问题，SDK 不再捕获开发者在 [`IRtcEngineEventHandler`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineeventhandler) 类回调中自行实现的代码逻辑中的异常。你需要自行处理该异常，否则异常出现时可能引起 App 崩溃。 ### 新增特性 [#新增特性-15] #### 多路媒体流 [#多路媒体流] 该版本通过设置 [`RtcEngineEx`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex) 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 实现一个 [`RtcEngine`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) 实例同时采集多组音视频流并发布到远端： 调用 `joinChannel` 加入首个频道后，多次调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 加入多个频道，通过不同的用户 ID (`localUid`) 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 设置发布指定的流到不同的频道。 同时，该版本支持通过 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/android/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流： 1. 创建自采集视频轨道：调用 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/android/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法创建一个自定义视频轨道，并获得视频轨道 ID。 2. 设置频道中待发布的自采集视频轨道：在每个频道的 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 中，将 `customVideoTrackId` 参数设置为你想要发布的视频轨道 ID，并将 `publishCustomVideoTrack` 设置为 `true`。 3. 推送外部视频源：调用 `pushExternalVideoFrameEx`，并将 `videoTrackId` 指定为步骤 2 中指定的视频轨道 ID，即可实现在多个频道中发布对应的自定义视频源。 结合多频道能力，你还可以体验如下功能： - 将多组音视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路音频流混音后通过一个用户 ID (`uid`) 发布到远端。 - 将多组视频频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路视频流合图后通过一个用户 ID (`uid`) 发布到远端。 #### 全高清和超高清分辨率 [#全高清和超高清分辨率] 为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持全高清 (FHD) 和超高清 (UHD) 视频分辨率。你可以在调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法时，将 `dimensions` 参数设置为 1920 × 1080 或更高的分辨率。如果你的设备不支持高分辨率，SDK 支持自动回退到适合的分辨率。 :::info[信息] - 超高清分辨率（4K，60 fps）目前为 Beta 功能，且对设备性能和网络带宽有一定要求，如需体验该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 - 高分辨率通常需要更高的性能消耗，为避免设备性能不足导致体验下降，声网建议你在性能较好的设备上开启全高清和超高清视频分辨率。 - 高分辨率可能会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 内置媒体播放器 [#内置媒体播放器] 为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 [`createMediaPlayer`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer) 创建媒体播放器后，你可以通过 [`IMediaPlayer`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imediaplayer) 类的一系列方法体验内置媒体播放器的各类功能： - 自动播放本地、在线、自定义的媒体资源。 - 预先加载待播放的媒体资源。 - 根据网络情况切换媒体资源的播放线路。 - 将媒体播放器的音视频流推送到任意频道、分享给远端用户。 - 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。 #### 新版 AI 降噪 [#新版-ai-降噪] 自该版本起，SDK 支持新版 AI 降噪（相对于 v3.7.0 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。 :::info[信息] 如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。 ::: #### 超高音质 [#超高音质] 为还原音频的细节、提升音频的清晰度，该版本新增 `ULTRA_HIGH_QUALITY_VOICE`。在语聊、歌唱等以人声为主的场景中，你可以调用 [`setVoiceBeautifierPreset`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) 并使用该枚举体验超高音质。 #### 空间音频 [#空间音频-1] :::warning[注意] 空间音频功能当前处于实验阶段，请联系 sales@shengwang.cn 开通空间音频功能，如果需要技术支持，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: 该版本支持对远端用户设置空间音频： - 本地直角坐标系计算方案: 该方案使用 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) 类实现空间音频，通过 SDK 计算远端用户的空间坐标。你需要分别调用 [`updateSelfPosition`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`updateRemotePosition`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音频。 ![](https://web-cdn.agora.io/docs-files/1646815293857) 该版本还支持对媒体播放器设置空间音频： - 本地直角坐标系计算方案: 该方案通过 SDK 计算媒体播放器的空间坐标。你需要在 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ilocalspatialaudioengine) 类中分别调用 [`updateSelfPosition`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`updatePlayerPositionInfo`](/zh-CN/api-reference/rtc/android/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateplayerpositioninfo) 更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音频。 ![](https://web-cdn.agora.io/docs-files/1646814580743) #### 实时合唱 [#实时合唱] 该版本为实时合唱赋予了如下能力： - 支持两人及两人以上合唱。 - 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。 - 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。 该版本新增 `AUDIO_SCENARIO_CHORUS` 枚举来设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。 #### 云市场插件 [#云市场插件] 为在声网 SDK 的基础上增强实时音视频互动性，该版本支持[声网云市场](https://www.agora.io/cn/marketplace)插件的一站式解决方案： - 方便集成：只需执行简单统一的 API 即可实现模块化功能的集成，将实时互动模块集成效率提高约 95%。 - 可扩展性设计：模块化和可扩展的 SDK 设计风格赋予了声网 SDK 良好的可扩展性，更有利于开发者基于声网云市场插件生态快速搭建好用的实时互动应用。 - 打造生态系统：可容纳众多开发者的实时音视频 App 社区，提供多种扩展组合。添加并开启云市场插件后，开发者可以实现更为丰富的实时音视频互动功能。 - 助力服务商：支持服务商将技术产品以插件的形式与声网 SDK 做技术上的融合，在声网云市场中展示并售卖，与声网一起共建开发者的实时互动生态系统。如何开发和发布插件详见[云市场-开发插件](/zh-CN/realtime-media/marketplace/build/create-extensions/publish)。 #### 增强的频道管理 [#增强的频道管理] 为满足各类业务场景对频道管理的需求，该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 结构体中新增了如下功能： - 设置或切换多种音视频源的发布 - 设置或切换频道场景、用户角色 - 设置或切换订阅视频的大小流类型 - 控制音频发布时延 在调用 `joinChannel` 或 [`joinChannelEx`](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 时设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions)，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_updatechannelmediaoptions) 随时更新 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/android/class-channelmediaoptions) 中的设置，例如，切换发布的音视频源。 #### 屏幕共享 [#屏幕共享] 该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享： - 在加入频道前调用 [`startScreenCapture`](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_startscreencapture)，然后调用 [`joinChannel`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_joinchannel2)[2/2] 加入频道并设置 `publishScreenCaptureVideo` 为 `true`，即可开始屏幕共享。 - 在加入频道后调用 [`startScreenCapture`](/zh-CN/api-reference/rtc/android/video/screencapture#api_irtcengine_startscreencapture)，然后调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_updatechannelmediaoptions) 设置 `publishScreenCaptureVideo` 为 `true`，即可开始屏幕共享。 #### 设置音视频流订阅黑/白名单 [#设置音视频流订阅黑白名单] 该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通 [`RtcEngineEx`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex) 类下的同名方法来实现该功能。 - `setSubscribeAudioBlacklist`：设置音频订阅黑名单。 - `setSubscribeAudioWhitelist`：设置音频订阅白名单。 - `setSubscribeVideoBlacklist`：设置视频订阅黑名单。 - `setSubscribeVideoWhitelist`：设置视频订阅白名单。 如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。 #### 设置音频场景 [#设置音频场景] 为方便用户灵活修改音频场景，该版本新增 [`setAudioScenario`](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_setaudioscenario) 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (`AUDIO_SCENARIO_DEFAULT`) 切换为高音质场景 (`AUDIO_SCENARIO_GAME_STREAMING`)，你可以调用该方法。 #### 设置本地代理 [#设置本地代理] 该版本新增 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_setlocalaccesspoint) 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。 #### 垫片推流 [#垫片推流] 该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/android/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 来开启该功能，并通过 `options` 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。 ### 改进 [#改进-16] #### 快速切换频道 [#快速切换频道] 该版本通过 `leaveChannel` 和 `joinChannel` 切换频道即可实现和 v3.7.0 中 `switchChannel` 一样的切换速度，无需额外调用 `switchChannel` 方法。 #### 推送外部视频帧 [#推送外部视频帧] 该版本新增支持推送 I422 格式的外部视频帧，你可以通过 [`pushExternalVideoFrame`](/zh-CN/api-reference/rtc/android/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe2)[1/2] 方法将 I422 格式的外部视频帧推送至 SDK。 #### 本地人声音调 [#本地人声音调] 该版本在 `onAudioVolumeIndication` 的 [`AudioVolumeInfo`](/zh-CN/api-reference/rtc/android/class-audiovolumeinfo) 中新增 `voicePitch` 参数。你可以通过 `voicePitch` 获取本地用户的人声音调，从而实现唱歌评分等业务功能。 #### 设备权限管理 [#设备权限管理] 该版本新增 [`onPermissionError`](/zh-CN/api-reference/rtc/android/network#callback_irtcengineeventhandler_onpermissionerror) 方法，当获取音频采集设备或摄像头权限开启失败时自动上报，用户可根据该回调的提示开启相应的设备权限。 #### 本地视频预览 [#本地视频预览] 该版本优化了 `startPreview` 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 `startPreview` 方法来开启视频预览，无调用时序要求。 #### 订阅视频流 [#订阅视频流] 你可以通过 `setRemoteDefaultVideoStreamType` 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" /> ### 已知问题和局限性 [#已知问题和局限性] **AirPods Pro 蓝牙连接问题** 由于 AirPods Pro 不支持在通话音量模式下使用 A2DP 协议，可能会导致该设备在该模式下无法成功连接。 ## v4.7.0 [#v470-1] 该版本于 2026 年 9 月 22 日发布。 ### 新增特性 [#新增特性-16] #### 声网高级美颜 2.1 [#声网高级美颜-21-1] 该版本支持声网高级美颜 2.1 API，并新增美颜人脸检测能力。使用声网高级美颜功能的客户可以检测人脸置信度。使用 RTC SDK v4.7.0 及以上版本集成声网高级美颜时，请参考[实现声网高级美颜](/zh-CN/realtime-media/rtc/build/video/advanced-beauty)；如果仍使用 RTC SDK v4.6.x，请继续参考[声网高级美颜 2.0 文档](/zh-CN/realtime-media/rtc/build/video/advanced-beauty-460)。 ### 改进 [#改进-17] #### 音视频链路性能优化 [#音视频链路性能优化-1] 该版本针对音视频链路与线程调度机制做了专项优化，显著降低各音视频场景 CPU 消耗，同步提升长时间运行稳定性。 #### 音频 SDK FFmpeg 插件集成优化 [#音频-sdk-ffmpeg-插件集成优化-1] 该版本调整了音频 SDK 中 FFmpeg player 插件的加载方式。`Agoraffmpeg.xcframework` 已调整为可选插件 `AgoraffmpegExtension.xcframework`。SDK 包中默认包含该插件，你可以根据业务需要选择是否集成。未加载 FFmpeg player 插件时，MediaPlayer 使用系统原生播放能力，实际支持的音频文件格式取决于系统支持的容器格式和音频编解码器；集成并加载 FFmpeg player 插件后，MediaPlayer 可支持更多音频格式和播放能力。 #### 视频首帧体验优化 [#视频首帧体验优化-1] 该版本优化了视频帧传输调度机制，提升了频道内首个用户订阅流的出图速度。 #### 1v1 连麦延时体验优化 [#1v1-连麦延时体验优化-1] 该版本优化了视频1v1等实时互动场景下的音视频策略，在保障画质的前提下改善端到端延迟，并提升突发抖动等弱网场景下的播放流畅性。 #### 音频场景码率优化 [#音频场景码率优化-1] 该版本优化了音频场景下的码率开销，保障音质的前提下提升了音频流传输效率。 #### 视频方向处理优化 [#视频方向处理优化] 该版本改进了横竖屏切换过程中的视频方向处理，降低设备旋转后视频 UI 旋转延迟或异常的概率。 #### 后台摄像头采集与重新开播体验优化 [#后台摄像头采集与重新开播体验优化] 该版本改进了 App 进入后台后的摄像头采集状态处理，解决主播重新开播时本地或远端画面偶现黑屏的问题。 #### Native 与 Web 互通弱网体验优化 [#native-与-web-互通弱网体验优化-1] 该版本优化了视频 1v1 弱网场景下 Native 与 Web 互通的音视频体验。 ### 问题修复 [#问题修复-22] 该版本修复了以下问题： - 修复了 iOS 26 上触发系统键盘语音转文字后，播放端低概率无声的问题。 - 修复了使用蓝牙音频设备上麦后，音频路由异常切换或远端音频无声的问题。 - 修复了聊天室上下麦场景中，先关闭本地音频、切换观众/主播角色后再开启本地音频时导致的低概率远端无声的问题。 - 修复了 AI QoS 配置下，通话刚开始时偶现首句音频丢字或异常的问题。 - 修复了音视频互动、屏幕共享、视频帧数据访问和音视频统计等场景下偶现 App 崩溃的问题，提升了 SDK 稳定性。 ## v4.6.4 [#v464-1] 该版本于 2026 年 8 月 31 日发布。 ### 升级必看 [#升级必看-14] #### iOS 27 横屏采集画面方向适配 [#ios-27-横屏采集画面方向适配] 在使用 Xcode 27 编译 App 并运行于 iOS 27.0 及以上系统时，由于声网 RTC SDK 旧版本依赖的界面方向相关系统 API，如 [`UIApplicationWillChangeStatusBarOrientationNotification`](https://developer.apple.com/documentation/uikit/uiapplication/willchangestatusbarorientationnotification)，在 iOS 27 中不再支持，导致 App 在横屏界面下启用摄像头采集时出现采集画面方向异常。本版本已使用新API完成适配。 更多信息请参考 Apple 的 [iOS & iPadOS 27 Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-27-release-notes)。 ### 问题修复 [#问题修复-23] 该版本修复了以下问题： - 修复了断网后 `onNetworkQuality` 回调报告的网络质量可能不准确的问题。 - 修复了接收端设置音频场景为`AUDIO_SCENARIO_AI_CLIENT`，发送端频繁停止和恢复发送音频流，当接收端网络不佳时偶现无声问题。 - 修复了使用有线耳机进行音视频互动时，在特定音频路由配置场景下偶现音质变差的问题。 - 修复了自渲染视频帧场景下，本地预览画面偶现卡住的问题。 - 修复了在 Android 模拟器上部分场景下偶现回声的问题。 - 修复了启用 Google 安全加固后，音视频互通过程中偶现 App 崩溃或无响应（ANR）的问题。 - 修复了 App 集成调用 `setExternalVideoSource` 设置推送的外部视频源类型为已编码的视频帧（`ENCODED_VIDEO_FRAME`），推送的已编码视频帧包含的 SEI 信息长度如果与编码协议规定不匹配，偶现崩溃问题。 - 修复了开启媒体播放器缓存后，在断网场景下播放已缓存资源时，可能延迟约 10 秒并回调错误的问题。 - 修复了 App 以通信模式（`CHANNEL_PROFILE_COMMUNICATION`）加入频道后，调用 `updateChannelMediaOptions` 更新频道媒体选项后，NCS 和 RESTful API 返回的频道信息被错误识别为互动直播模式的问题。 ## v4.6.2 [#v462-1] 该版本于 2026 年 1 月 16 日发布。 :::warning[注意] - 通过 CocoaPods 集成并升级至 v4.6.0 及以上版本时，除更新版本号外，还需将 Pod 名称从 `AgoraRtcEngine_iOS` 修改为 `ShengwangRtcEngine_iOS`。 - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `aosl.xcframework` 库。 - 4.6.2 RTC SDK `aosl.xcframework` 库版本为 1.3.5。 ::: ### 升级必看 [#升级必看-15] #### 支持自定义编码帧率 [#支持自定义编码帧率] 为支持更灵活的视频编码帧率设置，该版本将 `AgoraVideoEncoderConfiguration` 中 `frameRate` 参数的数据类型由枚举类型改成了 `Int`。在实际集成时，你可以参考原有 [`AgoraVideoFrameRate`](/zh-CN/api-reference/rtc/ios/enum-framerate) 枚举中的取值进行设置。 #### Lite 和 Voice 包中去除音频频谱功能 [#lite-和-voice-包中去除音频频谱功能-1] 为进一步优化 SDK 包体积，该版本将音频频谱（Audio Spectrum）功能从 Lite 和 Voice SDK 包中移除。如果你需要使用音频频谱功能，请集成完整 (Full) 包。 #### 关闭自动切换微距 [#关闭自动切换微距] 摄像头自适应切换微距可能会导致视频画面跳变。为避免该问题，该版本关闭了摄像头微距的自动切换功能。你仍可以根据业务或场景需要，通过私有参数设置手动切换摄像头微距。如有需要，可以[联系技术支持](https://ticket.shengwang.cn)。 #### 其他 [#其他-4] - 为保证整体解码兼容性，相关解码器插件已内置在 SDK 中。 - 从该版本起，SDK 默认不再支持 armv7 架构。如需支持该架构，可以[联系技术支持](https://ticket.shengwang.cn)。 ### 新增特性 [#新增特性-17] #### 支持多任务采集 [#支持多任务采集] 从 iOS 16 起，系统支持多任务处理，允许用户在多个 App 之间并行使用。常见的多任务模式包括[分屏显示 (Split views)](https://developer.apple.com/design/human-interface-guidelines/split-views)、[滑动叠放 (Slide over)](https://support.apple.com/en-gu/guide/ipad/ipadfe7c65e9/16.0/ipados/16.0)、[画中画 (Picture in picture)](https://support.apple.com/zh-cn/guide/iphone/iphcc3587b5d/ios) 和[台前调度 (Stage manager)](https://support.apple.com/zh-cn/guide/ipad/ipad1240f36f/ipados) 等。 从 v4.6.2 起，SDK 适配 iOS 的相机多任务采集能力，支持在多任务场景下持续进行音视频采集。在实时音视频互动场景中，启用该能力后，可支持例如视频通话过程中同时查阅资料、互动教学中分屏展示课件、直播过程中同时管理商品后台等业务场景。 在实际集成过程中，你需要先为 App 开启相机多任务采集能力，才能在多任务场景下正常使用相关功能。具体配置步骤请参考[如何开启 iOS 多任务相机采集](/zh-CN/reference/faq/integration/multitasking)。 经声网实验室测试，该功能支持的机型和系统版本如下： | 设备型号 | 芯片 | OS | 分屏显示 | 滑动叠放 | 画中画 | 台前调度 | | --- | --- | --- | --- | --- | --- | --- | | iPad Air 2 | A8X | iPadOS 14.7.1 | - | ✔ | - | - | | iPad Pro (10.5-inch) | A10X | iPadOS 15.0 | ✔ | ✔ | ✔ | ✔ | | iPad mini 第五代 | A12 | iPadOS 17.5.1 | ✔ | ✔ | ✔ | ✔ | | iPad Pro (11-inch) 第二代 | A12Z | iPadOS 18.4.1 | ✔ | ✔ | ✔ | ✔ | | iPad Pro (11-inch) 第三代 | M1 | iPadOS 17.6.1 | ✔ | ✔ | ✔ | ✔ | | iPhone 11 | A13 | iOS 16.1.1 | - | - | ✔ | - | #### Media Player 支持获取音频缓冲延迟 [#media-player-支持获取音频缓冲延迟-1] 为解决 K 歌场景中可能会出现的主唱与伴唱伴奏不同步的问题，该版本在 Media Player 模块中新增 [`getAudioBufferDelay`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-info#api_imediaplayer_getaudiobufferdelay) 方法，用于获取播放媒体文件时毫秒级的音频缓冲延迟。 ### 改进 [#改进-18] #### playEffect 支持无缝切换 [#playeffect-支持无缝切换-1] 该版本新增支持音效文件的无缝切换。对于同一个音效文件，如果先调用 `preloadEffect` 再调用 `playEffect`，在播放完成或通过 `stopEffect` 停止播放后，SDK 不会关闭该音效文件。当再次调用 `playEffect` 时，SDK 会直接复用已加载的文件进行播放，从而实现循环播放和无缝切换。该能力同样适用于多频道场景。 #### networkQuality 准确性提升 [#networkquality-准确性提升] 该版本提升了 `networkQuality` 回调中网络质量评估的准确性，使回调数据更贴近用户的主观体验。 #### onPlaybackAudioFrame 支持 24k 采样率的音频帧 [#onplaybackaudioframe-支持-24k-采样率的音频帧-1] 该版本在 `onPlaybackAudioFrame` 中新增支持采样率为 **24000 Hz** 的音频数据。在调用 [`setPlaybackAudioFrameParameters`](/zh-CN/api-reference/rtc/ios/audio/audio-raw#api_irtcengine_setplaybackaudioframeparameters) 设置播放音频数据格式时，可以将 `sampleRate` 设为 `24000`。 #### onEncodedVideoFrameReceived 回调支持获取频道 ID [#onencodedvideoframereceived-回调支持获取频道-id-1] 该版本在 `onEncodedVideoFrameReceived` 回调中新增 `channelId` 参数，方便你在获取编码后视频数据时识别其所属频道。 #### 其他 [#其他-5] - 新增错误码 `AgoraErrorCodePcmSendFormat (200)` 和 `AgoraErrorCodePcmSendBufferOverflow (201)`，用于报告 PCM 数据发送相关错误。 ### 问题修复 [#问题修复-24] 该版本修复了以下问题： - 美颜功能在部分场景下不生效。 - 当在子线程调用 `leaveChannel` 和 `destroy` 时，并同时发生 UI 方向切换时，可能导致 App 崩溃。 - 在 iOS 26 部分设备上，用户以主播身份在音频 Scenario 为 `AgoraAudioScenarioChatRoom` 的情况下加入频道，调用 `enableLocalAudio` 关闭本地音频采集后，无法调整通话音量。 - 在硬件异常的情况下切换视频分辨率时，偶现视频编码无输出帧，导致画面卡住的问题。 ## v4.6.0 [#v460-1] 该版本于 2025 年 8 月 18 日发布。 :::warning[注意] - 通过 CocoaPods 集成并升级至 v4.6.0 及以上版本时，除更新版本号外，还需将 Pod 名称从 `AgoraRtcEngine_iOS` 修改为 `ShengwangRtcEngine_iOS`。 - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `aosl.xcframework` 库。 - 4.6.0 RTC SDK `aosl.xcframework` 库版本为 1.3.0。你可以在 `Info.plist` 中查看库的版本信息。 ::: ### 升级必看 [#升级必看-16] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的废弃及删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 各版本废弃及删除的 API 信息。详见 [API 下架说明](/zh-CN/api-reference/rtc/ios/rtc-api-sunset)。 #### 直推 CDN 相关接口废弃 [#直推-cdn-相关接口废弃-1] 该版本废弃直推 CDN 功能的相关接口，并会在后续版本中删除，请改用[服务端旁路推流](/zh-CN/realtime-media/media-push)。 - `setDirectCdnStreamingAudioConfiguration:` - `setDirectCdnStreamingVideoConfiguration:` - `startDirectCdnStreaming:publishUrl:mediaOptions:` - `stopDirectCdnStreaming` - `AgoraDirectCdnStreamingMediaOptions` - `AgoraDirectCdnStreamingStats` - `AgoraDirectCdnStreamingState` - `AgoraDirectCdnStreamingReason` #### 虚拟节拍器接口废弃 [#虚拟节拍器接口废弃-1] 该版本废弃虚拟节拍器功能的相关接口，并会在后续版本中删除。 - [`startRhythmPlayer:sound2:config:`](/zh-CN/api-reference/rtc/ios/play/rhythmplayer#api_irtcengine_startrhythmplayer) - [`configRhythmPlayer:`](/zh-CN/api-reference/rtc/ios/play/rhythmplayer#api_irtcengine_configrhythmplayer) - [`rtcEngine:didRhythmPlayerStateChanged:reason:`](/zh-CN/api-reference/rtc/ios/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) #### 水印接口废弃 [#水印接口废弃-1] 该版本废弃水印功能的相关接口，推荐使用该版本新增的水印接口。 - [`addVideoWatermark:options:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2) - [`addVideoWatermarkEx:options:connection:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex) #### 冗余接口删除 [#冗余接口删除-1] 该版本删除了下列冗余接口及参数： - `setLocalPublishFallbackOption` - `didLocalPublishFallbackToAudioOnly` - `downlinkNetworkInfoUpdate` - `wlAccStats` - `wlAccMessage` - `enableWirelessAccelerate` - `AgoraWlAccReason` - `AgoraWlAccAction` - `AgoraWlAccStats` - [`AgoraRtcRemoteVideoStats`](/zh-CN/api-reference/rtc/ios/class-remotevideostats) 中删除 `receivedFrameRate` #### 美妆功能实现变更 [#美妆功能实现变更-1] 受美颜重构的影响，自 v4.6.0 起，不再支持调用 [`setExtensionPropertyWithVendor:extension:key:value:`](/zh-CN/api-reference/rtc/ios/extension#api_irtcengine_setextensionproperty) 启用美妆功能，改用 `STYLE_MAKEUP` 节点实现。 #### 默认日志路径修正 [#默认日志路径修正] 该版本将默认日志路径由 `AppSandbox/Library/documents/agorasdk.log` 修正为 `AppSandbox/Library/caches/agorasdk.log`。如果你是由 v4.3.1 及之后的版本升级到 v4.6.0，请改用修正后的路径查找日志。 #### 新增域名白名单 [#新增域名白名单-1] 如果你由之前的版本升级到 v4.6.0 且使用了域名白名单功能（`AgoraRtcEngineConfig` 下的 `domainLimit` 为 `YES`），请在白名单中添加以下域名，以确保互通顺畅： - `*.rtnsvc.com` - `*.realtimemesh.com` ### 新增特性 [#新增特性-18] #### 多路分辨率视频流 [#多路分辨率视频流-1] 该版本新增多路分辨率视频流（Adaptive Bitrate Video Streaming，简称 ABR）功能，支持对同一视频源设置同时发送多路不同分辨率的视频流，并支持多频道场景。接收端通过自动/手动订阅目标分辨率的视频流。 启用 ABR 后，你可以配置不同分辨率的视频流（最多四层分辨率，一个最高分辨率的主流和三层其他较低分辨率的视频流），并设置视频流的分辨率、码率、是否启用分层推流回退等选项来灵活控制流的发布。启用分层推流回退后，SDK 会在弱网环境下自动回退到低分辨率的视频流，确保流畅的观看体验。订阅端可根据实际需求选择想要接收的视频流。适用于会议场景、大班课、互动直播等多终端、多网络环境，可显著提升弱网下的观看体验。 具体实现方法以及和视频双流的对比可以参考进阶功能[发布多路视频流 (ABR)](/zh-CN/realtime-media/rtc/build/video/simulcast)。 #### 多路径网络传输 [#多路径网络传输-1] 该版本新增多路径传输功能，适用于终端支持多网卡传输(比如 5G， Wi-Fi，LAN)的设备，可以有效降低甚至消除弱网带来的体验回退，适用于弱网环境、对传输稳定性要求高的实时音视频通信场景，如车载、IoT、火车、高速公路等复杂网络环境。通过在 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中设置 `enableMultipath` 为 `YES`，可开启多路径传输能力。支持两种传输模式（[`AgoraMultipathMode`](/zh-CN/api-reference/rtc/ios/enum-multipathmode)）： - 动态模式：（默认）根据网络状况动态选择最佳路径进行传输，适用于流量敏感、对体验要求比较高的场景，如会议、教育等。动态模式下，你可以通过 `preferMultipathType` 指定首选的网络传输路径（如优先 Wi-Fi 或移动网络）。 - 全冗余模式：数据会在所有可用网络路径上同时传输，适用于流量不敏感，对体验有极致要求的场景，如户外采播、平行操控等。该模式会产生额外费用，如需使用请[联系技术支持](https://ticket.shengwang.cn/)。 上下行还可分别通过 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中的 `uplinkMultipathMode`、`downlinkMultipathMode` 配置。启用后，SDK 会通过回调 [`rtcEngine:multiPathStats:`](/zh-CN/api-reference/rtc/ios/network#callback_irtcengineeventhandler_onmultipathstats) 实时上报各路径的传输统计信息，包括每一个传输路径的流量消耗，便于开发者监控和优化网络表现。 #### 视频质量评分 [#视频质量评分-1] 该版本在 [`AgoraRtcRemoteVideoStats`](/zh-CN/api-reference/rtc/ios/class-remotevideostats) 中新增 `mosValue` 成员，报告声网实时视频 MOS（平均主观意见分）评估系统对接收到的远端视频流的质量评分。评分共有 5 个档次，5 分表示视频画质优秀，画面清晰无噪点，1 分表示视频画质极差，画面严重模糊。你可以通过该参数实时观测远端视频流的主观画质表现，便于动态调整视频参数、优化用户体验，或用于质量监控和告警等场景。如需启用该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 支持添加多个水印 [#支持添加多个水印-1] 该版本废弃了 [`addVideoWatermark:options:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2) 和 [`addVideoWatermarkEx:options:connection:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex) 方法，新增 [`addVideoWatermarkWithConfig`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/watermark#api_irtcengine_addvideowatermark3) 和 [`addVideoWatermarkEx3`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex1) 方法，支持通过水印 ID 来给视频添加多个水印，并可对水印进行排序。如果你需要移除指定水印，可调用 [`removeVideoWatermark`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/watermark#api_irtcengine_removevideowatermark) 方法。 #### 异步销毁引擎 [#异步销毁引擎-1] 该版本新增 `destroy:` 方法，用于销毁 RTC 引擎，且支持通过参数配置以同步或异步方式销毁引擎。异步销毁引擎时，SDK 会触发 `engineReleasedBlock` 回调块。 #### 美颜功能拓展 [#美颜功能拓展-1] 新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。 #### Token 更新结果回调 [#token-更新结果回调-1] 该版本新增 [`rtcEngine:renewTokenResult:code:`](/zh-CN/api-reference/rtc/ios/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调及 `RENEW_TOKEN_ERROR_CODE` 错误码。当调用 `renewToken:` 方法更新 Token 后，SDK 会通过 [`rtcEngine:renewTokenResult:code:`](/zh-CN/api-reference/rtc/ios/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调通知 Token 更新的结果，并通过 `RENEW_TOKEN_ERROR_CODE` 返回详细的错误码，开发者可在回调中根据错误码及时处理 Token 更新失败的场景。 #### 其他 [#其他-6] - 新增 [`setPlaybackAudioFrameBeforeMixingParametersWithSampleRate`](/zh-CN/api-reference/rtc/ios/audio/audio-raw#api_irtcengine_setplaybackaudioframebeforemixingparameters1) 方法用于设置 [`onPlaybackAudioFrameBeforeMixing:channelId:uid:`](/zh-CN/api-reference/rtc/ios/audio/audio-raw#callback_iaudioframeobserver_onplaybackaudioframebeforemixing) 回调中返回的音频帧格式，包括采样率、声道数以及每次回调的数据采样点数。调用此方法后，SDK 会按照设定的参数返回混音前的原始音频数据，便于开发者进行自定义处理或分析。 - 新增 `preloadEffectEx` 方法，用于将指定音效文件预加载到指定频道，支持本地或在线音效文件，便于后续快速播放，适合多频道场景。 - 新增 [`playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:startPos:`](/zh-CN/api-reference/rtc/ios/play/audio-effect-file#api_irtcengineex_playeffectex) 方法，用于在指定频道播放音效文件，支持设置循环次数、音调、空间位置、音量、是否发布到频道及播放起始位置等参数，满足丰富的音效播放需求。 - 本地截图上传功能支持通过 [`AgoraContentInspectModule`](/zh-CN/api-reference/rtc/ios/class-contentinspectmodule) 中新增的 `position` 成员设置截图的视频观测位置，从而实现对原始视频数据或效果处理前后的视频流进行截图并上传。 - 为了提升用户使用绿幕或蓝幕开启虚拟背景功能时，人像分割的准确性和稳定性，该版本在 [`AgoraSegmentationProperty`](/zh-CN/api-reference/rtc/ios/class-segmentationproperty) 中新增 `screenColorType` 属性，支持指定背景幕布的颜色为绿色、蓝色或自动识别。 ### 改进 [#改进-19] #### 美颜重构 [#美颜重构-1] 该版本对美颜功能进行了彻底重构和升级，不仅拓展了美颜功能，提升了美颜效果和性能，还解决了美颜参数配置复杂、集成成本高、美颜资源依赖网络易失效等痛点。主要改进包括： - **API 大幅简化**：将过去版本中的基础美颜、美型、美妆、滤镜功能整合为 `AgoraVideoEffectNodeBeauty`、`AgoraVideoEffectNodeStyleMakeup`、`AgoraVideoEffectNodeFilter` 三个核心节点 (node)，通过 [`AgoraVideoEffectObject`](/zh-CN/api-reference/rtc/ios/class-ivideoeffectobject) 统一管理生命周期和参数设置，减少频繁 API 调用带来的性能负担。 - **预设模板开箱即用**：提供多套预设风格模板（如“自然美颜”、“学姐妆”、“冷白滤镜”），大幅简化集成流程，无需手动调试数十项参数。 - **美颜参数动态控制**：该版本新增实时获取美颜参数的能力，开发者可通过 key-value 方式动态读取或修改任意细粒度参数（如磨皮强度、口红类型）。同时支持：调用预设模板快速启用风格效果、保存主播自定义参数配置、随时重置参数至默认状态，极大提升了业务层状态同步的灵活性和开发效率。 - **美颜资源外置**：该版本通过美颜资源外置化设计，将所有美颜资源（特效、滤镜、妆容）均打包为本地 bundle 文件，彻底消除因网络下载失败导致美颜失效的风险。 #### 其他改进 [#其他改进-9] - 在与 Web 端互通时，新增对 g711 和 g722 音频编解码器的支持，进一步提升了跨平台音频播放的兼容性和清晰度。 - 优化了屏幕共享文档场景下的共享视频清晰度。 ### 问题修复 [#问题修复-25] 该版本修复了以下问题： - 调用 [`open:startPos:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-open#api_imediaplayer_open) 打开在线音效文件后，调用 [`playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:`](/zh-CN/api-reference/rtc/ios/play/audio-effect-file#api_irtcengine_playeffect3) 开始播放，当调用 [`seekToPosition:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定播放位置后，音效文件会从头开始播放。 - 在媒体音量模式下，主播在频道中发布麦克风采集的音频流，同时调用 [`playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:`](/zh-CN/api-reference/rtc/ios/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效文件、调用 [`startAudioMixing:loopback:cycle:startPos:`](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing2) 播放音乐文件，偶现回声。 - 在 [`setExternalVideoSource:useTexture:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-custom-capturenrendering#api_irtcengine_setexternalvideosource) 之后调用 [`setMediaMetadataDelegate:withType:`](/zh-CN/api-reference/rtc/ios/metadata/metadata-observer#api_irtcengine_registermediametadataobserver) 注册媒体 metadata 观测器，SDK 没有触发 metadata 观测器的回调。 - 偶现的崩溃问题。 - 调用 [`joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengineex_joinchannelex) 加入频道，然后调用 [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 开始跨频道媒体流转发，下麦、退出频道后重新加入频道开始连麦，偶现 [`rtcEngine:channelMediaRelayStateDidChange:error:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) 回调报告 `state` 为 `AgoraChannelMediaRelayStateFailure`，[`code`](/zh-CN/api-reference/rtc/ios/play/rte-player#api_error_code) 为 `AgoraChannelMediaRelayErrorServerErrorResponse`。 ## v4.5.2 [#v452-1] 该版本于 2025 年 4 月 22 日发布。 :::warning[注意] - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `aosl.xcframework` 库。 - 4.5.2 RTC SDK `aosl.xcframework` 库版本为 1.2.13。你可以在 `Info.plist` 中查看库的版本信息。 ::: ### 改进 [#改进-20] #### URL 拉流播放 [#url-拉流播放-2] 该版本进一步拓展了 URL 拉流播放的功能，支持播放 CDN URL 和本地媒体资源文件，同时可以设置从指定位置开始播放、调节播放速度、设置播放音量、在播放过程中切换播放源等，详见 [观众端 URL 拉流](/zh-CN/realtime-media/rtc/build/optimize-and-operate/playing-url)。 ### 问题修复 [#问题修复-26] 该版本修复了以下问题： - 开启导唱功能播放多音轨歌曲时，调用 [`setAudioPitch:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setaudiopitch) 方法调整歌曲音调后出现杂音。 - 主播端调用 [`createCustomAudioTrack:config:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 创建自定义音频采集轨道并将 `trackType` 设为 `AUDIO_TRACK_DIRECT`，调用 [`pushExternalAudioFrameRawData:samples:sampleRate:channels:trackId:timestamp:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#api_irtcengine_pushaudioframe2) 将自采集音频推送到频道内，然后调用 [`playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:`](/zh-CN/api-reference/rtc/ios/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效，频道内的观众听主播的音频有杂音。 - 集成了 SDK 的 App 在音视频互动过程中偶现主线程阻塞导致的 UI 卡顿。 - 调用 [`openWithMediaSource:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 并通过 `source` 参数将 `isLiveSource` 设为 `YES` 并播放纯视频流，播放失败。 - 调用 [`enableVirtualBackground:backData:segData:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 开启虚拟背景功能，手机横竖屏旋转后，虚拟背景图像变大变模糊。 - 发送端传输多声道编码音频时，接收端偶现杂音。 - App 集成媒体播放器场景下，先后两次调用 open 打开不同媒体资源，第二次打开时，媒体播放器信息变化回调 [`AgoraRtcMediaPlayer:infoUpdated:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerinfoupdated) 返回第一次媒体资源的信息，不符合预期。 - 调用 [`enableAudioVolumeIndication:smooth:reportVad:`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 启用用户音量提示本地发流用户和远端用户音量相关信息，用户音量提示回调 [`rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 返回的本地用户音量为 0。 - App 调用 [`enableVideoImageSource:options:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 启用垫片推流功能，偶现发送端推流成功但是 [`rtcEngine:didVideoPublishStateChange:sourceType:oldState:newState:elapseSinceLastState:`](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 返回当前的发布状态不是 `PUB_STATE_PUBLISHED`，不符合预期。 - 多频道场景下，App 在调用 [`joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengineex_joinchannelex) 成功前调用 [`setupRemoteVideoEx:connection:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengineex_setupremotevideoex) 初始化远端用户视图，偶现远端用户视图首帧图像显示延时大。 - App 退出时偶现崩溃。 ## v4.5.1 [#v451-1] 该版本于 2025 年 3 月 5 日发布。 :::warning[注意] - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `aosl.xcframework` 库。 - 4.5.1 RTC SDK `aosl.xcframework` 库版本为 1.2.13。你可以在 `Info.plist` 中查看库的版本信息。 ::: ### 新增特性 [#新增特性-19] #### AI 对话场景 [#ai-对话场景-1] 该版本新增了专为与[声网对话式 AI 引擎](/zh-CN/ai)创建的智能体互动设计的 `AgoraAudioScenarioAiClient` 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。 ### 改进 [#改进-21] 该版本优化了特定机型上 SDK 初始化的耗时。 ### 问题修复 [#问题修复-27] 该版本修复了以下问题： - 同时加入两个及以上的频道，连续调用 [`takeSnapshotEx:uid:filePath:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。 - 使用媒体播放器时，调用 [`pause`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seekToPosition:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 定位到指定播放位置、然后调用 [`play`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。 - 使用媒体播放器时，调用 [`switchSrc:syncPts:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换媒体资源后，调用 [`getPlaySrc`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-info#getplaysrc)获取当前正在播放的媒体资源的路径没有变化。 - 在推送 i420 格式的视频帧到频道内时，使用 CVPixelBuffer 会导致崩溃。 - 调用 [`setupLocalVideo:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_setuplocalvideo) 设置两个视图（view），然后调用 [`enableFaceDetection:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/face-detection#api_irtcengine_enablefacedetection) 开启人脸检测，后传入的视图中无法检测到人脸信息。 - 屏幕共享场景下，接收端用户看到的共享图像出现绿线。 - 在极速直播场景下，观众通过 `string` 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。 - 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。 ## v4.5.0 [#v450-1] 该版本于 2024 年 11 月 26 日发布。 ### 升级必看 [#升级必看-17] 该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 :::warning[注意] 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `aosl.xcframework` 库。4.5.0 RTC SDK `aosl.xcframework` 库版本为 1.2.13。你可以在 `Info.plist` 中查看库的版本信息。 ::: #### 强效视频降噪实现变更 [#强效视频降噪实现变更-1] 该版本调整了强效视频降噪的实现方式，在 [`AgoraVideoDenoiserLevel`](/zh-CN/api-reference/rtc/ios/enum-videodenoiserlevel) 中删除了 `AgoraVideoDenoiserLevelStrength`，改为调用 [`setVideoDenoiserOptions:options:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 启用视频降噪后，调用 [`setBeautyEffectOptions:options:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 [`setVideoDenoiserOptions:options:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)。 此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 [`setLowlightEnhanceOptions:options:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)。 #### 视频编码偏好变更 [#视频编码偏好变更-1] 为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好： - 在 [`AgoraCompressionPreference`](/zh-CN/api-reference/rtc/ios/enum-compressionpreference) 枚举类中新增 `AgoraCompressionAuto` (-1) 枚举，并替代原有的 `AgoraCompressionQuality` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `AgoraCompressionLowLatency` 或 `AgoraCompressionQuality`，以获得最佳的用户体验。 - 在 [`AgoraDegradationPreference`](/zh-CN/api-reference/rtc/ios/enum-degradationpreference) 枚举类中新增 `AgoraDegradationMaintainAuto` (-1) 枚举，并替代原有的 `AgoraDegradationMaintainQuality` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `AgoraDegradationMaintainFramerate`、`AgoraDegradationBalanced` 或 `AgoraDegradationMaintainResolution`，以获得最优的综合质量体验 (QoE)。 ### 新增特性 [#新增特性-20] #### 高级美颜 [#高级美颜-1] 该版本新增以下两种高级美颜功能： - 美型：调用 [`setFaceShapeBeautyOptions:options:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 [`setFaceShapeAreaOptions:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapeareaoptions) 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。 - 美妆：调用 [`setExtensionPropertyWithVendor:extension:key:value:`](/zh-CN/api-reference/rtc/ios/extension#api_irtcengine_setextensionproperty) 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。 有关美型和美妆的实现步骤，详见[实现高级美颜](/zh-CN/realtime-media/rtc/build/video/advanced-beauty)。 :::info[信息] 目前，高级美颜功能为**限时免费**，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 秀场直播场景 [#秀场直播场景-1] 该版本在 [`AgoraApplicationScenarioType`](/zh-CN/api-reference/rtc/ios/enum-videoapplicationscenariotype) 类下新增枚举 `AgoraApplicationLiveShowScenario`(3)（秀场直播），你可以调用 [`setVideoScenario:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为[秀场直播](/zh-CN/solutions/showroom)。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，例如，默认开启音视频帧加速渲染来提升首帧出图体验，无需再额外调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_enableinstantmediarendering)，此外，也增强了在弱网环境和低端设备上的画质和流畅度表现。 #### 限制视频渲染帧率 [#限制视频渲染帧率-1] 该版本新增 [`setLocalRenderTargetFps`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_setlocalrendertargetfps) 和 [`setRemoteRenderTargetFps`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_setremoterendertargetfps) 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。 在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。 #### URL 拉流播放 [#url-拉流播放-3] URL 拉流播放功能主要用于直播场景，观众端可以直接通过 [`openWithUrl:startTime:cb:`](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_openwithurl) 打开特定的 URL 来播放实时媒体流，无需显示调用加入频道、订阅等 API，极大简化了观众端观看直播流的 API 调用。 在播放的过程中，观众端可以通过 [`setAbrSubscriptionLayer:error:`](/zh-CN/api-reference/rtc/ios/play/rte-player#api_playerconfig_setabrsubscriptionlayer) 设置订阅视频大小流，并可以在大小流之间实现平滑切换。如果对视频体验有更高要求，可以联系[联系技术支持](https://ticket.shengwang.cn/)开通 ABR（Adaptive Bitrate，自适应码率）功能。启用该功能后，可以自定义不同层级的视频流分辨率，观众可以实现不同分辨率视频流的平滑切换。 当网络情况不稳定时，观众端可以调用 [`setAbrFallbackLayer:error:`](/zh-CN/api-reference/rtc/ios/play/rte-player#api_playerconfig_setabrfallbacklayer) 来设置订阅的视频流的回退选项。SDK 会以你指定的最低质量层级对应的视频流分辨率为下限，在此范围内根据网络状况动态调整分辨率。实现细节详见[观众端 URL 拉流](/zh-CN/realtime-media/rtc/build/optimize-and-operate/playing-url)。 #### 滤镜效果 [#滤镜效果-1] 该版本新增 [`setFilterEffectOptions:options:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setfiltereffectoptions) 方法，你可以在 **config** 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 `built_in_whiten_filter.cube` 文件，用于快速实现美白滤镜效果。 #### 本地音频合流 [#本地音频合流-1] 该版本新增本地音频合流功能，你可以调用 [`startLocalAudioMixer`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/audiomixer#api_irtcengine_startlocalaudiomixer) 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 [`stopLocalAudioMixer`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/audiomixer#api_irtcengine_stoplocalaudiomixer) 方法停止本地音频合流；在合流过程中，可以调用 [`updateLocalAudioMixerConfiguration`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/audiomixer#api_irtcengine_updatelocalaudiomixerconfiguration) 方法更新正在合流的音频流配置。 该功能的使用场景示例如下： - 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。 - 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。 - 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。 #### 色彩空间设置 [#色彩空间设置-1] 该版本在 [`AgoraOutputVideoFrame`](/zh-CN/api-reference/rtc/ios/class-videoframe) 和 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/ios/class-externalvideoframe) 中新增了 **colorSpace**，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。 ### 改进 [#改进-22] #### 虚拟背景算法优化 [#虚拟背景算法优化-2] 该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。 #### 录制本地预览视频 [#录制本地预览视频-1] 该版本在 [`AgoraRecorderStreamInfo`](/zh-CN/api-reference/rtc/ios/class-recorderstreaminfo) 中新增 **type** 成员。当调用 [`createMediaRecorder:`](/zh-CN/api-reference/rtc/ios/recording#api_irtcengine_createmediarecorder) 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 [`AgoraMediaRecorderConfiguration`](/zh-CN/api-reference/rtc/ios/class-mediarecorderconfiguration) 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 [`startRecording:`](/zh-CN/api-reference/rtc/ios/recording#api_imediarecorder_startrecording) 即可开始录制本地预览的视频。 #### 指定视频观测位置截图 [#指定视频观测位置截图-1] 该版本新增 [`takeSnapshotWithConfig:config:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/snapshot#api_irtcengine_takesnapshot2) 和 [`takeSnapshotExWithConfig:uid:config:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex2) 方法，你可以在调用该方法时通过 **config** 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。 #### 自定义音频采集改进 [#自定义音频采集改进-1] 该版本在 [`AgoraAudioTrackConfig`](/zh-CN/api-reference/rtc/ios/class-audiotrackconfig) 中新增了 `enableAudioProcessing` 成员参数，用于控制是否对 `AUDIO_TRACK_DIRECT` 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 `NO`，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。 #### 其他改进 [#其他改进-10] - 通过拼接视频帧和 Alpha 数据实现 Alpha 透明特效的应用场景下，提升了接收端的渲染性能，有效减少卡顿和延迟。 - 优化了调用 [`queryDeviceScore`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_querydevicescore) 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。 - 频道内调用 [`enableLocalAudio:`](/zh-CN/api-reference/rtc/ios/audio/audio-capture#api_irtcengine_enablelocalaudio) 关闭本地采集后，支持通过手机静音侧键把 App 播放的背景音效设置为静音状态。 - 调用 [`switchSrc:syncPts:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 [`AgoraRtcMediaPlayer:didOccurEvent:elapsedTime:message:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent) 回调报告 `AgoraMediaPlayerEventSwitchError` 事件，表示媒体资源切换时发生错误。 - 调用 [`setPlaybackSpeed:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，最低支持 0.3 倍速播放。 ### 问题修复 [#问题修复-28] 该版本修复了以下问题： - 当发送端视频源类型为 JPEG 格式时，偶现接收端帧率低于预期。 - 音视频互动过程中，偶现接收端听发送端没有声音。 - 音视频互动过程中，如果发送端设备的系统版本为 iOS 17，偶现接收端听不到来自发送端的声音。 - 直播场景下，观众端因切换网络导致断开连接，重新连接直播间花费的时间长于预期。 - App 启动后使用媒体播放器播放在线媒体资源，播放无声。 - 音视频互动过程中被系统其他 App 打断后恢复，偶现音频采集无声。 - 调用 [`startAudioMixing:loopback:cycle:`](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing) 后，立即调用 [`pauseAudioMixing`](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_pauseaudiomixing) 暂停播放音乐文件不生效。 ## v4.4.0 [#v440-1] 该版本于 2024 年 8 月 5 日发布。 ### 升级必看 [#升级必看-18] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 :::info[信息] 自 v4.4.0 起，RTC SDK 提供 API 下架说明，包含各版本废弃及删除的 API 信息。详见 [API 下架说明](/zh-CN/api-reference/rtc/ios/rtc-api-sunset)。 ::: 1. 为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的 [`AgoraExtensionContext`](/zh-CN/api-reference/rtc/ios/class-extensioncontext) 了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。 | 原有回调 | 现有回调 | | -------------------- | ------------------------------- | | `onEvent` | [`onEventWithContext:key:value:`](/zh-CN/api-reference/rtc/ios/extension#callback_irtcengineeventhandler_onextensioneventwithcontext) | | `onExtensionStarted` | [`onExtensionStartedWithContext:`](/zh-CN/api-reference/rtc/ios/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) | | `onExtensionStopped` | [`onExtensionStoppedWithContext:`](/zh-CN/api-reference/rtc/ios/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext) | | `onExtensionError` | [`onExtensionErrorWithContext:error:message:`](/zh-CN/api-reference/rtc/ios/extension#callback_irtcengineeventhandler_onextensionerrorwithcontext) | 2. 在 v4.4.0 之前，当你的用户角色为观众时，调用 [`setAudioScenario:`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#api_irtcengine_setaudioscenario) 将音频场景设为聊天室场景（`AgoraAudioScenarioChatRoom`）会显示麦克风采集状态。自 v4.4.0 起，SDK 通过 iOS 原生的 API 控制麦克风开关，因此观众角色在聊天室场景下不会再显示麦克风采集状态。 3. 该版本将 `receiveMetadata` 回调改名为 [`didMetadataReceived:`](/zh-CN/api-reference/rtc/ios/metadata/metadata-observer#callback_imetadataobserver_onmetadatareceived)，并删除了回调中的 `data`、`timeStamp` 参数，你可以通过新增的 `metadata` 参数来获取 Metadata 的相关信息，包括 `timeStamp`（发送数据的时间戳）、`uid`（用户 ID）、`channelId`（源频道名称）等。 ### 新增特性 [#新增特性-21] #### Lite SDK [#lite-sdk-1] 自该版本起，声网推出 Lite 版 SDK，该 SDK 中仅包含音视频基础能力、对高阶音视频处理的功能进行部分裁剪，可有效减少集成 SDK 后的 App 体积。 - Lite SDK 支持手动集成或三方仓库集成，详见[下载](/zh-CN/realtime-media/rtc/reference/downloads)和[集成 SDK](/zh-CN/realtime-media/rtc/get-started/quick-start#集成-sdk)。 - Lite SDK 包含的动态库信息详见[减小 App 体积](/zh-CN/realtime-media/rtc/build/optimize-and-operate/reduce-app-size)。 - Lite SDK 支持的 API 清单详见 [Lite SDK API 列表](/zh-CN/api-reference/rtc/ios/rtc-lite-api)。 - 使用 Lite SDK 播放媒体文件时的限制和注意事项详见 [RTC SDK 支持播放哪些格式的音频文件？](/zh-CN/reference/faq/product/audio_format) :::warning[注意] Lite SDK 默认无法与 [RTC 小程序 SDK](/zh-CN/realtime-media/rtc) 互通。如果需要与小程序互通，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: #### Alpha 透明特效 [#alpha-透明特效-1] 该版本新增 Alpha 透明特效功能，支持在 SDK 采集和自定义采集视频的场景下，在发送端发布视频帧的 Alpha 通道、在接收端对 Alpha 通道进行渲染处理，实现透明礼物特效、接收端自定义主播背景等： - [`AgoraOutputVideoFrame`](/zh-CN/api-reference/rtc/ios/class-videoframe) 和 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/ios/class-externalvideoframe) 中新增 `alphaBuffer`：设置 Alpha 通道数据。 - [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/ios/class-externalvideoframe) 中新增 `fillAlphaBuffer`：对于 BGRA 或 RGBA 格式的视频数据，设置是否自动提取 Alpha 通道数据并填入到 `alphaBuffer` 中。 - [`AgoraOutputVideoFrame`](/zh-CN/api-reference/rtc/ios/class-videoframe) 和 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/ios/class-externalvideoframe) 中新增 `alphaStitchMode`：设置 `alphaBuffer` 和视频帧拼接的相对位置。 另外，[`AgoraAdvancedVideoOptions`](/zh-CN/api-reference/rtc/ios/class-advanceoptions) 中新增成员 `encodeAlpha`，用于设置是否将 Alpha 信息编码并发送到远端。SDK 默认不对 Alpha 信息进行编码发送；如果需要对 Alpha 信息编码发送至远端（例如开启了虚拟背景功能），请显式调用 [`setVideoEncoderConfiguration:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 设置视频编码属性，并将 `encodeAlpha` 设置为 `YES`。 :::info[信息] 如需了解在各场景下实现 Alpha 特效的最佳实践，详见[实现 Alpha 透明特效](/zh-CN/realtime-media/rtc/build/video/alpha-effect)。 ::: #### AI 调音器 [#ai-调音器-1] 该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 [`enableVoiceAITuner:type:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/audio-effect#api_irtcengine_enablevoiceaituner) 方法并传入 [`AgoraVoiceAITunerType`](/zh-CN/api-reference/rtc/ios/enum-voiceaitunertype) 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。 #### 版权音乐优化 [#版权音乐优化-1] - 该版本在 [`AgoraMusicPlayerProtocol`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusicplayer) 类下新增 [`setPlayMode:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusicplayer_setplaymode) 方法，用于设置音乐资源的播放模式。在在线 K 歌房等场景下，你可以根据需求启用伴唱、原唱或导唱模式。 - 该版本在 [`AgoraMusicContentCenter`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusiccontentcenter) 类下新增 [`destroyMusicPlayer:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_destroymusicplayer) 方法，用于销毁音乐播放器并释放相应的资源。 #### 1v1 视频通话场景 [#1v1-视频通话场景-1] 该版本在 [`AgoraApplicationScenarioType`](/zh-CN/api-reference/rtc/ios/enum-videoapplicationscenariotype) 类下新增枚举 `AgoraApplication1V1Scenario`（1v1 视频通话）。你可以调用 [`setVideoScenario:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。 ### 改进 [#改进-23] #### 人脸区域美颜 [#人脸区域美颜-1] 为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。 #### 其他改进 [#其他改进-11] 该版本还进行了如下改进： - 优化了传输策略，调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_enableinstantmediarendering) 不再对传输链路的安全性产生影响。 - 废弃了 [`AgoraClientRoleChangeFailedReason`](/zh-CN/api-reference/rtc/ios/enum-clientrolechangefailedreason) 中的冗余枚举值 `AgoraClientRoleChangeFailedRequestTimeout`、`AgoraClientRoleChangeFailedConnectionFailed`。 ### 问题修复 [#问题修复-29] 该版本修复了以下问题： - 在实时互动过程中，当多个远端同时加入频道时 App 偶现崩溃。 - App 切后台一段时间、然后返回前台时，远端视频画面偶现卡住或花屏。 - 发送端调用 `startDirectCdnStreaming:publishUrl:mediaOptions:` 开始直接向 CDN 推流后，频繁开关或切换网络，偶现接收端黑屏但发送端未收到推流失败回调。 - 调用 [`pushExternalAudioFrameRawData:samples:sampleRate:channels:trackId:timestamp:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#api_irtcengine_pushaudioframe2) 推送外部音频数据，外部音频渲染的采样率如果不是 SDK 推荐的值时，比如 22050 Hz 和 11025 Hz，声音播放失败。 ## v4.3.2 [#v432-1] 该版本于 2024 年 6 月 4 日发布。 ### 升级必看 [#升级必看-19] 该版本修改了播放版权音乐的行为，当调用 [`AgoraMusicPlayerProtocol`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusicplayer) 中的 [`play`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 方法播放版权音乐媒体文件时，存在以下行为变更： - v4.3.2 以前版本：SDK 默认播放当前音频文件的第一个音轨。 - v4.3.2： SDK 默认播放伴奏。 ### 改进 [#改进-24] 1. 提升了 [`setRemoteSubscribeFallbackOption:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_setremotesubscribefallbackoption) 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 [`setRemoteSubscribeFallbackOption:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_setremotesubscribefallbackoption) 动态切换弱网环境下的音视频流回退选项。 2. 媒体播放器支持播放带有 Alpha 通道的 MP4 文件。 ### 问题修复 [#问题修复-30] 该版本修复了以下问题： - App 长时间切后台再返回前台时，远端视频画面卡住或花屏。 - 部分 iPad 设备上的本地预览画面旋转 90°，不符合预期。 - 音视频互动过程中偶现视频流畅度不佳。 - 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。 - 远端用户离开频道时偶现崩溃。 - 调用 [`startAudioMixing:loopback:cycle:`](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_startaudiomixing) 播放音乐文件，音乐文件播放结束后偶现无法触发 [`rtcEngine:audioMixingStateChanged:reasonCode:`](/zh-CN/api-reference/rtc/ios/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)(AgoraAudioMixingStateTypeStopped,AgoraAudioMixingReasonAllLoopsCompleted) 回调报告音乐文件播放完毕。 - 调用 [`playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:`](/zh-CN/api-reference/rtc/ios/play/audio-effect-file#api_irtcengine_playeffect3) 播放时长不足 1 秒的音效文件并设置不循环播放（ [`loopCount`](/zh-CN/api-reference/rtc/ios/play/rte-player#api_playerconfig_getloopcount) 为 0 ）时，出现无声。 - 使用媒体播放器播放视频，暂停播放后恢复播放，偶现短暂无声。
## v4.3.1 [#v431-1] 该版本于 2024 年 4 月 29 日发布。 ### 新增特性 [#新增特性-22] #### 隐私清单文件 [#隐私清单文件] 为满足 Apple 对于 App 发布的安全合规要求，SDK 自该版本起新增隐私清单文件 `PrivacyInfo.xcprivacy`，其中包含 SDK 中需要访问或使用用户数据的 API 调用说明和 SDK 采集的数据类型说明。 :::info[信息] 如果你需要将集成 v4.3.1 之前的 SDK 版本的 App 发布到苹果应用商店，则需要在 Xcode 工程中手动添加 `PrivacyInfo.xcprivacy` 文件。详见[如何在 App 中增加隐私清单？](/zh-CN/reference/faq/other/ios_privacy_manifest) ::: #### 人像锁定 [#人像锁定] 为提升在线会议、秀场、在线教育等场景中的主播演讲效果，该版本新增 [`enableCameraCenterStage:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) 方法开启人像锁定功能。该功能可确保主播无论移动与否，始终位于画面中心，以取得良好的演讲效果。 在开启人像锁定前，建议你先调用 [`isCameraCenterStageSupported`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) 查询当前设备性能是否支持该功能。支持的设备清单可参考 [`API 文档`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage)。 #### 摄像头防抖 [#摄像头防抖] 为改善在移动拍摄、暗光环境拍摄、手持拍摄等场景下的视频画面稳定性，该版本新增摄像头防抖功能。你可以调用 [`setCameraStabilizationMode:`](/zh-CN/api-reference/rtc/ios/video/camera-capture#api_irtcengine_setcamerastabilizationmode) 开启该功能并设置适合的防抖模式，以获得更加稳定、清晰的视频画面。 #### 摄像头广角和超广角 [#摄像头广角和超广角-1] 为了让用户捕捉到更宽阔的视野和更完整的画面内容，该版本新增了对广角和超广角摄像头的支持。你可以先调用 [`queryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 查询设备支持的焦距能力，然后调用 [`setCameraCapturerConfiguration:`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 并将 `cameraFocalLengthType` 设置为支持的焦距类型，包括广角、超广角等。 #### 数据流加密 [#数据流加密-1] 该版本在 [`AgoraEncryptionConfig`](/zh-CN/api-reference/rtc/ios/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` 成员用于启用数据流加密。你可以在调用 [`enableEncryption:encryptionConfig:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_enableencryption) 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` 和 `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` 枚举得知。 #### 本地视频渲染 [#本地视频渲染-1] 该版本在 [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/ios/class-videocanvas) 中新增如下成员，以支持更多本地渲染功能。 - `enableAlphaMask`：可以通过该成员设置接收端是否开启 Alpha 遮罩渲染。Alpha 遮罩渲染功能可以创建具有透明效果的图像或提取视频中的人像。 #### 视频小流自适应配置 [#视频小流自适应配置-1] 该版本新增视频小流的自适应配置功能，当你调用 [`setDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setdualstreammode2) 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示： - 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。 - 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。 #### 其他 [#其他-7] - 新增 [`enableEncryptionEx:encryptionConfig:connection:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengineex_enableencryptionex) 方法，用于多频道场景下开启媒体流或数据流加密。 - 新增 [`setAudioMixingPlaybackSpeed:`](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) 方法，用于设置音乐文件的播放速度。 - 新增 [`getCallIdEx:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengineex_getcallidex) 方法，用于多频道场景下获取通话 ID。 ### 改进 [#改进-25] #### 虚拟背景算法优化 [#虚拟背景算法优化-3] 为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法： - 支持识别任意纯色背景，不再局限于绿幕。 - 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。 - 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。 #### 音频自采集优化 [#音频自采集优化] 为提升音频自采集的灵活性，该版本废弃 [`pushExternalAudioFrameSampleBuffer:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#pushexternalaudioframesamplebuffer) 并新增 [`pushExternalAudioFrameSampleBuffer:sampleRate:channels:trackId:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#api_irtcengine_pushexternalaudioframesamplebuffer2)。相比废弃方法，新增方法中增加了 `sampleRate`、`channels`、`trackId` 参数，支持你通过自定义音频轨道将外部 CMSampleBuffer 音频数据推送到频道内，并支持设置外部音频源的采样率和声道数。 #### 降低耳返的 CPU 消耗 [#降低耳返的-cpu-消耗-1] 该版本在 [`AgoraEarMonitoringFilterType`](/zh-CN/api-reference/rtc/ios/enum-earmonitoringfiltertype) 中新增 `AgoraEarMonitoringFilterReusePostProcessingFilter`(1<<15) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。 #### 其他改进 [#其他改进-12] 该版本还进行了如下改进： - 优化了非屏幕共享场景的视频编解码策略，节省系统性能开销。 - 提升了原始视频帧观测器在处理视频时的稳定性。 - 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。 - 在 [`AgoraAudioEffectPreset`](/zh-CN/api-reference/rtc/ios/enum-audioeffectpreset) 中新增 `AgoraAudioEffectPresetRoomAcousticsChorus`（合唱音效），可使人声在合唱场景下更具空间立体感。 - 在 [`AgoraRtcRemoteAudioStats`](/zh-CN/api-reference/rtc/ios/class-remoteaudiostats) 中新增 `e2eDelay`，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。 ### 问题修复 [#问题修复-31] 该版本修复了以下问题： - 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。 - 当发送端用户的网络环境恶化（例如弱网）时，接收端偶现视频流畅度降低、卡顿增加。 ### API 变更 [#api-变更-8] #### 新增 [#新增-8] - [`enableCameraCenterStage:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) - [`isCameraCenterStageSupported`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) - [`setCameraStabilizationMode:`](/zh-CN/api-reference/rtc/ios/video/camera-capture#api_irtcengine_setcamerastabilizationmode) - [`AgoraCameraStabilizationMode`](/zh-CN/api-reference/rtc/ios/enum-camerastabilizationmode) - [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/ios/class-videocanvas) 中新增 `enableAlphaMask` - [`AgoraEncryptionConfig`](/zh-CN/api-reference/rtc/ios/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` - [`AgoraEncryptionErrorType`](/zh-CN/api-reference/rtc/ios/enum-encryptionerrortype) 中新增如下枚举： - `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` - `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` - [`AgoraRtcRemoteAudioStats`](/zh-CN/api-reference/rtc/ios/class-remoteaudiostats) 新增 `e2eDelay` - [`AgoraErrorCode`](/zh-CN/api-reference/rtc/ios/enum-errorcodetype) 新增 `AgoraErrorCodeDatastreamDecryptionFailed` - [`AgoraAudioEffectPreset`](/zh-CN/api-reference/rtc/ios/enum-audioeffectpreset) 新增 `AgoraAudioEffectPresetRoomAcousticsChorus` - [`getCallIdEx:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengineex_getcallidex) - [`enableEncryptionEx:encryptionConfig:connection:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengineex_enableencryptionex) - [`setAudioMixingPlaybackSpeed:`](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) - [`queryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) - [`AgoraFocalLengthInfo`](/zh-CN/api-reference/rtc/ios/class-focallengthinfo) - [`AgoraFocalLength`](/zh-CN/api-reference/rtc/ios/enum-camerafocallengthtype) - [`AgoraCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/ios/class-cameracapturerconfiguration) 新增成员 `cameraFocalLengthType` - [`AgoraEarMonitoringFilterType`](/zh-CN/api-reference/rtc/ios/enum-earmonitoringfiltertype) 新增枚举 `AgoraEarMonitoringFilterBuiltInAudioFilters`(1<<15) - [`pushExternalAudioFrameSampleBuffer:sampleRate:channels:trackId:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#api_irtcengine_pushexternalaudioframesamplebuffer2) #### 废弃 [#废弃-4] - [`pushExternalAudioFrameSampleBuffer:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#pushexternalaudioframesamplebuffer)
## v4.3.0 [#v430-1] 该版本于 2024 年 2 月 22 日发布。 ### 升级必看 [#升级必看-20] 该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 回调中的参数改名 [#回调中的参数改名-1] 为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。 | 回调 | 原有参数名 | 现有参数名 | | --- | --- | --- | | [`rtcEngine:localAudioStateChanged:reason:`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) | `error` | `reason` | | [`rtcEngine:localVideoStateChangedOfState:reason:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) | `error` | `reason` | | `onDirectCdnStreamingStateChanged:reason:message:` | `error` | `reason` | | [`onMusicChartsResult:result:reason:`](/zh-CN/api-reference/rtc/ios/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) | `errorCode` | `reason` | | [`onPreLoadEvent:songCode:percent:lyricUrl:state:reason:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onpreloadevent) | [release-notes-ios-html-1-5-1 details](#table-slot-release-notes-ios-html-1-5-1) | [release-notes-ios-html-1-5-2 details](#table-slot-release-notes-ios-html-1-5-2) | | [`onMusicCollectionResult:result:reason:`](/zh-CN/api-reference/rtc/ios/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) | `errorCode` | `reason` | | [`onLyricResult:songCode:lyricUrl:reason:`](/zh-CN/api-reference/rtc/ios/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) | `errorCode` | `reason` | | [`onSongSimpleInfoResult:songCode:simpleInfo:reason:`](/zh-CN/api-reference/rtc/ios/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) | `errorCode` | `reason` | | [`AgoraRtcMediaPlayer:didChangedToState:reason:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) | `error` | `reason` | | [`rtcEngine:rtmpStreamingChangedToState:state:reason:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/media-push#callback_irtcengineeventhandler_onrtmpstreamingstatechanged) | `errCode` | `reason` | **release-notes-ios-html-1-5-1 details** - `status` - `state` **release-notes-ios-html-1-5-2 details** - `errorCode` - `reason` | 原有枚举类 | 现有枚举类 | | ------------------------------------ | ------------------------------------ | | `AgoraAudioLocalError` | [`AgoraAudioLocalReason`](/zh-CN/api-reference/rtc/ios/enum-localaudiostreamreason) | | `AgoraLocalVideoStreamError` | [`AgoraLocalVideoStreamReason`](/zh-CN/api-reference/rtc/ios/enum-localvideostreamreason) | | `AgoraDirectCdnStreamingError` | `AgoraDirectCdnStreamingReason` | | `AgoraMediaPlayerError` | [`AgoraMediaPlayerReason`](/zh-CN/api-reference/rtc/ios/enum-mediaplayerreason) | | `AgoraRtmpStreamingError` | [`AgoraRtmpStreamingReason`](/zh-CN/api-reference/rtc/ios/enum-rtmpstreampublishreason) | | `AgoraMusicContentCenterStatusCode` | [`AgoraMusicContentCenterStateReason`](/zh-CN/api-reference/rtc/ios/enum-musiccontentcenterstatereason) | :::info[信息] 有关具体枚举的改名详见 [API 变更](#apichange)。 ::: #### 跨频道媒体流转发 [#跨频道媒体流转发-2] 为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项： | 已删除的方法和回调 | 替代的方法和回调 | | --- | --- | | [release-notes-ios-html-2-1-0 details](#table-slot-release-notes-ios-html-2-1-0) | [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) | | [release-notes-ios-html-2-2-0 details](#table-slot-release-notes-ios-html-2-2-0) | [`startOrUpdateChannelMediaRelayEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) | | `didReceiveChannelMediaRelayEvent` | [`rtcEngine:channelMediaRelayStateDidChange:error:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) | **release-notes-ios-html-2-1-0 details** - `startChannelMediaRelay` - `updateChannelMediaRelay` **release-notes-ios-html-2-2-0 details** - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` #### 视频自采集 [#视频自采集-1] 该版本起，[`pushExternalVideoFrame:videoTrackId:`](/zh-CN/api-reference/rtc/ios/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe) 从 [`AgoraRtcEngineKitEx`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex) 接口类迁移到 [`AgoraRtcEngineKit`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 接口类。 #### 音频路由 [#音频路由-1] 该版本起，[`AgoraAudioOutputRouting`](/zh-CN/api-reference/rtc/ios/enum-audioroute) 中的 `AgoraAudioOutputRoutingBluetooth` 更名为 `AgoraAudioOutputRoutingBluetoothDeviceHfp`，表示音频路由为使用 HFP 协议的蓝牙设备，新增 `AgoraAudioOutputRoutingBluetoothDeviceA2dp`(10) 表示音频路由为使用 A2DP 协议的蓝牙设备。 #### 本地视频状态改变原因 [#本地视频状态改变原因-1] 该版本对 [`AgoraLocalVideoStreamReason`](/zh-CN/api-reference/rtc/ios/enum-localvideostreamreason) 枚举类中的枚举进行了如下修改： - `AgoraLocalVideoStreamErrorEncodeFailure` 的枚举名变更为 `AgoraLocalVideoStreamReasonCodecNotSupport`。 #### 日志加密行为变更 [#日志加密行为变更-1] 出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案： - 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。 - 如有其他特殊需求，请[联系技术支持](https://ticket.shengwang.cn/)并附上对应的加密日志。 ### 新增特性 [#新增特性-23] #### 接收端自定义合图布局 [#接收端自定义合图布局-1] 为支持接收端自定义多路合图流的布局，该版本新增了 [`rtcEngine:didTranscodedStreamLayoutInfoUpdatedWithUserId:videoLayoutInfo:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo) 回调。当接收端收到合图服务器发送的频道内合图视频流时，该回调会被触发，上报合图视频流的布局信息、以及合图流中每一路子视频流的布局信息。接收端可以在调用 [`setupRemoteVideo:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_setupremotevideo) 方法时，为合图视频流中的子视频流（通过 `subviewUid` 区分）设置单独的 `view` 进行渲染，从而达到自定义视频布局的效果。 当合图视频流中的子视频流布局发生变化时，该回调也会被触发，实时上报最新的布局信息。 通过该特性，接收端可以灵活调整本地的视图布局。当在多人视频场景下应用时，接收端只需接收并解码一路合图视频流，可以有效降低接收端解码多路视频时的 CPU 占用率和网络带宽。 :::info[信息] 关于该特性在多主播场景下的最佳实践，详见[多主播场景下的视频体验优化](/zh-CN/realtime-media/rtc/build/video/custom-layout)。 ::: #### 多视图本地预览 [#多视图本地预览-1] 该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下： 1. 调用 [`setupLocalVideo:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第一个视图：在 [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/ios/class-videocanvas) 中设置 `position` 参数为 `AgoraVideoModulePositionPostCaptureOrigin`（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。 2. 调用 [`setupLocalVideo:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第二个视图：在 [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/ios/class-videocanvas) 中设置 `position` 参数为 `AgoraVideoModulePositionPostCapture`，此处观测到的视频具备视频前处理的效果。 3. 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。 #### 查询设备评分等级 [#查询设备评分等级-1] 该版本新增 [`queryDeviceScore`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_querydevicescore) 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请[联系技术支持](https://ticket.shengwang.cn/)。 #### 本地播放及发布至远端的音轨控制 [#本地播放及发布至远端的音轨控制-1] 该版本新增 [`selectMultiAudioTrack:publishTrackIndex:`](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 [`openWithMediaSource:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并通过 [`AgoraMediaSource`](/zh-CN/api-reference/rtc/ios/class-mediasource) 中新增的 `enableMultiAudioTrack` 成员来开启音轨控制。 #### 音频采集及播放设备测试 [#音频采集及播放设备测试] 该版本新增下列方法，用于在加入频道前测试音频采集或播放设备能否正常工作： - [`startRecordingDeviceTest:`](/zh-CN/api-reference/rtc/ios/device-management/audio-device#startrecordingdevicetest)：用于测试本地音频采集设备（如外放设备）能否正常工作。调用该方法后，SDK 会按设置的时间间隔触发相关回调报告采集设备的音量信息。测试完毕后，你需要调用新增的 [`stopRecordingDeviceTest`](/zh-CN/api-reference/rtc/ios/device-management/audio-device#stoprecordingdevicetest) 方法停止测试。 - [`startPlaybackDeviceTest:`](/zh-CN/api-reference/rtc/ios/device-management/audio-device#startplaybackdevicetest)：用于在加入频道前测试音频播放设备能否正常工作。你可以通过 `testAudioFilePath` 参数指定需要播放的音频文件，测试者如果能听到声音，说明播放设备能正常工作。测试完毕后，你需要调用新增的 [`stopPlaybackDeviceTest`](/zh-CN/api-reference/rtc/ios/device-management/audio-device#stopplaybackdevicetest) 方法停止测试。 #### 其他 [#其他-8] 该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。 - [`setRemoteSubscribeFallbackOption:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_setremotesubscribefallbackoption)：设置弱网环境下订阅的音视频流回退选项。 - [`rtcEngine:didRemoteSubscribeFallbackToAudioOnly:byUid:`](/zh-CN/api-reference/rtc/ios/network#callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly)：订阅流已回退为音频流或恢复为音视频流回调。 - [`setPlayerOption:value:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption) 和 [`setPlayerOptionString:value:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption2)：设置媒体播放器选项，用于提供技术预览或特别定制功能。 - [`enableCustomAudioLocalPlayback:enabled:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback)：设置是否在本地播放外部音频源。 ### 改进 [#改进-26] #### 耳返音量提升 [#耳返音量提升-1] 该版本为用户提供更灵活的耳返音频调整选项，支持调用 [`setInEarMonitoringVolume:`](/zh-CN/api-reference/rtc/ios/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) 将耳返音量设置为原始音量的 4 倍。 #### 空间音频易用性提升 [#空间音频易用性提升-1] - 该版本优化了 [`setZones:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 方法的设计，支持将 `zones` 参数设置为 `NULL`，表示清除所有隔声区域。 - 自该版本起，在调用 [`AgoraLocalSpatialAudioKit`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_ilocalspatialaudioengine) 中的方法之前，无需先取消订阅频道内所有远端用户的音频流。 - 该版本新增 [`updateSelfTransform:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#updateselftransform) 方法，用于将位置向量传递到 iOS 原生的 SceneKit 或 RealityKit 等框架中直接进行渲染。 #### 本地音频状态回调优化 [#本地音频状态回调优化] 该版本在 [`AgoraAudioLocalReason`](/zh-CN/api-reference/rtc/ios/enum-localaudiostreamreason) 中增加了如下枚举，用户可通过 [`rtcEngine:localAudioStateChanged:reason:`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) 回调了解更多本地音频状态改变的原因： - `AgoraAudioLocalReasonInterrupted`：本地音频采集被系统来电、Siri、闹钟中断。如需恢复本地音频采集，请用户中止电话、Siri、闹钟。 #### 视频前处理方法优化 [#视频前处理方法优化-1] 该版本对以下 5 个视频前处理方法新增了带 `souceType` 参数的重载方法，支持通过传入 `sourceType` 来指定视频前处理特效应用的媒体源类型（例如应用在自定义的视频采集媒体源上）： - [`setBeautyEffectOptions:options:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions2) - [`setLowlightEnhanceOptions:options:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions2) - [`setVideoDenoiserOptions:options:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions2) - [`setColorEnhanceOptions:options:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions2) - [`enableVirtualBackground:backData:segData:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground2) #### 其他改进 [#其他改进-13] 该版本还进行了如下改进： - 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。 - 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用 [`setLocalAccessPoint:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_setlocalaccesspoint) 解析域名时的稳定性。 - 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。 - [`AgoraRtcLocalAudioStats`](/zh-CN/api-reference/rtc/ios/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。 - 新增 [`AgoraRtcMediaPlayer:cacheStats:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) 回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。 - 新增 [`AgoraRtcMediaPlayer:playbackStats:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) 回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过 [`AgoraMediaPlayerPlaybackStats`](/zh-CN/api-reference/rtc/ios/class-playerplaybackstats) 来获取当前音、视频的码率等信息。 - [`AgoraMusicContentCenterStateReason`](/zh-CN/api-reference/rtc/ios/enum-musiccontentcenterstatereason) 中新增状态码 `AgoraMusicContentCenterStateReasonErrorHttpInternalError` 表示 HTTP 内部发生错误，请稍后重试。 ### 问题修复 [#问题修复-32] 该版本修复了以下问题： - 当同时共享两路屏幕共享视频流时，[`rtcEngine:localVideoStats:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostats) 回调上报的 `captureFrameRate` 为 0，不符合预期。 ### API 变更 [#api-变更-9] #### 新增 [#新增-9] - [`rtcEngine:didTranscodedStreamLayoutInfoUpdatedWithUserId:videoLayoutInfo:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo) - `AgoraVideoLayoutInfo` - [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/ios/class-videocanvas) 新增 `subviewUid` 和 `uid` 成员 - [`updateSelfTransform:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#updateselftransform) - [`AgoraAudioLocalReason`](/zh-CN/api-reference/rtc/ios/enum-localaudiostreamreason) 中新增以下枚举 - `AgoraAudioLocalReasonInterrupted` - [`enableCustomAudioLocalPlayback:enabled:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback) - [`queryDeviceScore`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_querydevicescore) - [`AgoraMediaSourceType`](/zh-CN/api-reference/rtc/ios/enum-mediasourcetype) 中新增 `AgoraMediaSourceTypeCustomVideo` 枚举 - [`setBeautyEffectOptions:options:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions2) - [`setLowlightEnhanceOptions:options:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions2) - [`setVideoDenoiserOptions:options:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions2) - [`setColorEnhanceOptions:options:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions2) - [`enableVirtualBackground:backData:segData:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground2) - [`AgoraAudioOutputRouting`](/zh-CN/api-reference/rtc/ios/enum-audioroute) 中新增 `AgoraAudioOutputRoutingBluetoothDeviceA2dp` 枚举 - [`AgoraRtcLocalAudioStats`](/zh-CN/api-reference/rtc/ios/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员 - [`selectMultiAudioTrack:publishTrackIndex:`](/zh-CN/api-reference/rtc/ios/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) - [`AgoraRtcMediaPlayer:cacheStats:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) - [`AgoraRtcMediaPlayer:playbackStats:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) - [`AgoraMediaPlayerPlaybackStats`](/zh-CN/api-reference/rtc/ios/class-playerplaybackstats) - [`AgoraMusicContentCenterStateReason`](/zh-CN/api-reference/rtc/ios/enum-musiccontentcenterstatereason) 中新增 `AgoraMusicContentCenterStateReasonErrorHttpInternalError` - [`startPlaybackDeviceTest:`](/zh-CN/api-reference/rtc/ios/device-management/audio-device#startplaybackdevicetest) - [`stopPlaybackDeviceTest`](/zh-CN/api-reference/rtc/ios/device-management/audio-device#stopplaybackdevicetest) #### 修改 [#修改-3] - [`pushExternalVideoFrame:videoTrackId:`](/zh-CN/api-reference/rtc/ios/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe) 从 [`AgoraRtcEngineKitEx`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex) 接口类迁移到 [`AgoraRtcEngineKit`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 接口类 - `AgoraAudioOutputRoutingBluetooth` 枚举名变更为 `AgoraAudioOutputRoutingBluetoothDeviceHfp` - 以下枚举名中的 `Error` 字段全部修改为 `Reason`： - `AgoraAudioLocalErrorOK` - `AgoraAudioLocalErrorFailure` - `AgoraAudioLocalErrorDeviceNoPermission` - `AgoraAudioLocalErrorDeviceBusy` - `AgoraAudioLocalErrorRecordFailure` - `AgoraAudioLocalErrorEncodeFailure` - `AgoraLocalVideoStreamErrorOK` - `AgoraLocalVideoStreamErrorFailure` - `AgoraLocalVideoStreamErrorDeviceNoPermission` - `AgoraLocalVideoStreamErrorDeviceBusy` - `AgoraLocalVideoStreamErrorCaptureFailure` - `AgoraLocalVideoStreamErrorCodecNotSupport` - `AgoraLocalVideoStreamErrorCaptureInBackGround` - `AgoraLocalVideoStreamErrorCaptureMultipleForegroundApps` - `AgoraLocalVideoStreamErrorCaptureNoDeviceFound` - `AgoraLocalVideoStreamErrorCaptureDeviceDisconnected` - `AgoraLocalVideoStreamErrorCaptureDeviceInvalidId` - `AgoraDirectCdnStreamingErrorOK` - `AgoraDirectCdnStreamingErrorFailed` - `AgoraDirectCdnStreamingErrorAudioPublication` - `AgoraDirectCdnStreamingErrorVideoPublication` - `AgoraDirectCdnStreamingErrorNetConnect` - `AgoraDirectCdnStreamingErrorBadName` - `AgoraMediaPlayerErrorNone` - `AgoraMediaPlayerErrorInvalidArguments` - `AgoraMediaPlayerErrorInternal` - `AgoraMediaPlayerErrorNoSource` - `AgoraMediaPlayerErrorInvalidMediaSource` - `AgoraMediaPlayerErrorUnknowStreamType` - `AgoraMediaPlayerErrorObjNotInitialized` - `AgoraMediaPlayerErrorCodecNotSupported` - `AgoraMediaPlayerErrorVideoRenderFailed` - `AgoraMediaPlayerErrorInvalidState` - `AgoraMediaPlayerErrorUrlNotFound` - `AgoraMediaPlayerErrorInvalidConnectState` - `AgoraMediaPlayerErrorSrcBufferUnderflow` - `AgoraMediaPlayerErrorInterrupted` - `AgoraMediaPlayerErrorNotSupported` - `AgoraMediaPlayerErrorTokenExpired` - `AgoraMediaPlayerErrorUnknown` - `AgoraRtmpStreamingErrorOK` - `AgoraRtmpStreamingErrorInvalidParameters` - `AgoraRtmpStreamingErrorEncryptedStreamNotAllowed` - `AgoraRtmpStreamingErrorConnectionTimeout` - `AgoraRtmpStreamingErrorInternalServerError` - `AgoraRtmpStreamingErrorRtmpServerError` - `AgoraRtmpStreamingErrorTooOften` - `AgoraRtmpStreamingErrorReachLimit` - `AgoraRtmpStreamingErrorNotAuthorized` - `AgoraRtmpStreamingErrorStreamNotFound` - `AgoraRtmpStreamingErrorFormatNotSupported` - `AgoraRtmpStreamingErrorNotBroadcaster` - `AgoraRtmpStreamingErrorTranscodingNoMixStream` - `AgoraRtmpStreamingErrorNetDown` - `AgoraRtmpStreamingErrorInvalidPrivilege` - `AgoraRtmpStreamingErrorUnpublishOK` - `AgoraMusicContentCenterStatusCode` 修改为 [`AgoraMusicContentCenterStateReason`](/zh-CN/api-reference/rtc/ios/enum-musiccontentcenterstatereason)，其中的枚举名的 `StatusErr` 字段全部修改为 `Reason`： - `AgoraMusicContentCenterStateReasonErrorGateway` - `AgoraMusicContentCenterStateReasonErrorPermissionAndResource` - `AgoraMusicContentCenterStateReasonErrorInternalDataParse` - `AgoraMusicContentCenterStateReasonErrorMusicLoading` - `AgoraMusicContentCenterStateReasonErrorMusicDecryption` - `AgoraMusicContentCenterStatusCodeError` 修改为 `AgoraMusicContentCenterStateReasonError` #### 删除 [#删除-5] - `startChannelMediaRelay` - `updateChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - `didReceiveChannelMediaRelayEvent` - `AgoraChannelMediaRelayEvent` ## v4.2.6 [#v426-1] 该版本于 2023 年 11 月 16 日发布。 ### 问题修复 [#问题修复-33] 该版本修复了以下问题： - 使用 iOS 16 版本或以上设备在加入频道前连接了蓝牙耳机，在加入频道后的音频路由不符合预期：音频从扬声器播放、而非蓝牙耳机。 - 在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。 ## v4.2.3 [#v423-1] 该版本于 2023 年 10 月 12 日发布。 ### 新增特性 [#新增特性-24] #### 本地截图上传更新 [#本地截图上传更新-1] 为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动： - [`AgoraContentInspectType`](/zh-CN/api-reference/rtc/ios/enum-contentinspecttype) 中新增 `AgoraContentInspectTypeImageModeration` 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。 - [`AgoraContentInspectConfig`](/zh-CN/api-reference/rtc/ios/class-contentinspectconfig) 中新增的 `serverConfig` 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请[联系技术支持](https://ticket.shengwang.cn/)。 此外，该版本还新增了 [`enableContentInspectEx:config:connection:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) 方法，支持同时对多条视频流截图并上传。 #### 进阶功能查询 [#进阶功能查询-1] 该版本新增了 [`isFeatureAvailableOnDevice:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_isfeatureavailableondevice) 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。 在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。 此外，自该版本起，调用 `enableVirtualBackground` 和 `setBeautyEffectOptions` 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 `-4` 表示该设备不支持开启该功能。 ### 改进 [#改进-27] #### SDK 任务处理调度优化 [#sdk-任务处理调度优化-1] 该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面： - 远端及本地的首帧出图与出声速度提升了 10% 到 20%。 - API 的调用耗时和响应耗时缩短了 5% 到 50%。 - SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。 - SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。 #### 优化虚拟背景内存占用 [#优化虚拟背景内存占用-1] 该版本升级了虚拟背景算法，降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。 #### 其他改进 [#其他改进-14] 该版本还进行了如下改进： - 当调用 [`setPlaybackSpeed:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，传入非法参数后会返回错误码 `-2`，表示方法中设置了无效的参数，需要重新设置参数。 - 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。 ### 问题修复 [#问题修复-34] 该版本修复了以下问题： - 本地系统时间不正确时，偶现加入频道失败。 - 调用 `playEffect` 使用相同的 `soundId` 播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 - 合唱场景下，调用 [`preloadWithSongCode:jsonOption:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_preload) 加载音乐，偶现加载失败。 - 当本地系统时间不准确时，歌曲榜单加载失败。 - 调用一次 [`takeSnapshotEx:uid:filePath:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 获取视频截图会收到多次 [`rtcEngine:snapshotTaken:filePath:width:height:errCode:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 视频截图结果回调。 ### API 变更 [#api-变更-10] #### 新增 [#新增-10] - [`enableContentInspectEx:config:connection:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) - [`AgoraContentInspectType`](/zh-CN/api-reference/rtc/ios/enum-contentinspecttype) 新增 `AgoraContentInspectTypeImageModeration` - [`AgoraContentInspectConfig`](/zh-CN/api-reference/rtc/ios/class-contentinspectconfig) 中新增 `serverConfig` 可选参数 - [`isFeatureAvailableOnDevice:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_isfeatureavailableondevice) - [`AgoraFeatureType`](/zh-CN/api-reference/rtc/ios/enum-featuretype) ## v4.2.2 [#v422-1] 该版本于 2023 年 7 月 27 日发布。 ### 升级必看 [#升级必看-21] 该版本废弃了 [`AgoraMusicContentCenter`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusiccontentcenter) 类下的 [`preloadWithSongCode:jsonOption:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_preload) 方法并新增 [`preloadWithSongCode:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_preload2) 方法。如果你使用了 [`preloadWithSongCode:jsonOption:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_preload) 方法实现预加载音乐资源，请在升级到该版本后更新 App 代码。 ### 新增特性 [#新增特性-25] #### 通配 Token [#通配-token-1] 该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 :::warning[注意] 声网 4.x RTC SDK 均支持使用通配 Token。 ::: #### 预加载频道 [#预加载频道-1] 该版本新增 [`preloadChannelByToken:channelId:uid:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengine_preloadchannel) 和 [`preloadChannelByTokenWithUserAccount:channelId:userAccount:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengine_preloadchannelwithuseraccount) 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。 在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 #### 自定义视频画布背景颜色 [#自定义视频画布背景颜色-1] 该版本在 [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/ios/class-videocanvas) 中增加了 `backgroundColor` 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。 #### 指定视频源进行预览 [#指定视频源进行预览] 为支持用户选择不同类型的视频源进行本地视频预览，该版本新增 [`startPreview:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 和 [`stopPreview:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_stoppreview2) 方法。你可以调用 [`startPreview:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) 并设置 `sourceType` 指定待预览的视频源类型；然后调用 [`stopPreview:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_stoppreview2) 关闭视频预览。 :::warning[注意] 该方法中设置的视频源类型需要跟 `setupLocalVideo` 中 `AgoraRtcVideoCanvas` 的视频源类型一致。 ::: #### 支持仅播放副歌片段 [#支持仅播放副歌片段-1] 该版本新增 [`getInternalSongCode:jsonOption:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_getinternalsongcode) 方法，如果你仅需要播放某一音乐资源的副歌片段，在播放前你需要调用该方法来为该副歌片段创建一个内部歌曲编号，作为该资源的唯一标识。你可以查看[在线 K 歌房文档](/zh-CN/solutions/online-ktv)了解更多 K 歌场景方案。 ### 改进 [#改进-28] #### 摄像头采集效果提升 [#摄像头采集效果提升-1] 该版本从以下几个方面提升了摄像头采集效果： - 支持摄像头采集曝光调节 新增 [`isCameraExposureSupported`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_iscameraexposuresupported) 和 [`setCameraExposureFactor:`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameraexposurefactor) 方法，用于查询当前设备是否支持曝光调节和设置摄像头的曝光增益。 - 优化默认摄像头选择 自该版本起，SDK 的默认摄像头选择对齐 iOS 系统相机行为。如果设备拥有多个后置摄像头，则在视频采集时可以获得更好的拍摄视野、变焦能力、低光性能和深度感应，从而提高视频采集的质量。 #### 虚拟背景算法升级 [#虚拟背景算法升级-1] 该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。 #### 跨频道连麦优化 [#跨频道连麦优化-1] 该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 时，你可以指定最多 6 个目标频道。 #### 视频编解码查询能力增强 [#视频编解码查询能力增强-1] 为提升设备编解码能力查询功能，该版本在 `CodecCapAgoraVideoCodecCapInfoInfo` 中新增 `codecLevels` 成员。当成功调用 [`queryCodecCapability`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_querycodeccapability) 后，可通过 `codecLevels` 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。 #### 其他改进 [#其他改进-15] - 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。 - 为帮助用户了解更多类型的远端视频状态改变的原因，[`rtcEngine:remoteVideoStateChangedOfUid:state:reason:elapsed:`](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调中新增了 `AgoraVideoRemoteReasonCodecNotSupport` 枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。 - 版权音乐新增 [`getSongSimpleInfoWithSongCode:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_getsongsimpleinfo) 方法，可用于获取某一指定歌曲的详细信息，你可以通过触发的 [`onSongSimpleInfoResult:songCode:simpleInfo:reason:`](/zh-CN/api-reference/rtc/ios/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) 回调来获取歌曲信息。 ### 问题修复 [#问题修复-35] 该版本修复了以下问题： - 网络异常导致频道连接断开后，频道连接恢复较慢。 - 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。 - 自采集场景下，`setBeautyEffectOptions`、`setLowlightEnhanceOptions`、`setVideoDenoiserOptions` 和 `setColorEnhanceOptions` 无法自动加载插件。 ### API 变更 [#api-变更-11] #### 新增 [#新增-11] - [`startPreview:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview2) - [`stopPreview:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_stoppreview2) - [`setCameraExposureFactor:`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_setcameraexposurefactor) - [`isCameraExposureSupported`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_iscameraexposuresupported) - [`preloadChannelByToken:channelId:uid:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengine_preloadchannel) - [`preloadChannelByTokenWithUserAccount:channelId:userAccount:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengine_preloadchannelwithuseraccount) - [`updatePreloadChannelToken:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengine_updatepreloadchanneltoken) - [`getSongSimpleInfoWithSongCode:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_getsongsimpleinfo) - [`onSongSimpleInfoResult:songCode:simpleInfo:reason:`](/zh-CN/api-reference/rtc/ios/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) - [`getInternalSongCode:jsonOption:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_getinternalsongcode) - [`preloadWithSongCode:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_preload2) - [`onLyricResult:songCode:lyricUrl:reason:`](/zh-CN/api-reference/rtc/ios/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 中增加 `songCode` - [`onPreLoadEvent:songCode:percent:lyricUrl:state:reason:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onpreloadevent) 中增加 `requestId` - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中增加下列成员： - `publishThirdCameraTrack` - `publishFourthCameraTrack` - `publishThirdScreenTrack` - `publishFourthScreenTrack` - [`AgoraVideoCodecCapLevels`](/zh-CN/api-reference/rtc/ios/class-codeccaplevels) - [`AgoraVideoCodecCapabilityLevel`](/zh-CN/api-reference/rtc/ios/enum-videocodeccapabilitylevel) - [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/ios/class-videocanvas) 中增加 `backgroundColor` 成员 - `CodecCapAgoraVideoCodecCapInfoInfo` 中增加 `codecLevels` 成员 - [`AgoraVideoRemoteReason`](/zh-CN/api-reference/rtc/ios/enum-remotevideostatereason) 中增加 `AgoraVideoRemoteReasonCodecNotSupport` 枚举 #### 废弃 [#废弃-5] - [`preloadWithSongCode:jsonOption:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_preload) ## v4.2.1 [#v421-1] 该版本于 2023 年 6 月 21 日发布。 ### 改进 [#改进-29] 该版本改进了网络传输策略，提升了音视频交互的流畅度。 ### 问题修复 [#问题修复-36] 该版本修复了以下问题： - SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。 - 发送端调用 [`setAINSMode:mode:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。 - 调用 [`destroyMediaPlayer:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-initialize#api_irtcengine_destroymediaplayer) 销毁媒体播放器时偶现崩溃。 ## v4.2.0 [#v420-1] 该版本于 2023 年 5 月 24 日发布。 ### 升级必看 [#升级必看-22] 该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。 #### 视频采集 [#视频采集] 原有用于摄像头采集的方法已删除，请改用下表中列出的替代方法，并通过设置 `sourceType` 来指定视频源。 | 已删除方法 | 替代方法 | | :------------------------------------------------------- | :----------------------- | | `startSecondaryCameraCapture` | [`startCameraCapture:config:`](/zh-CN/api-reference/rtc/ios/video/camera-capture#api_irtcengine_startcameracapture) | | `stopSecondaryCameraCapture` | [`stopCameraCapture:`](/zh-CN/api-reference/rtc/ios/video/camera-capture#api_irtcengine_stopcameracapture) | #### 视频数据获取 [#视频数据获取-1] - [`onCaptureVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调中新增了 `sourceType` 参数，用于表示具体的视频源类型。 - 以下回调已删除，请通过 [`onPreEncodeVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 和 [`onCaptureVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 中的 `sourceType` 参数得知视频源类型。 - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` #### 媒体发布选项 [#媒体发布选项-1] - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` 已删除，请改用 `publishCustomAudioTrack`。 - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中的成员 `publishTrancodedVideoTrack` 变更为 `publishTranscodedVideoTrack`. - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中的成员 `publishCustomAudioSourceId` 变更为 `publishCustomAudioTrackId`。 #### 音视频录制 [#音视频录制-1] - 删除 `sharedMediaRecorderWithRtcEngine` 方法，可通过该版本新增的 [`createMediaRecorder:`](/zh-CN/api-reference/rtc/ios/recording#api_irtcengine_createmediarecorder) 方法来创建录制对象。 - 删除 [`startRecording:`](/zh-CN/api-reference/rtc/ios/recording#api_imediarecorder_startrecording) 、[`stopRecording`](/zh-CN/api-reference/rtc/ios/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderDelegate:`](/zh-CN/api-reference/rtc/ios/recording#api_imediarecorder_setmediarecorderobserver) 中的 `connection` 参数。 - 删除 [`AgoraMediaRecorder`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imediarecorder) 类中的 `destroy` 方法，你可直接调用该版本新增的 [`destroyMediaRecorder:`](/zh-CN/api-reference/rtc/ios/recording#api_irtcengine_destroymediarecorder) 方法来销毁录制对象以释放资源。 #### 其他兼容性变更 [#其他兼容性变更-1] - `didApiCallExecute` 已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。 - [`enableDualStreamMode:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_enabledualstreammode) 和 [`enableDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_enabledualstreammode3) 已废弃，请改用 [`setDualStreamMode:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setdualstreammode) 和 [`setDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setdualstreammode2)。 - `startChannelMediaRelay`、`updateChannelMediaRelay`、`startChannelMediaRelayEx` 和 `updateChannelMediaRelayEx` 已废弃，请改用 [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex)。 ### 新增特性 [#新增特性-26] #### AI 降噪 [#ai-降噪-1] 该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 [`setAINSMode:mode:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。 #### 增强虚拟背景 [#增强虚拟背景-1] 为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 `enableVirtualBackground` 方法时，将自定义背景设置为更多类型： - 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。 - 将背景替换为多种格式的本地视频。 #### 视频场景化设置 [#视频场景化设置-1] 该版本新增 [`setVideoScenario:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoscenario) 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化： - 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。 - 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。 #### 本地录制远端音视频 (Beta) [#本地录制远端音视频-beta-1] 该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 [`mediaRecorder:stateDidChanged:uid:state:reason:`](/zh-CN/api-reference/rtc/ios/recording#callback_imediarecorderobserver_onrecorderstatechanged) 、[`mediaRecorder:informationDidUpdated:uid:info:`](/zh-CN/api-reference/rtc/ios/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数，用于表示录制的音视频流的具体信息，并新增 [`createMediaRecorder:`](/zh-CN/api-reference/rtc/ios/recording#api_irtcengine_createmediarecorder) 方法，用于创建本地或远端的录制对象。 你可以通过如下方法体验本地录制远端音视频功能： - [`createMediaRecorder:`](/zh-CN/api-reference/rtc/ios/recording#api_irtcengine_createmediarecorder)：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。 - [`setMediaRecorderDelegate:`](/zh-CN/api-reference/rtc/ios/recording#api_imediarecorder_setmediarecorderobserver)：设置录制回调对象。 - [`startRecording:`](/zh-CN/api-reference/rtc/ios/recording#api_imediarecorder_startrecording)：开始录制。 - [`stopRecording`](/zh-CN/api-reference/rtc/ios/recording#api_imediarecorder_stoprecording)：停止录制。 - [`destroyMediaRecorder:`](/zh-CN/api-reference/rtc/ios/recording#api_irtcengine_destroymediarecorder)：销毁录制对象。 #### 本地合图 [#本地合图-1] 该版本新增本地合图功能，用户可以调用 [`startLocalVideoTranscoder:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) 方法，在本地将多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）混合和渲染，以实现自定义布局和效果。通过这项功能，你可以轻松创建个性化的视频显示效果，满足各种场景需求，如远程会议、直播、在线教育场景，同时支持人像画中画等功能。 另外，SDK 还提供了[`updateLocalTranscoderConfiguration:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 方法和 [`rtcEngine:didLocalVideoTranscoderErrorWithStream:errorCode:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调。当你在开启本地合图后，可以调用 [`updateLocalTranscoderConfiguration:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 更新合图的配置；当你在开启本地合图或者更新本地合图配置失败时，可通过 [`rtcEngine:didLocalVideoTranscoderErrorWithStream:errorCode:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调得知合图失败的原因。 :::warning[注意] 本地合图对 CPU 的消耗较高，声网建议你在性能较高的设备上开启该功能。 ::: #### 多端同步 [#多端同步-1] 在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_getntpwalltimeinms) 方法获取当前的 NTP (网络时间协议) 时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。 ### 改进 [#改进-30] #### 优化变声 [#优化变声-1] 该版本新增了 [`setLocalVoiceFormant:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceformant) 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 [`setLocalVoicePitch:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch) 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。 #### 增强屏幕共享 [#增强屏幕共享-1] 该版本新增 [`queryScreenCaptureCapability`](/zh-CN/api-reference/rtc/ios/video/screencapture#api_irtcengine_queryscreencapturecapability) 方法，用于查询当前设备的屏幕捕获能力。如果你想在屏幕共享时启用高帧率（如 60 fps）、但不确定设备是否支持时，可以调用该方法、然后从返回值中得知设备支持的最高帧率是否满足需求。 该版本新增 [`setScreenCaptureScenario:`](/zh-CN/api-reference/rtc/ios/video/screencapture#api_irtcengine_setscreencapturescenario) 方法，用于设置屏幕共享的场景类型，SDK 会根据场景类型自动调整共享画面的的流畅度和清晰度。 #### 提升音视频同步能力 [#提升音视频同步能力-1] 针对自定义视频和音频采集场景，该版本新增 [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_getcurrentmonotonictimeinms) 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。 #### 优化多路摄像头采集 [#优化多路摄像头采集-1] 该版本新增 [`startCameraCapture:config:`](/zh-CN/api-reference/rtc/ios/video/camera-capture#api_irtcengine_startcameracapture) 方法，通过多次调用并指定 `sourceType` 参数可以同时开启多路摄像头采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头的场景。 #### 优化版权音乐 [#优化版权音乐-1] 针对在线 K 歌房场景，改版本新增 [`getCaches`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_getcaches) 和 [`removeCacheWithSongCode:`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_removecache) 方法，用于获取、删除音乐资源缓存，并新增状态码和错误码，可方便用户排查问题。 #### 优化跨频道连麦 [#优化跨频道连麦-1] 该版本新增 [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。 #### 多路音频自采集 [#多路音频自采集-1] 为更好地满足音频自采集的场景需求，该版本新增了 [`createCustomAudioTrack:config:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 和 [`destroyCustomAudioTrack:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#destroycustomaudiotrack) 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性： - 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。 - 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。 ### 问题修复 [#问题修复-37] 该版本修复了以下问题： - 当快速切换身份角色时，观众端听不到声音。 - 跨频道连麦时 [`rtcEngine:firstRemoteVideoFrameOfUid:size:elapsed:`](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onfirstremotevideoframe) 回调偶现丢失。 - 接收端主动订阅大流但是异常接收小流。 - 由于 [`rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed:`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged) 回调异常造成客户端状态异常。 ### API 变更 [#api-变更-12] #### 新增 [#新增-12] - [`startCameraCapture:config:`](/zh-CN/api-reference/rtc/ios/video/camera-capture#api_irtcengine_startcameracapture) - [`stopCameraCapture:`](/zh-CN/api-reference/rtc/ios/video/camera-capture#api_irtcengine_stopcameracapture) - [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) - [`startOrUpdateChannelMediaRelayEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) - [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_getntpwalltimeinms) - [`setVideoScenario:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoscenario) - [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_getcurrentmonotonictimeinms) - [`rtcEngine:didLocalVideoTranscoderErrorWithStream:errorCode:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) - [`startLocalVideoTranscoder:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) - [`updateLocalTranscoderConfiguration:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) - [`queryScreenCaptureCapability`](/zh-CN/api-reference/rtc/ios/video/screencapture#api_irtcengine_queryscreencapturecapability) - [`setScreenCaptureScenario:`](/zh-CN/api-reference/rtc/ios/video/screencapture#api_irtcengine_setscreencapturescenario) - [`setAINSMode:mode:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) - [`createCustomAudioTrack:config:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) - [`destroyCustomAudioTrack:`](/zh-CN/api-reference/rtc/ios/audio/audio-custom-capturenrendering#destroycustomaudiotrack) - [`createMediaRecorder:`](/zh-CN/api-reference/rtc/ios/recording#api_irtcengine_createmediarecorder) - [`destroyMediaRecorder:`](/zh-CN/api-reference/rtc/ios/recording#api_irtcengine_destroymediarecorder) - [`AgoraMusicContentCenter`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusiccontentcenter) - `removeCache` - [`getCaches`](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_getcaches) - `AudioTrackConfig` - [`AgoraMusicCacheInfo`](/zh-CN/api-reference/rtc/ios/class-musiccacheinfo) - [`AgoraRecorderStreamInfo`](/zh-CN/api-reference/rtc/ios/class-recorderstreaminfo) - [`AUDIO_AINS_MODE`](/zh-CN/api-reference/rtc/ios/enum-audioainsmode) - [`AgoraAudioTrackType`](/zh-CN/api-reference/rtc/ios/enum-audiotracktype) - [`AgoraMusicCacheStatusType`](/zh-CN/api-reference/rtc/ios/enum-musiccachestatustype) - [`AgoraApplicationScenarioType`](/zh-CN/api-reference/rtc/ios/enum-videoapplicationscenariotype) - [`AgoraScreenCaptureFrameRateCapability`](/zh-CN/api-reference/rtc/ios/enum-screencaptureframeratecapability) - [`AgoraRtcEngineConfig`](/zh-CN/api-reference/rtc/ios/class-rtcengineconfig) 中新增 `domainLimit` 和 `autoRegisterAgoraExtensions` 属性 - [`mediaRecorder:stateDidChanged:uid:state:reason:`](/zh-CN/api-reference/rtc/ios/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`mediaRecorder:informationDidUpdated:uid:info:`](/zh-CN/api-reference/rtc/ios/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数 - [`onCaptureVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 中增加 `sourceType` 参数 - [`AgoraVirtualBackgroundSourceType`](/zh-CN/api-reference/rtc/ios/enum-backgroundsourcetype) 中新增 `AgoraVirtualBackgroundNone` 和 `AgoraVirtualBackgroundVideo` - [`AgoraMusicContentCenterPreloadStatus`](/zh-CN/api-reference/rtc/ios/enum-preloadstate) 中增加 `AgoraMusicContentCenterPreloadStatusRemoveCache` - `AgoraMusicContentCenterStatusCode` 中增加如下枚举： - `AgoraMusicContentCenterStatusCodeErrorGateway` - `AgoraMusicContentCenterStatusCodeErrorPermissionAndResource` - `AgoraMusicContentCenterStatusCodeErrorInternalDataParse` - `AgoraMusicContentCenterStatusCodeErrorMusicLoadin` - `AgoraMusicContentCenterStatusCodeErrorMusicDecryption` - [`AgoraMusicContentCenterConfig`](/zh-CN/api-reference/rtc/ios/class-musiccontentcenterconfiguration) 中新增 `maxCacheSize` #### 修改 [#修改-4] - [`onMusicChartsResult:result:reason:`](/zh-CN/api-reference/rtc/ios/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 中的 `status` 修改为 `errorCode` - [`onMusicCollectionResult:result:reason:`](/zh-CN/api-reference/rtc/ios/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 中的 `status` 修改为 `errorCode` - [`onLyricResult:songCode:lyricUrl:reason:`](/zh-CN/api-reference/rtc/ios/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 中的 `status` 修改为 `errorCode` - `onPreLoadEvent `中的 `msg` 修改为 `errorCode` #### 废弃 [#废弃-6] - [`enableDualStreamMode:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_enabledualstreammode) - [`enableDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_enabledualstreammode3) - `startChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelay` - `updateChannelMediaRelayEx` - `didReceiveChannelMediaRelayEvent` - `AgoraChannelMediaRelayEvent` #### 删除 [#删除-6] - `startSecondaryCameraCapture` - `stopSecondaryCameraCapture` - `didApiCallExecute` - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中的 ` publishCustomAudioTrackEnableAec` - `sharedMediaRecorderWithRtcEngine` - [`AgoraMediaRecorder`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imediarecorder) 类中的 `destroy` - [`startRecording:`](/zh-CN/api-reference/rtc/ios/recording#api_imediarecorder_startrecording)、[`stopRecording`](/zh-CN/api-reference/rtc/ios/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderDelegate:`](/zh-CN/api-reference/rtc/ios/recording#api_imediarecorder_setmediarecorderobserver) 中删除 `connection` 参数 - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` ## v4.1.1 [#v411-1] 该版本于 2023 年 2 月 8 日发布。 ### 升级必看 [#升级必看-23] #### 默认分辨率 [#默认分辨率] 自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。 如果你想自定义视频编码分辨率，可调用 [`setVideoEncoderConfiguration:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法，重新设置视频编码参数配置中的视频编码分辨率。 :::note 由于默认分辨率的提升，会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 设置远端视频流的订阅选项 [#设置远端视频流的订阅选项] 该版本起，`setRemoteVideo` 更名为 [`setRemoteVideoSubscriptionOptions:options:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions)；`setRemoteVideoEx` 更名为 [`setRemoteVideoSubscriptionOptionsEx:options:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex)。如果你将 SDK 升级至该版本或更高版本，请在调用处同步修改以上两个方法的名称。 ### 新增特性 [#新增特性-27] #### 快速出图出声 [#快速出图出声-1] 该版本新增 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_enableinstantmediarendering) 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。 #### 视频渲染数据打点 [#视频渲染数据打点-1] 该版本新增 [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_startmediarenderingtracing) 和 [`startMediaRenderingTracingEx:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 [`rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告相关事件的信息。 声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 [`rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。 ### 改进 [#改进-31] #### 视频观测器 [#视频观测器-1] 自该版本起，SDK 对 [`onRenderVideoFrame:uid:channelId:`](/zh-CN/api-reference/rtc/ios/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 回调进行了优化，在不同的视频处理模式下返回值的意义不同： - 当视频处理模式为 `AgoraVideoFrameProcessModeReadOnly` 时，返回值无实际含义。 - 当视频处理模式为 `AgoraVideoFrameProcessModeReadWrite` 时，返回 `YES` 代表设置 SDK 接收视频帧；返回 `NO` 代表设置 SDK 丢弃视频帧。 #### 超分辨率 [#超分辨率-1] 该版本提升了超分辨率的性能表现。为提升超分辨率易用性，该版本删除了 `enableRemoteSuperResolution`，超分辨率纳入画质增强线上策略的一部分，无需单独设置即可体验。 ### 问题修复 [#问题修复-38] 该版本修复了以下问题： - 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。 - 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。 - 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。 ### API 变更 [#api-变更-13] #### 新增 [#新增-13] - [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_enableinstantmediarendering) - [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengine_startmediarenderingtracing) - [`startMediaRenderingTracingEx:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) - [`rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:`](/zh-CN/api-reference/rtc/ios/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) - [`AgoraMediaTraceEvent`](/zh-CN/api-reference/rtc/ios/enum-mediatraceevent) - [`AgoraVideoRenderingTracingInfo`](/zh-CN/api-reference/rtc/ios/class-videorenderingtracinginfo) #### 修改 [#修改-5] - `setRemoteVideo` 更名为 [`setRemoteVideoSubscriptionOptions:options:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) - `setRemoteVideoEx` 更名为 [`setRemoteVideoSubscriptionOptionsEx:options:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) #### 删除 [#删除-7] - `enableRemoteSuperResolution` - [`AgoraRtcRemoteVideoStats`](/zh-CN/api-reference/rtc/ios/class-remotevideostats) 中删除 `superResolutionType` ## v4.1.0 [#v410] 该版本于 2022 年 12 月 19 日发布。 ### 新增特性 [#新增特性-28] #### 多路摄像头 [#多路摄像头] 该版本新增多路摄像头视频采集功能，你可以通过调用 [`enableMultiCamera:config:`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_enablemulticamera) 开启多路摄像头采集模式，再调用 `startSecondaryCameraCapture` 通过第二个摄像头采集视频，然后将采集到的视频发布到多频道中。 如需停止多路摄像头采集，需要先调用 `stopSecondaryCameraCapture` 停止第二个摄像头采集，然后调用 [`enableMultiCamera:config:`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_enablemulticamera) 并将 `enabled` 设置为 `NO`。 #### 版权音乐 [#版权音乐-1] 为解决直播、语聊房、在线 K 歌房等场景下歌曲的应用版权问题，该版本新增版权音乐相关 API。你可以通过调用 [`AgoraMusicContentCenter`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusiccontentcenter) 、[`AgoraMusicPlayerProtocol`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusicplayer) 、[`AgoraMusicContentCenterEventDelegate`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusiccontentcentereventhandler) 类下的相关 API 实现在实时互动场景中播放版权音乐以及相关功能，例如检索音乐资源、获取音乐榜单及榜单详情、预加载及播放音乐资源、下载歌词及海报等功能。你还可以参考[在线 K 歌房](/zh-CN/solutions/online-ktv)来体验搭配了演唱评分、美声音效等一系列功能的线上 K 歌场景化解决方案。 #### 耳机均衡器 [#耳机均衡器-1] 该版本新增 [`setHeadphoneEQParameters:highGain:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) 方法，用于调节耳机均衡器的低频和高频参数，主要应用于空间音频场景。如果在调用 [`setHeadphoneEQPreset:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。 #### 编码视频帧观测器 [#编码视频帧观测器] 该版本在 [`AgoraRtcEngineKit`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 及 [`AgoraRtcEngineKitEx`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex) 中新增 `setRemoteVideo` 方法，当你调用 `setEncodedVideoFrameDelegate` 方法为编码后的视频注册视频帧观测器时，SDK 默认订阅编码后的视频帧。如果你想要修改订阅选项，可以调用该新增的方法进行设置。 有关更多注册视频观测器和订阅选项的介绍，详见 [API 参考](/zh-CN/api-reference/rtc/ios/video/video-encoded#api_irtcengine_registervideoencodedframeobserver)。 #### MPUDP (MultiPath UDP) [#mpudp-multipath-udp-1] 自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在移动端和桌面端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。 :::info[信息] 如果你希望体验该功能，请联系 sales@shengwang.cn。 ::: #### 摄像头采集选项 [#摄像头采集选项-1] 该版本在 [`AgoraCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/ios/class-cameracapturerconfiguration) 中增加了 `followEncodeDimensionRatio` 成员，你可以在使用摄像头采集视频时，通过该成员设置是否跟随 [`setVideoEncoderConfiguration:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中已经设置的视频宽高比。 #### 多频道管理 [#多频道管理-1] 该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。 - 新增 [`muteLocalAudioStreamEx:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) 和 [`muteLocalVideoStreamEx:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) 方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增 [`muteAllRemoteAudioStreamsEx:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) 和 [`muteAllRemoteVideoStreamsEx:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) 方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增 [`startRtmpStreamWithoutTranscodingEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex)、[`startRtmpStreamWithTranscodingEx:transcoding:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex)、[`updateRtmpTranscodingEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) 和 [`stopRtmpStreamEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) 方法，用于实现多频道场景下的旁路推流。 - 新增 `startChannelMediaRelayEx`、`updateChannelMediaRelayEx`、[`pauseAllChannelMediaRelayEx:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex)、[`resumeAllChannelMediaRelayEx:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) 和 `stopChannelMediaRelayEx` 方法，用于实现多频道场景下的跨频道媒体流转发。 - 新增 [`leaveChannelEx:options:leaveChannelBlock:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengineex_leavechannelex2) 方法，相较于 [`leaveChannelEx:leaveChannelBlock:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengineex_leavechannelex) 方法新增了 `options` 参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。 #### 视频编码偏好 [#视频编码偏好-1] 一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 [`AgoraVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/ios/class-videoencoderconfiguration) 中新增 `advancedVideoOptions` 成员，用于视频编码属性的进阶设置： - `compressionPreference`：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。 - `encodingPreference`：视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。 #### 日志上传 [#日志上传-1] 使用声网私有媒体服务器的场景下，为支持用户在调用 [`setLocalAccessPoint:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_setlocalaccesspoint) 方法时的进阶设置，该版本在 [`AgoraLocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/ios/class-localaccesspointconfiguration) 中新增 `advancedConfig` 成员参数，该参数支持如下设置： `logUploadServer`：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。 #### 用户角色切换 [#用户角色切换-1] 为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 [`rtcEngine:didClientRoleChanged:newRole:newRoleOptions:`](/zh-CN/api-reference/rtc/ios/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调中新增 `newRoleOptions` 参数，该参数取值如下： - `AgoraAudienceLatencyLevelLowLatency`(1): 低延时，属于极速直播。 - `AgoraAudienceLatencyLevelUltraLowLatency`(2): 超低延时，属于互动直播。 ### 改进 [#改进-32] #### CDN 推流 [#cdn-推流-1] 为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 `onDirectCdnStreamingStats:` 回调报告推送的视频流的实际分辨率。 #### 跨频道媒体流转发 [#跨频道媒体流转发-3] 该版本对 `updateChannelMediaRelay` 方法做了如下优化： - 4.1.0 版本前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码 `AgoraChannelMediaRelayEventUpdateDestinationChannelRefused`(8)，你需要重新调用 `updateChannelMediaRelay` 方法。 - 4.1.0 版本及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。 #### AIAEC [#aiaec-1] 该版本基于 AI 方法重构了AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。 #### 虚拟背景 [#虚拟背景-1] 该版本对虚拟背景算法做了如下优化： - 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。 - 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。 - 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。 - 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。 #### 其他改进 [#其他改进-16] - 降低了推送外部音频源时的上行延迟。 - 提升了会议场景 (`AgoraAudioScenarioMeeting`) 默认参数配置下的回声消除性能。 - 提升了 SDK 视频渲染的流畅度。 - 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。 ### 问题修复 [#问题修复-39] 该版本修复了以下问题： - 调用 `startAudioMixing` 播放 `ipod-library://item` 路径的音乐文件失败。 - 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。 - 同时通过 [`onRecordAudioFrame:channelId:`](/zh-CN/api-reference/rtc/ios/audio/audio-raw#callback_iaudioframeobserver_onrecordaudioframe) 和 [`onCaptureVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 回调分别获取的音频和视频数据时间戳不同。 - 调用 `getExtensionPropertyWithVendor` 失败，返回空字符串。 - 当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。 ### API 变更 [#api-变更-14] #### 新增 [#新增-14] - [`enableMultiCamera:config:`](/zh-CN/api-reference/rtc/ios/device-management/video-device#api_irtcengine_enablemulticamera) - `startSecondaryCameraCapture` - `stopSecondaryCameraCapture` - [`setHeadphoneEQParameters:highGain:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) - `setRemoteVideo` - [`AgoraVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/ios/class-videosubscriptionoptions) - [`muteLocalAudioStreamEx:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) - [`muteLocalVideoStreamEx:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) - [`muteAllRemoteAudioStreamsEx:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) - [`muteAllRemoteVideoStreamsEx:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) - [`startRtmpStreamWithoutTranscodingEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex) - [`startRtmpStreamWithTranscodingEx:transcoding:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex) - [`updateRtmpTranscodingEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) - [`stopRtmpStreamEx:connection:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - [`pauseAllChannelMediaRelayEx:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex) - [`resumeAllChannelMediaRelayEx:`](/zh-CN/api-reference/rtc/ios/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) - `stopChannelMediaRelayEx` - [`AgoraCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/ios/class-cameracapturerconfiguration) 中增加 `followEncodeDimensionRatio` - [`AgoraRtcLocalVideoStats`](/zh-CN/api-reference/rtc/ios/class-localvideostats) 中增加 `hwEncoderAccelerating` - [`leaveChannelEx:options:leaveChannelBlock:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengineex_leavechannelex2) - [`AgoraVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/ios/class-videoencoderconfiguration) 中增加 `advancedVideoOptions` 成员 - [`AgoraLocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/ios/class-localaccesspointconfiguration) 中增加 `advancedConfig` 成员 - [`rtcEngine:didClientRoleChanged:newRole:newRoleOptions:`](/zh-CN/api-reference/rtc/ios/channel#callback_irtcengineeventhandler_onclientrolechanged) 中增加 `newRoleOptions` - [`adjustUserPlaybackSignalVolumeEx:volume:connection:`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#api_irtcengineex_adjustuserplaybacksignalvolumeex) - [`enableAudioVolumeIndicationEx:smooth:reportVad:connection:`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#api_irtcengineex_enableaudiovolumeindicationex) - [`AgoraMusicContentCenter`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusiccontentcenter) 接口类及其中方法 - [`AgoraMusicPlayerProtocol`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusicplayer) 协议及其中方法 - [`AgoraMusicContentCenterEventDelegate`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imusiccontentcentereventhandler) 接口类及其中回调 - [`AgoraMusic`](/zh-CN/api-reference/rtc/ios/class-music) 类 - [`AgoraMusicChartInfo`](/zh-CN/api-reference/rtc/ios/class-musicchartinfo) 类 - [`AgoraMusicContentCenterConfig`](/zh-CN/api-reference/rtc/ios/class-musiccontentcenterconfiguration) 类 - [`AgoraClimaxSegment`](/zh-CN/api-reference/rtc/ios/class-climaxsegment) 类 - [`AgoraMusicCollection`](/zh-CN/api-reference/rtc/ios/class-musiccollection) 类 - [`AgoraMusicContentCenterPreloadStatus`](/zh-CN/api-reference/rtc/ios/enum-preloadstate) - `AgoraMusicContentCenterStatusCode` #### 废弃 [#废弃-7] - `didApiCallExecute`，改用具体方法触发的回调。 #### 删除 [#删除-8] - 删除了 [`AgoraLiveTranscoding`](/zh-CN/api-reference/rtc/ios/class-livetranscoding) 类中的废弃成员参数 `backgroundImage` 和 `watermark` - `didReceiveChannelMediaRelayEvent` 中删除 `AgoraChannelMediaRelayEventUpdateDestinationChannelRefused`(8) ## v4.0.1 [#v401-1] 该版本于 2022 年 9 月 29 日发布。 ### 升级必看 [#升级必看-24] 如果你已经使用了以下类或方法，请在升级到该版本后重新调用方法并更新参数设置。 1. 为提高代码易用性，该版本将以下类中 `Optional` 类型的参数变更为 `Bool`、`Int` 等基本数据类型： - `AgoraDirectCdnStreamingMediaOptions` 中 `publishCameraTrack`、`publishMicrophoneTrack`、`publishCustomAudioTrack`、`publishCustomVideoTrack`、`publishMediaPlayerAudioTrack` 的参数类型由 `Optional` 变为 `Bool` 型。 - [`AgoraMediaSource`](/zh-CN/api-reference/rtc/ios/class-mediasource) 中的 `isAgoraSource` 和 `isLiveSource` 由 `Optional` 型变为 `Bool` 型。 - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中的所有参数类型由 `Optional` 变为 `Bool` 型或 `Int` 型。 2. [`destroyCustomVideoTrack:`](/zh-CN/api-reference/rtc/ios/video/video-custom-capturenrendering#api_irtcengine_destroycustomvideotrack) 方法中的 `position` 参数变更为 `trackid`。 3. 删除了 `enableDualStreamMode:sourceType:streamConfig:` 和 `enableDualStreamModeEx:sourceType:streamConfig:connection:` 中的 `sourceType` 参数以及 [`enableDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_enabledualstreammode3) 方法，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。 ### 新增特性 [#新增特性-29] #### 耳返 [#耳返-1] 该版本新增 [`getEarMonitoringAudioParams`](/zh-CN/api-reference/rtc/ios/audio/audio-raw#getearmonitoringaudioparams) 回调，用于设置耳返音频数据格式，你可以使用自己的音效处理模块对耳返音频数据进行前处理，实现自定义音效。调用 [`setAudioFrameDelegate:`](/zh-CN/api-reference/rtc/ios/audio/audio-raw#api_irtcengine_registeraudioframeobserver) 注册音频观测器后，在 [`getEarMonitoringAudioParams`](/zh-CN/api-reference/rtc/ios/audio/audio-raw#getearmonitoringaudioparams) 回调的返回值中设置耳返音频数据格式，SDK 会根据该回调的返回值计算采样间隔，并根据该采样间隔触发 [`onEarMonitoringAudioFrame:`](/zh-CN/api-reference/rtc/ios/audio/audio-raw#onearmonitoringaudioframe) 回调。 #### 本地网络连接类型 [#本地网络连接类型-1] 为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 [`getNetworkType`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_getnetworktype) 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 `networkTypeChangedToType` 回调，报告当前的网络连接类型。 #### 音强选流 [#音强选流-1] 该版本新增音强选流功能。该功能开启后，声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请联系技术支持。 同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗，详见[音强选流](/zh-CN/realtime-media/rtc/build/audio/audio-stream-filter)。 :::info[信息] 如需开启该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: #### 双流模式 [#双流模式-1] 该版本对双流模式做了优化，在加入频道前后均可调用 `enableDualStreamMode` 和 `enableDualStreamModeEx。` 扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式（即：默认不主动发送小流），可通过以下步骤开启发送小流： 1. 接收端主播调用 `setRemoteVideoStreamType` 或 [`setRemoteDefaultVideoStreamType:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 发起接收小流申请。 2. 发送端收到申请后自动切换为发送小流模式。 如果你想修改上述发送端的默认行为，可以调用 [`setDualStreamMode:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setdualstreammode) 或 [`setDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setdualstreammode2) 方法，将 `mode` 参数设置为 `AgoraDisableSimulcastStream` （始终不发送小流）或 `AgoraEnableSimulcastStream` （始终发送小流）。 #### 空间音频 [#空间音频-2] 该版本新增了如下适用于空间音频场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。 - 隔声区域：你可以通过调用 [`setZones:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用 [`setPlayerAttenuation:playerId:forceSet:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 和 [`setRemoteAudioAttenuation:userId:forceSet:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) 方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖 [`setZones:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 中的声音衰减系数。 - 多普勒音效：你可以通过设置 `SpatialAudioParams` 中的 `enable_doppler` 参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下（比如赛车游戏场景），接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用 [`setHeadphoneEQPreset:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 方法使用预设的耳机均衡效果，以改善耳机的听感。 ### 改进 [#改进-33] #### 视频信息发生改变回调 [#视频信息发生改变回调-1] 该版本优化了 `videoSizeChangedOfUid` 的触发逻辑，当单独调用 [`startPreview`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview) 时，也可触发该回调并上报本地视频大小发生改变。 #### 屏幕共享 [#屏幕共享-1] 为提升各平台屏幕共享的一致性，自该版本起删除了 `AgoraLocalVideoStreamErrorExtensionCaptureStarted`、`AgoraLocalVideoStreamErrorExtensionCaptureStoped`、`AgoraLocalVideoStreamErrorExtensionCaptureDisconnected` 枚举，改用 [`rtcEngine:localVideoStateChangedOfState:reason:sourceType:`](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中 `sourceType` 为 `AgoraVideoSourceTypeScreen` 时的 `state` 参数表示屏幕共享的状态。 ### 问题修复 [#问题修复-40] 该版本修复了以下问题： - 在频道内调用 [`setVideoEncoderConfigurationEx:connection:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengineex_setvideoencoderconfigurationex) 将视频的分辨率调高时，偶现失效。 - 使用媒体播放器播放视频，先调用 [`play`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 再调用 [`pause`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/ios/play/rte-player#api_player_seek) 指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用 [`resume`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_resume) 恢复播放后，偶现视频画面出现快进。 ### API 变更 [#api-变更-15] #### 新增 [#新增-15] - [`getEarMonitoringAudioParams`](/zh-CN/api-reference/rtc/ios/audio/audio-raw#getearmonitoringaudioparams) - [`getNetworkType`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_getnetworktype) - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中新增 `isAudioFilterable` - [`setDualStreamMode:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setdualstreammode) - [`setDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setdualstreammode2) - [`setDualStreamModeEx:streamConfig:connection:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengineex_setdualstreammodeex) - [`AgoraSimulcastStreamMode`](/zh-CN/api-reference/rtc/ios/enum-simulcaststreammode) - [`setZones:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) - [`setPlayerAttenuation:playerId:forceSet:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) - [`setRemoteAudioAttenuation:userId:forceSet:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) - `muteRemoteAudioStream:mute:` - `SpatialAudioParams` - [`setHeadphoneEQPreset:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) - [`AgoraHeadphoneEQPreset`](/zh-CN/api-reference/rtc/ios/enum-headphoneequalizerpreset) #### 修改 [#修改-6] - `enableDualStreamMode:sourceType:streamConfig:` - `enableDualStreamModeEx:sourceType:streamConfig:connection:` #### 废弃 [#废弃-8] - `startEchoTestWithInterval:interval:successBlock:` #### 删除 [#删除-9] - [`enableDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_enabledualstreammode3) - `AgoraLocalVideoStreamErrorExtensionCaptureStarted` - `AgoraLocalVideoStreamErrorExtensionCaptureStoped` - `AgoraLocalVideoStreamErrorExtensionCaptureDisconnected` ## v4.0.0 [#v400-1] 该版本于 2022 年 8 月 3 日发布。 ### 升级必看 [#升级必看-25] v4.0.0 SDK 对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见[迁移指南](/zh-CN/realtime-media/rtc/reference/migration-guide)。 - 多频道 - 媒体流发布控制 - 自定义视频采集与渲染（Media IO 方式） - 警告码 ### 新增特性 [#新增特性-30] #### 多路媒体流 [#多路媒体流-1] 该版本通过设置 [`AgoraRtcEngineKitEx`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex) 和 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 实现一个 [`AgoraRtcEngineKit`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengine) 实例同时采集多组音视频流并发布到远端： 调用 `joinChannelByToken` 加入首个频道后，多次调用 `joinChannelExByToken` 加入多个频道，通过不同的用户 ID (`localUid`) 和 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 设置发布指定的流到不同的频道。 支持通过设置 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中的 `publishSecondaryCameraTrack` 和 `publishSecondaryScreenTrack` 同时发布多路摄像头采集或者屏幕共享的视频流。 同时，该版本支持通过 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/ios/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流： 1. 创建自采集视频轨道：调用 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/ios/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法创建一个自定义视频轨道，并获得视频轨道 ID。 2. 设置频道中待发布的自采集视频轨道：在每个频道的 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中，将 `customVideoTrackId` 参数设置为你想要发布的视频轨道 ID，并将 `publishCustomVideoTrack` 设置为 `YES`。 3. 推送外部视频源：调用 `pushExternalVideoFrame`，并将 `videoTrackId` 指定为步骤 2 中指定的视频轨道 ID，即可实现在多个频道中发布对应的自定义视频源。 结合多频道能力，你还可以体验如下功能： - 将多组音视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路音频流混音后通过一个用户 ID (`uid`) 发布到远端。 - 将多组视频频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路视频流合图后通过一个用户 ID (`uid`) 发布到远端。 #### 全高清和超高清分辨率 [#全高清和超高清分辨率-1] 为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持全高清 (FHD) 和超高清 (UHD) 视频分辨率。你可以在调用 [`setVideoEncoderConfiguration:`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法时，将 `dimensions` 参数设置为 1920 × 1080 或更高的分辨率。如果你的设备不支持高分辨率，SDK 支持自动回退到适合的分辨率。 :::info[信息] - 超高清分辨率（4K，60 fps）目前为 Beta 功能，且对设备性能和网络带宽有一定要求，如需体验该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 - 高分辨率通常需要更高的性能消耗，为避免设备性能不足导致体验下降，声网建议你在性能较好的设备上开启全高清和超高清视频分辨率。 - 高分辨率可能会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 内置媒体播放器 [#内置媒体播放器-1] 为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 [`createMediaPlayerWithDelegate:`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer) 创建媒体播放器后，你可以通过 [`AgoraRtcMediaPlayerProtocol`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_imediaplayer) 类的一系列方法体验内置媒体播放器的各类功能： - 自动播放本地、在线、自定义的媒体资源。 - 预先加载待播放的媒体资源。 - 根据网络情况切换媒体资源的播放线路。 - 将媒体播放器的音视频流推送到任意频道、分享给远端用户。 - 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。 #### 新版 AI 降噪 [#新版-ai-降噪-1] 自该版本起，SDK 支持新版 AI 降噪（相对于 v3.7.0 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。 :::info[信息] 如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。 ::: #### 超高音质 [#超高音质-1] 为还原音频的细节、提升音频的清晰度，该版本在 [`AgoraVoiceBeautifierPreset`](/zh-CN/api-reference/rtc/ios/enum-voicebeautifierpreset) 中新增 `AgoraVoiceBeautifierUltraHighQuality`。在语聊、歌唱等以人声为主的场景中，你可以调用 [`setVoiceBeautifierPreset:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) 并使用该枚举体验超高音质。 #### 空间音频 [#空间音频-3] :::info[信息] 空间音频功能当前处于实验阶段，请联系 sales@shengwang.cn 开通空间音频功能，如果需要技术支持，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: 该版本提供本地直角坐标系计算方案实现空间音频： - 该方案使用 [`AgoraLocalSpatialAudioKit`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_ilocalspatialaudioengine) 类实现空间音频，通过 SDK 计算远端用户的空间坐标。你需要分别调用 [`updateSelfPosition:axisForward:axisRight:axisUp:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`updateRemotePosition:positionInfo:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音频。 ![](https://web-cdn.agora.io/docs-files/1646815686507) - 该方案通过 SDK 计算媒体播放器的空间坐标。你需要在 [`AgoraLocalSpatialAudioKit`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_ilocalspatialaudioengine) 类中分别调用 [`updateSelfPosition:axisForward:axisRight:axisUp:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`updatePlayerPositionInfo:positionInfo:`](/zh-CN/api-reference/rtc/ios/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateplayerpositioninfo) 更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音频。 ![](https://web-cdn.agora.io/docs-files/1646815708012) #### 实时合唱 [#实时合唱-1] 该版本为实时合唱赋予了如下能力： - 支持两人及两人以上合唱。 - 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。 - 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。 该版本在 [`AgoraAudioScenario`](/zh-CN/api-reference/rtc/ios/enum-audioscenariotype) 中新增 `AgoraAudioScenarioChorus` 枚举设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。 #### 云市场插件 [#云市场插件-1] 为在声网 SDK 的基础上增强实时音视频互动性，该版本支持[声网云市场](https://www.agora.io/cn/marketplace)插件的一站式解决方案： - 方便集成：只需执行简单统一的 API 即可实现模块化功能的集成，将实时互动模块集成效率提高约 95%。 - 可扩展性设计：模块化和可扩展的 SDK 设计风格赋予了声网 SDK 良好的可扩展性，更有利于开发者基于声网云市场插件生态快速搭建好用的实时互动应用。 - 打造生态系统：可容纳众多开发者的实时音视频 App 社区，提供多种扩展组合。添加并开启云市场插件后，开发者可以实现更为丰富的实时音视频互动功能。 - 助力服务商：支持服务商将技术产品以插件的形式与声网 SDK 做技术上的融合，在声网云市场中展示并售卖，与声网一起共建开发者的实时互动生态系统。如何开发和发布插件详见[云市场-开发插件](/zh-CN/realtime-media/marketplace/build/create-extensions/publish)。 #### 增强的频道管理 [#增强的频道管理-1] 为满足各类业务场景对频道管理的需求，该版本在 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中新增了如下功能： - 设置或切换多种音视频源的发布 - 设置或切换频道场景、用户角色 - 设置或切换订阅视频的大小流类型 - 控制音频发布时延 在调用 `joinChannelByToken` 或 `joinChannelExByToken` 时设置 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions)，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 [`updateChannelWithMediaOptions:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengine_updatechannelmediaoptions) 随时更新 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/ios/class-channelmediaoptions) 中的设置，例如，切换发布的音视频源。 #### 屏幕共享 [#屏幕共享-2] 该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享： - 在加入频道前调用 [`startScreenCapture:`](/zh-CN/api-reference/rtc/ios/video/screencapture#api_irtcengine_startscreencapture)，然后调用 [`joinChannelByToken:channelId:uid:mediaOptions:joinSuccess:`](/zh-CN/api-reference/rtc/ios/channel#api_irtcengine_joinchannel2) 加入频道并设置 `publishScreenCaptureVideo` 为 `YES`，即可开始屏幕共享。 - 在加入频道后调用 [`startScreenCapture:`](/zh-CN/api-reference/rtc/ios/video/screencapture#api_irtcengine_startscreencapture)，然后调用 `updateChannelMediaOptions` 设置 `publishScreenCaptureVideo` 为 `YES`，即可开始屏幕共享。 #### 设置音视频流订阅黑/白名单 [#设置音视频流订阅黑白名单-1] 该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通 [`AgoraRtcEngineKitEx`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex) 类下的同名方法来实现该功能。 - `setSubscribeAudioBlacklist`：设置音频订阅黑名单。 - `setSubscribeAudioWhitelist`：设置音频订阅白名单。 - `setSubscribeVideoBlacklist`：设置视频订阅黑名单。 - `setSubscribeVideoWhitelist`：设置视频订阅白名单。 如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。 #### 设置音频场景 [#设置音频场景-1] 为方便用户灵活修改音频场景，该版本新增 [`setAudioScenario:`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#api_irtcengine_setaudioscenario) 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (`AgoraAudioScenarioDefault`) 切换为高音质场景 (`AgoraAudioScenarioGameStreaming`)，你可以调用该方法。 #### 设置本地代理 [#设置本地代理-1] 该本版新增 [`setLocalAccessPoint:`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_setlocalaccesspoint) 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。 #### 垫片推流 [#垫片推流-1] 该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 [`enableVideoImageSource:options:`](/zh-CN/api-reference/rtc/ios/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 来开启该功能，并通过 `options` 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。 ### 改进 [#改进-34] #### 快速切换频道 [#快速切换频道-1] 该版本通过 `leaveChannel` 和 `joinChannelByToken` 切换频道即可实现和 v3.7.0 中 `switchChannelByToken` 一样的切换速度，无需额外调用 `switchChannelByToken` 方法。 #### 推送外部视频帧 [#推送外部视频帧-1] 该版本新增支持推送 I422 格式的外部视频帧，你可以通过 `pushExternalVideoFrame` 方法将 I422 格式的外部视频帧推送至 SDK。 #### 本地人声音调 [#本地人声音调-1] 该版本在 [`rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 的 [`AgoraRtcAudioVolumeInfo`](/zh-CN/api-reference/rtc/ios/class-audiovolumeinfo) 中新增 `voicePitch` 参数。你可以通过 `voicePitch` 获取本地用户的人声音调，从而实现唱歌评分等业务功能。 #### 设备权限管理 [#设备权限管理-1] 该版本新增 [`rtcEngine:permissionError:`](/zh-CN/api-reference/rtc/ios/network#callback_irtcengineeventhandler_onpermissionerror) 方法，当获取音频采集设备或摄像头权限开启失败时自动上报，用户可根据该回调的提示开启相应的设备权限。 #### 本地视频预览 [#本地视频预览-1] 该版本优化了 [`startPreview`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview) 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 [`startPreview`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_startpreview) 方法来开启视频预览，无调用时序要求。 #### 订阅视频流 [#订阅视频流-1] 你可以通过 [`setRemoteDefaultVideoStreamType:`](/zh-CN/api-reference/rtc/ios/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="macos" /> ## v4.7.0 [#v470-2] 该版本于 2026 年 9 月 22 日发布。 ### 改进 [#改进-35] #### 音视频链路性能优化 [#音视频链路性能优化-2] 该版本针对音视频链路与线程调度机制做了专项优化，显著降低各音视频场景 CPU 消耗，同步提升长时间运行稳定性。 #### 视频首帧体验优化 [#视频首帧体验优化-2] 该版本优化了视频帧传输调度机制，提升了频道内首个用户订阅流的出图速度。 #### 1v1 连麦延时体验优化 [#1v1-连麦延时体验优化-2] 该版本优化了视频1v1等实时互动场景下的音视频策略，在保障画质的前提下改善端到端延迟，并提升突发抖动等弱网场景下的播放流畅性。 #### 音频场景码率优化 [#音频场景码率优化-2] 该版本优化了音频场景下的码率开销，保障音质的前提下提升了音频流传输效率。 #### Native 与 Web 互通弱网体验优化 [#native-与-web-互通弱网体验优化-2] 该版本优化了视频 1v1 弱网场景下 Native 与 Web 互通的音视频体验。 ### 问题修复 [#问题修复-41] 该版本修复了以下问题： - 修复了 macOS 26 设备连接 HDMI 外接屏后，调用屏幕共享相关接口枚举屏幕列表时，无法枚举出扩展屏幕的问题。 - 修复了 AI Client 场景下接收较长 TTS 音频时，偶现远端音频数据混乱的问题。 - 修复了预加载音效场景下，调用 `stopEffect` 停止播放后再次调用 `playEffect` 时，上一段音效仍有残留的问题。 - 修复了镜像渲染、自渲染和屏幕共享源枚举等场景下偶现 App 崩溃的问题，提升了 SDK 稳定性。 ## v4.6.2 [#v462-2] 该版本于 2026 年 1 月 16 日发布。 :::warning[注意] - 通过 CocoaPods 集成并升级至 v4.6.0 及以上版本时，除更新版本号外，还需将 Pod 名称从 `AgoraRtcEngine_iOS` 修改为 `ShengwangRtcEngine_iOS`。 - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `aosl.xcframework` 库。 - 4.6.2 RTC SDK `aosl.xcframework` 库版本为 1.3.5。 ::: ### 升级必看 [#升级必看-26] #### 支持自定义编码帧率 [#支持自定义编码帧率-1] 为支持更灵活的视频编码帧率设置，该版本将 `AgoraVideoEncoderConfiguration` 中 `frameRate` 参数的数据类型由枚举类型改成了 `Int`。在实际集成时，你可以参考原有 [`AgoraVideoFrameRate`](/zh-CN/api-reference/rtc/ios/enum-framerate) 枚举中的取值进行设置。 #### 其他 [#其他-9] - 为保证整体解码兼容性，相关解码器插件已内置在 SDK 中。 ### 新增特性 [#新增特性-31] #### Media Player 支持获取音频缓冲延迟 [#media-player-支持获取音频缓冲延迟-2] 为解决 K 歌场景中可能会出现的主唱与伴唱伴奏不同步的问题，该版本在 Media Player 模块中新增 `getAudioBufferDelay` 方法，用于获取播放媒体文件时毫秒级的音频缓冲延迟。 ### 改进 [#改进-36] #### playEffect 支持无缝切换 [#playeffect-支持无缝切换-2] 该版本新增支持音效文件的无缝切换。对于同一个音效文件，如果先调用 `preloadEffect` 再调用 `playEffect`，在播放完成或通过 `stopEffect` 停止播放后，SDK 不会关闭该音效文件。当再次调用 `playEffect` 时，SDK 会直接复用已加载的文件进行播放，从而实现循环播放和无缝切换。该能力同样适用于多频道场景。 #### networkQuality 准确性提升 [#networkquality-准确性提升-1] 该版本提升了 `networkQuality` 回调中网络质量评估的准确性，使回调数据更贴近用户的主观体验。 #### onPlaybackAudioFrame 支持 24k 采样率的音频帧 (All Native) [#onplaybackaudioframe-支持-24k-采样率的音频帧-all-native] 该版本在 `onPlaybackAudioFrame` 中新增支持采样率为 **24000 Hz** 的音频数据。在调用 [`setPlaybackAudioFrameParameters`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#api_irtcengine_setplaybackaudioframeparameters) 设置播放音频数据格式时，可以将 `sampleRate` 设为 `24000`。 #### 支持共享窗口前置 [#支持共享窗口前置] 该版本修复了 macOS 14 及以上设备上设置共享窗口前置不生效的问题。你需要在项目的 `plist` 中添加 `NSAccessibilityUsageDescription` 权限。添加后，系统会提示用户授权辅助功能，从而支持共享窗口前置。 #### onEncodedVideoFrameReceived 回调支持获取频道 ID (All Native) [#onencodedvideoframereceived-回调支持获取频道-id-all-native] 该版本在 `onEncodedVideoFrameReceived` 回调中新增 `channelId` 参数，方便你在获取编码后视频数据时识别其所属频道。 #### 其他 [#其他-10] - 新增错误码 `AgoraErrorCodePcmSendFormat (200)` 和 `AgoraErrorCodePcmSendBufferOverflow (201)`，用于报告 PCM 数据发送相关错误。 ## v4.6.0 [#v460-2] 该版本于 2025 年 8 月 18 日发布。 :::warning[注意] - 通过 CocoaPods 集成并升级至 v4.6.0 及以上版本时，除更新版本号外，还需将 Pod 名称从 `AgoraRtcEngine_iOS` 修改为 `ShengwangRtcEngine_iOS`。 - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `aosl.xcframework` 库。 - 4.6.0 RTC SDK `aosl.xcframework` 库版本为 1.3.0。你可以在 `Info.plist` 中查看库的版本信息。 ::: ### 升级必看 [#升级必看-27] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的废弃及删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 各版本废弃及删除的 API 信息。详见 [API 下架说明](/zh-CN/api-reference/rtc/macos/rtc-api-sunset)。 #### 直推 CDN 相关接口废弃 [#直推-cdn-相关接口废弃-2] 该版本废弃直推 CDN 功能的相关接口，并会在后续版本中删除，请改用[服务端旁路推流](/zh-CN/realtime-media/media-push)。 - `setDirectCdnStreamingAudioConfiguration:` - `setDirectCdnStreamingVideoConfiguration:` - `startDirectCdnStreaming:publishUrl:mediaOptions:` - `stopDirectCdnStreaming` - `AgoraDirectCdnStreamingMediaOptions` - `AgoraDirectCdnStreamingStats` - `AgoraDirectCdnStreamingState` - `AgoraDirectCdnStreamingReason` #### 虚拟节拍器接口废弃 [#虚拟节拍器接口废弃-2] 该版本废弃虚拟节拍器功能的相关接口，并会在后续版本中删除。 - [`startRhythmPlayer:sound2:config:`](/zh-CN/api-reference/rtc/macos/play/rhythmplayer#api_irtcengine_startrhythmplayer) - [`configRhythmPlayer:`](/zh-CN/api-reference/rtc/macos/play/rhythmplayer#api_irtcengine_configrhythmplayer) - [`rtcEngine:didRhythmPlayerStateChanged:reason:`](/zh-CN/api-reference/rtc/macos/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) #### 水印接口废弃 [#水印接口废弃-2] 该版本废弃水印功能的相关接口，推荐使用该版本新增的水印接口。 - [`addVideoWatermark:options:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2) - [`addVideoWatermarkEx:options:connection:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex) #### 冗余接口删除 [#冗余接口删除-2] 该版本删除了下列冗余接口及参数： - `setLocalPublishFallbackOption` - `didLocalPublishFallbackToAudioOnly` - `downlinkNetworkInfoUpdate` - `wlAccStats` - `wlAccMessage` - `enableWirelessAccelerate` - `AgoraWlAccReason` - `AgoraWlAccAction` - `AgoraWlAccStats` - `AgoraRtcRemoteVideoStats 中删除 receivedFrameRate` #### 美妆功能实现变更 [#美妆功能实现变更-2] 受美颜重构的影响，自 v4.6.0 起，不再支持调用 [`setExtensionPropertyWithVendor:extension:key:value:`](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_setextensionproperty) 启用美妆功能，改用 `STYLE_MAKEUP` 节点实现。 #### 新增域名白名单 [#新增域名白名单-2] 如果你由之前的版本升级到 v4.6.0 且使用了域名白名单功能（`AgoraRtcEngineConfig` 下的 `domainLimit` 为 `YES`），请在白名单中添加以下域名，以确保互通顺畅： - `*.rtnsvc.com` - `*.realtimemesh.com` ### 新增特性 [#新增特性-32] #### 多路分辨率视频流 [#多路分辨率视频流-2] 该版本新增多路分辨率视频流（Adaptive Bitrate Video Streaming，简称 ABR）功能，支持对同一视频源设置同时发送多路不同分辨率的视频流，并支持多频道场景。接收端通过自动/手动订阅目标分辨率的视频流。 启用 ABR 后，你可以配置不同分辨率的视频流，（最多四层分辨率，一个最高分辨率的主流和三层其他较低分辨率的视频流），并设置视频流的分辨率、码率、是否启用分层推流回退等选项来灵活控制流的发布。启用分层推流回退后，SDK 会在弱网环境下自动回退到低分辨率的视频流，确保流畅的观看体验。订阅端可根据实际需求选择想要接收的视频流。适用于会议场景、大班课、互动直播等多终端、多网络环境，可显著提升弱网下的观看体验。 具体实现方法以及和视频双流的对比可以参考进阶功能[发布多路视频流 (ABR)](/zh-CN/realtime-media/rtc/build/video/simulcast)。 #### 多路径网络传输 [#多路径网络传输-2] 该版本新增多路径传输功能，适用于终端支持多网卡传输(比如 5G， Wi-Fi，LAN)的设备，可以有效降低甚至消除弱网带来的体验回退，适用于弱网环境、对传输稳定性要求高的实时音视频通信场景，如车载、IoT、火车、高速公路等复杂网络环境。通过在 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中设置 `enableMultipath` 为 `YES`，可开启多路径传输能力。支持两种传输模式（[`AgoraMultipathMode`](/zh-CN/api-reference/rtc/macos/enum-multipathmode)）： - 动态模式：（默认）根据网络状况动态选择最佳路径进行传输，适用于流量敏感、对体验要求比较高的场景，如会议、教育等。动态模式下，你可以通过 `preferMultipathType` 指定首选的网络传输路径（如优先 Wi-Fi 或移动网络）。 - 全冗余模式：数据会在所有可用网络路径上同时传输，适用于流量不敏感，对体验有极致要求的场景，如户外采播、平行操控等。该模式会产生额外费用，如需使用请[联系技术支持](https://ticket.shengwang.cn/)。 上下行还可分别通过 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的 `uplinkMultipathMode`、`downlinkMultipathMode` 配置。启用后，SDK 会通过回调 [`rtcEngine:multiPathStats:`](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onmultipathstats) 实时上报各路径的传输统计信息，包括每一个传输路径的流量消耗，便于开发者监控和优化网络表现。 #### 视频质量评分 [#视频质量评分-2] 该版本在 [`AgoraRtcRemoteVideoStats`](/zh-CN/api-reference/rtc/macos/class-remotevideostats) 中新增 `mosValue` 成员，报告声网实时视频 MOS（平均主观意见分）评估系统对接收到的远端视频流的质量评分。评分共有 5 个档次，5 分表示视频画质优秀，画面清晰无噪点，1 分表示视频画质极差，画面严重模糊。你可以通过该参数实时观测远端视频流的主观画质表现，便于动态调整视频参数、优化用户体验，或用于质量监控和告警等场景。如需启用该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 支持添加多个水印 [#支持添加多个水印-2] 该版本废弃了 [`addVideoWatermark:options:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2) 和 [`addVideoWatermarkEx:options:connection:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex) 方法，新增 [`addVideoWatermarkWithConfig`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/watermark#api_irtcengine_addvideowatermark3) 和 [`addVideoWatermarkEx3`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex1) 方法，支持通过水印 ID 来给视频添加多个水印，并可对水印进行排序。如果你需要移除指定水印，可调用 [`removeVideoWatermark`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/watermark#api_irtcengine_removevideowatermark) 方法。 #### 异步销毁引擎 [#异步销毁引擎-2] 该版本新增 `destroy:` 方法，用于销毁 RTC 引擎，且支持通过参数配置以同步或异步方式销毁引擎。异步销毁引擎时，SDK 会触发 `engineReleasedBlock` 回调块。 #### 美颜功能拓展 [#美颜功能拓展-2] 新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。 #### Token 更新结果回调 [#token-更新结果回调-2] 该版本新增 [`rtcEngine:renewTokenResult:code:`](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调及 `RENEW_TOKEN_ERROR_CODE` 错误码。当调用 [`renewToken:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_renewtoken) 方法更新 Token 后，SDK 会通过 [`rtcEngine:renewTokenResult:code:`](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调通知 Token 更新的结果，并通过 `RENEW_TOKEN_ERROR_CODE` 返回详细的错误码，开发者可在回调中根据错误码及时处理 Token 更新失败的场景。 #### 其他 [#其他-11] - 新增 [`setPlaybackAudioFrameBeforeMixingParametersWithSampleRate`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#api_irtcengine_setplaybackaudioframebeforemixingparameters1) 方法用于设置 [`onPlaybackAudioFrameBeforeMixing:channelId:uid:`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#callback_iaudioframeobserver_onplaybackaudioframebeforemixing) 回调中返回的音频帧格式，包括采样率、声道数以及每次回调的数据采样点数。调用此方法后，SDK 会按照设定的参数返回混音前的原始音频数据，便于开发者进行自定义处理或分析。 - 新增 `preloadEffectEx` 方法，用于将指定音效文件预加载到指定频道，支持本地或在线音效文件，便于后续快速播放，适合多频道场景。 - 新增 [`playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:startPos:`](/zh-CN/api-reference/rtc/macos/play/audio-effect-file#api_irtcengineex_playeffectex) 方法，用于在指定频道播放音效文件，支持设置循环次数、音调、空间位置、音量、是否发布到频道及播放起始位置等参数，满足丰富的音效播放需求。 - 本地截图上传功能支持通过 [`AgoraContentInspectModule`](/zh-CN/api-reference/rtc/macos/class-contentinspectmodule) 中新增的 `position` 成员设置截图的视频观测位置，从而实现对原始视频数据或效果处理前后的视频流进行截图并上传。 - 为了提升用户使用绿幕或蓝幕开启虚拟背景功能时，人像分割的准确性和稳定性，该版本在 [`AgoraSegmentationProperty`](/zh-CN/api-reference/rtc/macos/class-segmentationproperty) 中新增 `screenColorType` 属性，支持指定背景幕布的颜色为绿色、蓝色或自动识别。 ### 改进 [#改进-37] #### 美颜重构 [#美颜重构-2] 该版本对美颜功能进行了彻底重构和升级，不仅拓展了美颜功能，提升了美颜效果和性能，还解决了美颜参数配置复杂、集成成本高、美颜资源依赖网络易失效等痛点。主要改进包括： - **API 大幅简化**：将过去版本中的基础美颜、美型、美妆、滤镜功能整合为 `AgoraVideoEffectNodeBeauty`、`AgoraVideoEffectNodeStyleMakeup`、`AgoraVideoEffectNodeFilter` 三个核心节点 (node)，通过 [`AgoraVideoEffectObject`](/zh-CN/api-reference/rtc/macos/class-ivideoeffectobject) 统一管理生命周期和参数设置，减少频繁 API 调用带来的性能负担。 - **预设模板开箱即用**：提供多套预设风格模板（如“自然美颜”、“学姐妆”、“冷白滤镜”），大幅简化集成流程，无需手动调试数十项参数。 - **美颜参数动态控制**：该版本新增实时获取美颜参数的能力，开发者可通过 key-value 方式动态读取或修改任意细粒度参数（如磨皮强度、口红类型）。同时支持：调用预设模板快速启用风格效果、保存主播自定义参数配置、随时重置参数至默认状态，极大提升了业务层状态同步的灵活性和开发效率。 - **美颜资源外置**：该版本通过美颜资源外置化设计，将所有美颜资源（特效、滤镜、妆容）均打包为本地 bundle 文件，彻底消除因网络下载失败导致美颜失效的风险。 #### 其他改进 [#其他改进-17] - 在与 Web 端互通时，新增对 g711 和 g722 音频编解码器的支持，进一步提升了跨平台音频播放的兼容性和清晰度。 - 优化了屏幕共享文档场景下的共享视频清晰度。 ### 问题修复 [#问题修复-42] 该版本修复了以下问题： - 调用 [`open:startPos:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-open#api_imediaplayer_open) 打开在线音效文件后，调用 [`playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:`](/zh-CN/api-reference/rtc/macos/play/audio-effect-file#api_irtcengine_playeffect3) 开始播放，当调用 [`seekToPosition:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定播放位置后，音效文件会从头开始播放。 - 在媒体音量模式下，主播在频道中发布麦克风采集的音频流，同时调用 [`playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:`](/zh-CN/api-reference/rtc/macos/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效文件、调用 [`startAudioMixing:loopback:cycle:startPos:`](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing2) 播放音乐文件，偶现回声。 - 调用 [`joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_joinchannelex) 加入频道，然后调用 [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 开始跨频道媒体流转发，下麦、退出频道后重新加入频道开始连麦，偶现 [`rtcEngine:channelMediaRelayStateDidChange:error:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) 回调报告 `state` 为 `AgoraChannelMediaRelayStateFailure`，[`code`](/zh-CN/api-reference/rtc/macos/play/rte-player#api_error_code) 为 `AgoraChannelMediaRelayErrorServerErrorResponse`。 ## v4.5.2 [#v452-2] 该版本于 2025 年 4 月 22 日发布。 :::warning[注意] - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `aosl.xcframework` 库。 - 4.5.2 RTC SDK `aosl.xcframework` 库版本为 1.2.13。你可以在 `Info.plist` 中查看库的版本信息。 ::: ### 改进 [#改进-38] #### URL 拉流播放 [#url-拉流播放-4] 该版本进一步拓展了 URL 拉流播放的功能，支持播放 CDN URL 和本地媒体资源文件，同时可以设置从指定位置开始播放、调节播放速度、设置播放音量、在播放过程中切换播放源等，详见 [观众端 URL 拉流](/zh-CN/realtime-media/rtc/build/optimize-and-operate/playing-url)。 ### 问题修复 [#问题修复-43] 该版本修复了以下问题： - 开启导唱功能播放多音轨歌曲时，调用 [`setAudioPitch:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setaudiopitch) 方法调整歌曲音调后出现杂音。 - 主播端调用 [`createCustomAudioTrack:config:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 创建自定义音频采集轨道并将 `trackType` 设为 `AUDIO_TRACK_DIRECT`，调用 [`pushExternalAudioFrameRawData:samples:sampleRate:channels:trackId:timestamp:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_pushaudioframe2) 将自采集音频推送到频道内，然后调用 [`playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:`](/zh-CN/api-reference/rtc/macos/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效，频道内的观众听主播的音频有杂音。 - 集成了 SDK 的 App 在音视频互动过程中偶现主线程阻塞导致的 UI 卡顿。 - 调用 [`openWithMediaSource:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 并通过 `source` 参数将 `isLiveSource` 设为 `YES` 并播放纯视频流，播放失败。 - 发送端传输多声道编码音频时，接收端偶现杂音。 - App 集成媒体播放器场景下，先后两次调用 open 打开不同媒体资源，第二次打开时，媒体播放器信息变化回调 [`AgoraRtcMediaPlayer:infoUpdated:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerinfoupdated) 返回第一次媒体资源的信息，不符合预期。 - 调用 [`enableAudioVolumeIndication:smooth:reportVad:`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 启用用户音量提示本地发流用户和远端用户音量相关信息，用户音量提示回调 [`rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 返回的本地用户音量为 0。 - App 调用 [`enableVideoImageSource:options:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 启用垫片推流功能，偶现发送端推流成功但是 [`rtcEngine:didVideoPublishStateChange:sourceType:oldState:newState:elapseSinceLastState:`](/zh-CN/api-reference/rtc/macos/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 返回当前的发布状态不是 PUB_STATE_PUBLISHED，不符合预期。 - 多频道场景下，App 在调用 [`joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_joinchannelex) 成功前调用 [`setupRemoteVideoEx:connection:`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengineex_setupremotevideoex) 初始化远端用户视图，偶现远端用户视图首帧图像显示延时大。 ## v4.5.1 [#v451-2] 该版本于 2025 年 3 月 5 日发布。 :::warning[注意] - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `aosl.xcframework` 库。 - 4.5.1 RTC SDK `aosl.xcframework` 库版本为 1.2.13。你可以在 `Info.plist` 中查看库的版本信息。 ::: ### 新增特性 [#新增特性-33] #### AI 对话场景 [#ai-对话场景-2] 该版本新增了专为与[声网对话式 AI 引擎](/zh-CN/ai)创建的智能体互动设计的 `AgoraAudioScenarioAiClient` 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。 ### 问题修复 [#问题修复-44] 该版本修复了以下问题： - 同时加入两个及以上的频道，连续调用 [`takeSnapshotEx:uid:filePath:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。 - 使用媒体播放器时，调用 [`pause`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seekToPosition:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 定位到指定播放位置、然后调用 [`play`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。 - 使用媒体播放器时，调用 [`switchSrc:syncPts:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换媒体资源后，调用 [`getPlaySrc`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-info#getplaysrc) 获取当前正在播放的媒体资源的路径没有变化。 - 在极速直播场景下，观众通过 `string` 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。 - 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。 ## v4.5.0 [#v450-2] 该版本于 2024 年 11 月 26 日发布。 ### 升级必看 [#升级必看-28] 该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 :::warning[注意] 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `aosl.xcframework` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `aosl.xcframework` 库。4.5.0 RTC SDK `aosl.xcframework` 库版本为 1.2.13。你可以在 `Info.plist` 中查看库的版本信息。 ::: #### 自动安装虚拟声卡 [#自动安装虚拟声卡] 自该版本起，SDK 支持自动安装虚拟声卡功能，当你第一次调用 [`enableLoopbackRecording:deviceName:`](/zh-CN/api-reference/rtc/macos/audio/audio-capture#api_irtcengine_enableloopbackrecording) 时，SDK 会自动安装内置的声网自研虚拟声卡 AgoraALD。安装成功后，音频路由会自动切换为虚拟声卡，同时使用虚拟声卡进行采集。 #### 强效视频降噪实现变更 [#强效视频降噪实现变更-2] 该版本调整了强效视频降噪的实现方式，在 [`AgoraVideoDenoiserLevel`](/zh-CN/api-reference/rtc/macos/enum-videodenoiserlevel) 中删除了 `AgoraVideoDenoiserLevelStrength`，改为调用 [`setVideoDenoiserOptions:options:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 启用视频降噪后，调用 [`setBeautyEffectOptions:options:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 [`setVideoDenoiserOptions:options:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)。 此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 [`setLowlightEnhanceOptions:options:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)。 #### 摄像头插拔状态变更 [#摄像头插拔状态变更] 在之前版本中，摄像头拔出并重新插入后不会自动恢复采集。该版本起，摄像头重新插入后将自动恢复采集。 #### 视频编码偏好变更 [#视频编码偏好变更-2] 为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好： - 在 [`AgoraCompressionPreference`](/zh-CN/api-reference/rtc/macos/enum-compressionpreference) 枚举类中新增 `AgoraCompressionAuto` (-1) 枚举，并替代原有的 `AgoraCompressionQuality` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `AgoraCompressionLowLatency` 或 `AgoraCompressionQuality`，以获得最佳的用户体验。 - 在 [`AgoraDegradationPreference`](/zh-CN/api-reference/rtc/macos/enum-degradationpreference) 枚举类中新增 `AgoraDegradationMaintainAuto` (-1) 枚举，并替代原有的 `AgoraDegradationMaintainQuality` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `AgoraDegradationMaintainFramerate`、`AgoraDegradationBalanced` 或 `AgoraDegradationMaintainResolution`，以获得最优的综合质量体验 (QoE)。 ### 新增特性 [#新增特性-34] #### 高级美颜 [#高级美颜-2] 该版本新增以下两种高级美颜功能： - 美型：调用 [`setFaceShapeBeautyOptions:options:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 [`setFaceShapeAreaOptions:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapeareaoptions) 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。 - 美妆：调用 [`setExtensionPropertyWithVendor:extension:key:value:`](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_setextensionproperty) 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。 有关美型和美妆的实现步骤，详见[实现高级美颜](/zh-CN/realtime-media/rtc/build/video/advanced-beauty)。 :::info[信息] 目前，高级美颜功能为**限时免费**，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 秀场直播场景 [#秀场直播场景-2] 该版本在 [`AgoraApplicationScenarioType`](/zh-CN/api-reference/rtc/macos/enum-videoapplicationscenariotype) 类下新增枚举 `AgoraApplicationLiveShowScenario`(3)（秀场直播），你可以调用 [`setVideoScenario:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为[秀场直播](/zh-CN/solutions/showroom)。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，例如，默认开启音视频帧加速渲染来提升首帧出图体验，无需再额外调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_enableinstantmediarendering)，此外，也增强了在弱网环境和低端设备上的画质和流畅度表现。 #### 限制视频渲染帧率 [#限制视频渲染帧率-2] 该版本新增 [`setLocalRenderTargetFps`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_setlocalrendertargetfps) 和 [`setRemoteRenderTargetFps`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_setremoterendertargetfps) 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。 在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。 #### URL 拉流播放 [#url-拉流播放-5] URL 拉流播放功能主要用于直播场景，观众端可以直接通过 [`openWithUrl:startTime:cb:`](/zh-CN/api-reference/rtc/macos/play/rte-player#api_player_openwithurl) 打开特定的 URL 来播放实时媒体流，无需显示调用加入频道、订阅等 API，极大简化了观众端观看直播流的 API 调用。 在播放的过程中，观众端可以通过 [`setAbrSubscriptionLayer:error:`](/zh-CN/api-reference/rtc/macos/play/rte-player#api_playerconfig_setabrsubscriptionlayer) 设置订阅视频大小流，并可以在大小流之间实现平滑切换。如果对视频体验有更高要求，可以联系[联系技术支持](https://ticket.shengwang.cn/)开通 ABR（Adaptive Bitrate，自适应码率）功能。启用该功能后，可以自定义不同层级的视频流分辨率，观众可以实现不同分辨率视频流的平滑切换。 当网络情况不稳定时，观众端可以调用 [`setAbrFallbackLayer:error:`](/zh-CN/api-reference/rtc/macos/play/rte-player#api_playerconfig_setabrfallbacklayer) 来设置订阅的视频流的回退选项。SDK 会以你指定的最低质量层级对应的视频流分辨率为下限，在此范围内根据网络状况动态调整分辨率。实现细节详见[观众端 URL 拉流](/zh-CN/realtime-media/rtc/build/optimize-and-operate/playing-url)。 #### 滤镜效果 [#滤镜效果-2] 该版本新增 [`setFilterEffectOptions:options:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setfiltereffectoptions) 方法，你可以在 **config** 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 `built_in_whiten_filter.cube` 文件，用于快速实现美白滤镜效果。 #### 本地音频合流 [#本地音频合流-2] 该版本新增本地音频合流功能，你可以调用 [`startLocalAudioMixer`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/audiomixer#api_irtcengine_startlocalaudiomixer) 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 [`stopLocalAudioMixer`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/audiomixer#api_irtcengine_stoplocalaudiomixer) 方法停止本地音频合流；在合流过程中，可以调用 [`updateLocalAudioMixerConfiguration`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/audiomixer#api_irtcengine_updatelocalaudiomixerconfiguration) 方法更新正在合流的音频流配置。 该功能的使用场景示例如下： - 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。 - 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。 - 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。 #### 色彩空间设置 [#色彩空间设置-2] 该版本在 [`AgoraOutputVideoFrame`](/zh-CN/api-reference/rtc/macos/class-videoframe) 和 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/macos/class-externalvideoframe) 中新增了 **colorSpace**，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。 ### 改进 [#改进-39] #### 虚拟背景算法优化 [#虚拟背景算法优化-4] 该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。 #### 录制本地预览视频 [#录制本地预览视频-2] 该版本在 [`AgoraRecorderStreamInfo`](/zh-CN/api-reference/rtc/macos/class-recorderstreaminfo) 中新增 **type** 成员。当调用 [`createMediaRecorder:`](/zh-CN/api-reference/rtc/macos/recording#api_irtcengine_createmediarecorder) 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 [`AgoraMediaRecorderConfiguration`](/zh-CN/api-reference/rtc/macos/class-mediarecorderconfiguration) 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 [`startRecording:`](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_startrecording) 即可开始录制本地预览的视频。 #### 指定视频观测位置截图 [#指定视频观测位置截图-2] 该版本新增 [`takeSnapshotWithConfig:config:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/snapshot#api_irtcengine_takesnapshot2) 和 [`takeSnapshotExWithConfig:uid:config:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex2) 方法，你可以在调用该方法时通过 **config** 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。 #### 自定义音频采集改进 [#自定义音频采集改进-2] 该版本在 [`AgoraAudioTrackConfig`](/zh-CN/api-reference/rtc/macos/class-audiotrackconfig) 中新增了 `enableAudioProcessing` 成员参数，用于控制是否对 `AUDIO_TRACK_DIRECT` 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 `NO`，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。 #### 其他改进 [#其他改进-18] - 优化了调用 [`queryDeviceScore`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_querydevicescore) 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。 - 调用 [`switchSrc:syncPts:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 [`AgoraRtcMediaPlayer:didOccurEvent:elapsedTime:message:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent) 回调报告 `AgoraMediaPlayerEventSwitchError` 事件，表示媒体资源切换时发生错误。 - 调用 [`setPlaybackSpeed:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，最低支持 0.3 倍速播放。 ### 问题修复 [#问题修复-45] 该版本修复了以下问题： - 调用 [`startAudioMixing:loopback:cycle:`](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_startaudiomixing) 后，立即调用 [`pauseAudioMixing`](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_pauseaudiomixing) 暂停播放音乐文件不生效。 ## v4.4.0 [#v440-2] 该版本于 2024 年 8 月 5 日发布。 ### 升级必看 [#升级必看-29] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 :::info[信息] 自 v4.4.0 起，RTC SDK 提供 API 下架说明，包含各版本废弃及删除的 API 信息。详见 [API 下架说明](/zh-CN/api-reference/rtc/macos/rtc-api-sunset)。 ::: 1. 为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的 [`AgoraExtensionContext`](/zh-CN/api-reference/rtc/macos/class-extensioncontext) 了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。 | 原有回调 | 现有回调 | | -------------------- | ------------------------------- | | `onEvent` | [`onEventWithContext:key:value:`](/zh-CN/api-reference/rtc/macos/extension#callback_irtcengineeventhandler_onextensioneventwithcontext) | | `onExtensionStarted` | [`onExtensionStartedWithContext:`](/zh-CN/api-reference/rtc/macos/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) | | `onExtensionStopped` | [`onExtensionStoppedWithContext:`](/zh-CN/api-reference/rtc/macos/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext) | | `onExtensionError` | [`onExtensionErrorWithContext:error:message:`](/zh-CN/api-reference/rtc/macos/extension#callback_irtcengineeventhandler_onextensionerrorwithcontext) | 2. 该版本将 `receiveMetadata` 回调改名为 [`didMetadataReceived:`](/zh-CN/api-reference/rtc/macos/metadata/metadata-observer#callback_imetadataobserver_onmetadatareceived)，并删除了回调中的 `data`、`timeStamp` 参数，你可以通过新增的 `metadata` 参数来获取 Metadata 的相关信息，包括 `timeStamp`（发送数据的时间戳）、`uid`（用户 ID）、`channelId`（源频道名称）等。 ### 新增特性 [#新增特性-35] #### Alpha 透明特效 [#alpha-透明特效-2] 该版本新增 Alpha 透明特效功能，支持在 SDK 采集和自定义采集视频的场景下，在发送端发布视频帧的 Alpha 通道、在接收端对 Alpha 通道进行渲染处理，实现透明礼物特效、接收端自定义主播背景等： - [`AgoraOutputVideoFrame`](/zh-CN/api-reference/rtc/macos/class-videoframe) 和 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/macos/class-externalvideoframe) 中新增 `alphaBuffer`：设置 Alpha 通道数据。 - [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/macos/class-externalvideoframe) 中新增 `fillAlphaBuffer`：对于 BGRA 或 RGBA 格式的视频数据，设置是否自动提取 Alpha 通道数据并填入到 `alphaBuffer` 中。 - [`AgoraOutputVideoFrame`](/zh-CN/api-reference/rtc/macos/class-videoframe) 和 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/macos/class-externalvideoframe) 中新增 `alphaStitchMode`：设置 `alphaBuffer` 和视频帧拼接的相对位置。 另外，[`AgoraAdvancedVideoOptions`](/zh-CN/api-reference/rtc/macos/class-advanceoptions) 中新增成员 `encodeAlpha`，用于设置是否将 Alpha 信息编码并发送到远端。SDK 默认不对 Alpha 信息进行编码发送；如果需要对 Alpha 信息编码发送至远端（例如开启了虚拟背景功能），请显式调用 [`setVideoEncoderConfiguration:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 设置视频编码属性，并将 `encodeAlpha` 设置为 `YES`。 :::info[信息] 如需了解在各场景下实现 Alpha 特效的最佳实践，详见[实现 Alpha 透明特效](/zh-CN/realtime-media/rtc/build/video/alpha-effect)。 ::: #### AI 调音器 [#ai-调音器-2] 该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 [`enableVoiceAITuner:type:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/audio-effect#api_irtcengine_enablevoiceaituner) 方法并传入 [`AgoraVoiceAITunerType`](/zh-CN/api-reference/rtc/macos/enum-voiceaitunertype) 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。 #### 1v1 视频通话场景 [#1v1-视频通话场景-2] 该版本在 [`AgoraApplicationScenarioType`](/zh-CN/api-reference/rtc/macos/enum-videoapplicationscenariotype) 类下新增枚举 `AgoraApplication1V1Scenario`（1v1 视频通话）。你可以调用 [`setVideoScenario:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。 ### 改进 [#改进-40] #### 人脸区域美颜 [#人脸区域美颜-2] 为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。 #### 其他改进 [#其他改进-19] 该版本还进行了如下改进： - 优化了传输策略，调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_enableinstantmediarendering) 不再对传输链路的安全性产生影响。 - [`rtcEngine:localVideoStateChangedOfState:reason:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增 `AgoraLocalVideoStreamReasonScreenCaptureDisplayDisconnected` 枚举，表示进行屏幕采集的显示器已断开连接。 - 优化了共享窗口的视频链路，降低了 CPU 占用率。 - 废弃了 [`AgoraClientRoleChangeFailedReason`](/zh-CN/api-reference/rtc/macos/enum-clientrolechangefailedreason) 中的冗余枚举值 `AgoraClientRoleChangeFailedRequestTimeout`、`AgoraClientRoleChangeFailedConnectionFailed`。 ### 问题修复 [#问题修复-46] 无。 ## v4.3.2 [#v432-2] 该版本于 2024 年 6 月 4 日发布。 ### 改进 [#改进-41] 提升了 [`setRemoteSubscribeFallbackOption:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_setremotesubscribefallbackoption) 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 [`setRemoteSubscribeFallbackOption:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_setremotesubscribefallbackoption) 动态切换弱网环境下的音视频流回退选项。 ### 问题修复 [#问题修复-47] 该版本修复了以下问题： - 音视频互动过程中偶现视频流畅度不佳。 - 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。 - 远端用户离开频道时偶现崩溃。 ## v4.3.1 [#v431-2] 该版本于 2024 年 4 月 29 日发布。 ### 新增特性 [#新增特性-36] #### 人像锁定 [#人像锁定-1] 为提升在线会议、秀场、在线教育等场景中的主播演讲效果，该版本新增 [`enableCameraCenterStage:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) 方法开启人像锁定功能。该功能可确保主播无论移动与否，始终位于画面中心，以取得良好的演讲效果。 在开启人像锁定前，建议你先调用 [`isCameraCenterStageSupported`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) 查询当前设备性能是否支持该功能。支持的设备清单可参考 [`API 文档`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage)。 #### 数据流加密 [#数据流加密-2] 该版本在 [`AgoraEncryptionConfig`](/zh-CN/api-reference/rtc/macos/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` 成员用于启用数据流加密。你可以在调用 [`enableEncryption:encryptionConfig:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_enableencryption) 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` 和 `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` 枚举得知。 #### 视频小流自适应配置 [#视频小流自适应配置-2] 该版本新增视频小流的自适应配置功能，当你调用 [`setDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setdualstreammode2) 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示： - 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。 - 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。 #### 其他 [#其他-12] - 新增 [`enableEncryptionEx:encryptionConfig:connection:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengineex_enableencryptionex) 方法，用于多频道场景下开启媒体流或数据流加密。 - 新增 [`setAudioMixingPlaybackSpeed:`](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) 方法，用于设置音乐文件的播放速度。 - 新增 [`getCallIdEx:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengineex_getcallidex) 方法，用于多频道场景下获取通话 ID。 ### 改进 [#改进-42] #### 本地视频状态回调优化 [#本地视频状态回调优化-1] 为方便你了解本地视频状态改变的具体原因，该版本在 [`rtcEngine:localVideoStateChangedOfState:reason:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调的 [`AgoraLocalVideoStreamReason`](/zh-CN/api-reference/rtc/macos/enum-localvideostreamreason) 枚举类中新增如下枚举： - `AgoraLocalVideoStreamReasonScreenCaptureRecoverFromMinimized` (27)：进行屏幕采集的窗口已经从最小化状态恢复正常。 #### 获取音频设备类型 [#获取音频设备类型] 该版本在 [`AgoraRtcDeviceInfo`](/zh-CN/api-reference/rtc/macos/class-agorartcdeviceinfo) 中新增 `deviceTypeName` 成员，用于获取音频设备的类型，如 built-in、USB、HDMI 等。 #### 虚拟背景算法优化 [#虚拟背景算法优化-5] 为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法： - 支持识别任意纯色背景，不再局限于绿幕。 - 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。 - 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。 #### 音频自采集优化 [#音频自采集优化-1] 为提升音频自采集的灵活性，该版本废弃 [`pushExternalAudioFrameSampleBuffer:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#pushexternalaudioframesamplebuffer) 并新增 [`pushExternalAudioFrameSampleBuffer:sampleRate:channels:trackId:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_pushexternalaudioframesamplebuffer2)。相比废弃方法，新增方法中增加了 `sampleRate`、`channels`、`trackId` 参数，支持你通过自定义音频轨道将外部 CMSampleBuffer 音频数据推送到频道内，并支持设置外部音频源的采样率和声道数。 #### 降低耳返的 CPU 消耗 [#降低耳返的-cpu-消耗-2] 该版本在 [`AgoraEarMonitoringFilterType`](/zh-CN/api-reference/rtc/macos/enum-earmonitoringfiltertype) 中新增 `AgoraEarMonitoringFilterReusePostProcessingFilter`(1<<15) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。 #### 其他改进 [#其他改进-20] 该版本还进行了如下改进： - 优化了非屏幕共享场景的视频编解码策略，节省系统性能开销。 - 针对 macOS 14 及以上系统，优化了 [`getScreenCaptureSourcesWithThumbSize:iconSize:includeScreen:`](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_getscreencapturesources) 的行为。自该版本起，调用该方法返回的可用窗口资源中会自动过滤小组件窗口。 - 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。 - 在 [`AgoraAudioEffectPreset`](/zh-CN/api-reference/rtc/macos/enum-audioeffectpreset) 中新增 `AgoraAudioEffectPresetRoomAcousticsChorus`（合唱音效），可使人声在合唱场景下更具空间立体感。 - 在 [`AgoraRtcRemoteAudioStats`](/zh-CN/api-reference/rtc/macos/class-remoteaudiostats) 中新增 `e2eDelay`，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。 ### 问题修复 [#问题修复-48] 该版本修复了以下问题： - 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。 - 用户插拔一次蓝牙或有线耳机，音频状态改变回调 [`rtcEngine:device:type:stateChanged:`](/zh-CN/api-reference/rtc/macos/device-management/common-device#api_irtcengine_statechanged) 会触发多次。 - 当发送端用户的网络环境恶化（例如弱网）时，接收端偶现视频流畅度降低、卡顿增加。 ### API 变更 [#api-变更-16] #### 新增 [#新增-16] - [`enableCameraCenterStage:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) - [`isCameraCenterStageSupported`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) - [`AgoraLocalVideoStreamReason`](/zh-CN/api-reference/rtc/macos/enum-localvideostreamreason) 中新增如下枚举： - `AgoraLocalVideoStreamReasonScreenCaptureRecoverFromMinimized` - [`AgoraEncryptionConfig`](/zh-CN/api-reference/rtc/macos/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` - [`AgoraEncryptionErrorType`](/zh-CN/api-reference/rtc/macos/enum-encryptionerrortype) 中新增如下枚举： - `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` - `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` - [`AgoraRtcDeviceInfo`](/zh-CN/api-reference/rtc/macos/class-agorartcdeviceinfo) 新增 `deviceTypeName` - [`AgoraRtcRemoteAudioStats`](/zh-CN/api-reference/rtc/macos/class-remoteaudiostats) 新增 `e2eDelay` - [`AgoraErrorCode`](/zh-CN/api-reference/rtc/macos/enum-errorcodetype) 新增 `AgoraErrorCodeDatastreamDecryptionFailed` - [`AgoraAudioEffectPreset`](/zh-CN/api-reference/rtc/macos/enum-audioeffectpreset) 新增 `AgoraAudioEffectPresetRoomAcousticsChorus` - [`getCallIdEx:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengineex_getcallidex) - [`enableEncryptionEx:encryptionConfig:connection:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengineex_enableencryptionex) - [`setAudioMixingPlaybackSpeed:`](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) - [`AgoraEarMonitoringFilterType`](/zh-CN/api-reference/rtc/macos/enum-earmonitoringfiltertype) 新增枚举 `AgoraEarMonitoringFilterBuiltInAudioFilters`(1<<15) - [`pushExternalAudioFrameSampleBuffer:sampleRate:channels:trackId:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_pushexternalaudioframesamplebuffer2) #### 废弃 [#废弃-9] - [`pushExternalAudioFrameSampleBuffer:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#pushexternalaudioframesamplebuffer) ## v4.3.0 [#v430-2] 该版本于 2024 年 2 月 22 日发布。 ### 升级必看 [#升级必看-30] 该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 回调中的参数改名 [#回调中的参数改名-2] 为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。 | 回调 | 原有参数名 | 现有参数名 | | ---------------------------------- | --------------- | ------------------- | | [`rtcEngine:localAudioStateChanged:reason:`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) | `error` | `reason` | | `localVideoStateChanged` | `error` | `reason` | | `onDirectCdnStreamingStateChanged:reason:message:` | `error` | `reason` | | [`AgoraRtcMediaPlayer:didChangedToState:reason:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) | `error` | `reason` | | [`rtcEngine:rtmpStreamingChangedToState:state:reason:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/media-push#callback_irtcengineeventhandler_onrtmpstreamingstatechanged) | `errCode` | `reason` | | 原有枚举类 | 现有枚举类 | | ------------------------------------ | ------------------------------------ | | `AgoraAudioLocalError` | [`AgoraAudioLocalReason`](/zh-CN/api-reference/rtc/macos/enum-localaudiostreamreason) | | `AgoraLocalVideoStreamError` | [`AgoraLocalVideoStreamReason`](/zh-CN/api-reference/rtc/macos/enum-localvideostreamreason) | | `AgoraDirectCdnStreamingError` | `AgoraDirectCdnStreamingReason` | | `AgoraMediaPlayerError` | [`AgoraMediaPlayerReason`](/zh-CN/api-reference/rtc/macos/enum-mediaplayerreason) | | `AgoraRtmpStreamingError` | [`AgoraRtmpStreamingReason`](/zh-CN/api-reference/rtc/macos/enum-rtmpstreampublishreason) | | `AgoraMusicContentCenterStatusCode` | `AgoraMusicContentCenterStateReason` | :::info[信息] 有关具体枚举的改名详见 [API 变更](#apichange)。 ::: #### 跨频道媒体流转发 [#跨频道媒体流转发-4] 为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项： | 已删除的方法和回调 | 替代的方法和回调 | | --- | --- | | [release-notes-macos-html-0-1-0 details](#table-slot-release-notes-macos-html-0-1-0) | [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) | | [release-notes-macos-html-0-2-0 details](#table-slot-release-notes-macos-html-0-2-0) | [`startOrUpdateChannelMediaRelayEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) | | `didReceiveChannelMediaRelayEvent` | [`rtcEngine:channelMediaRelayStateDidChange:error:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) | **release-notes-macos-html-0-1-0 details** - `startChannelMediaRelay` - `updateChannelMediaRelay` **release-notes-macos-html-0-2-0 details** - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` #### 本地视频状态改变原因 [#本地视频状态改变原因-2] 该版本对 [`AgoraLocalVideoStreamReason`](/zh-CN/api-reference/rtc/macos/enum-localvideostreamreason) 枚举类中的枚举进行了如下修改： - `AgoraLocalVideoStreamErrorEncodeFailure` 的枚举名变更为 `AgoraLocalVideoStreamReasonCodecNotSupport`。 #### 声卡采集 [#声卡采集] - 在 v4.3.0 之前，当你调用 [`disableAudio`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#api_irtcengine_disableaudio) 关闭整个音频模块后，声卡采集功能不会被关闭。 - 从 v4.3.0 起，当你调用 [`disableAudio`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#api_irtcengine_disableaudio) 关闭音频模块后，声卡采集功能也会被关闭，如果你需要再次启用声卡采集功能，需要在调用 [`enableAudio`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#api_irtcengine_enableaudio) 启用音频模块后再次调用 [`enableLoopbackRecording:deviceName:`](/zh-CN/api-reference/rtc/macos/audio/audio-capture#api_irtcengine_enableloopbackrecording)。 #### 日志加密行为变更 [#日志加密行为变更-2] 出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案： - 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。 - 如有其他特殊需求，请[联系技术支持](https://ticket.shengwang.cn/)并附上对应的加密日志。 ### 新增特性 [#新增特性-37] #### 多视图本地预览 [#多视图本地预览-2] 该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下： 1. 调用 [`setupLocalVideo:`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第一个视图：在 [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/macos/class-videocanvas) 中设置 `position` 参数为 `AgoraVideoModulePositionPostCaptureOrigin`（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。 2. 调用 [`setupLocalVideo:`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第二个视图：在 [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/macos/class-videocanvas) 中设置 `position` 参数为 `AgoraVideoModulePositionPostCapture`，此处观测到的视频具备视频前处理的效果。 3. 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。 #### 查询设备评分等级 [#查询设备评分等级-2] 该版本新增 [`queryDeviceScore`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_querydevicescore) 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请[联系技术支持](https://ticket.shengwang.cn/)。 #### 本地播放及发布至远端的音轨控制 [#本地播放及发布至远端的音轨控制-2] 该版本新增 [`selectMultiAudioTrack:publishTrackIndex:`](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 [`openWithMediaSource:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并通过 [`AgoraMediaSource`](/zh-CN/api-reference/rtc/macos/class-mediasource) 中新增的 `enableMultiAudioTrack` 成员来开启音轨控制。 #### 其他 [#其他-13] 该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。 - [`setRemoteSubscribeFallbackOption:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_setremotesubscribefallbackoption)：设置弱网环境下订阅的音视频流回退选项。 - [`rtcEngine:didRemoteSubscribeFallbackToAudioOnly:byUid:`](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly)：订阅流已回退为音频流或恢复为音视频流回调。 - [`setPlayerOption:value:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption) 和 [`setPlayerOptionString:value:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption2)：设置媒体播放器选项，用于提供技术预览或特别定制功能。 - [`enableCustomAudioLocalPlayback:enabled:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback)：设置是否在本地播放外部音频源。 ### 改进 [#改进-43] #### SDK 任务处理调度优化 [#sdk-任务处理调度优化-2] 该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面： - 远端及本地的首帧出图与出声速度提升了 10% 到 20%。 - API 的调用耗时和响应耗时缩短了 5% 到 50%。 - SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。 - SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。 #### 耳返音量提升 [#耳返音量提升-2] 该版本为用户提供更灵活的耳返音频调整选项，支持调用 [`setInEarMonitoringVolume:`](/zh-CN/api-reference/rtc/macos/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) 将耳返音量设置为原始音量的 4 倍。 #### 空间音频易用性提升 [#空间音频易用性提升-2] - 该版本优化了 [`setZones:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 方法的设计，支持将 `zones` 参数设置为 `NULL`，表示清除所有隔声区域。 - 自该版本起，在调用 [`AgoraLocalSpatialAudioKit`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_ilocalspatialaudioengine) 中的方法之前，无需先取消订阅频道内所有远端用户的音频流。 #### 本地音频状态回调优化 [#本地音频状态回调优化-1] 该版本在 [`AgoraAudioLocalReason`](/zh-CN/api-reference/rtc/macos/enum-localaudiostreamreason) 中增加了如下枚举，用户可通过 [`rtcEngine:localAudioStateChanged:reason:`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) 回调了解更多本地音频状态改变的原因： - `AgoraAudioLocalReasonNoRecordingDevice`：无本地音频采集设备。请提示用户在设备的控制面板中检查麦克风是否与设备连接正常，检查麦克风是否正常工作。 - `AgoraAudioLocalReasonNoPlayoutDevice`：无本地音频播放设备。请提示用户在设备的控制面板中检查扬声器是否与设备连接正常，检查扬声器是否正常工作。 #### 视频前处理方法优化 [#视频前处理方法优化-2] 该版本对以下 5 个视频前处理方法新增了带 `souceType` 参数的重载方法，支持通过传入 `sourceType` 来指定视频前处理特效应用的媒体源类型（例如应用在自定义的视频采集媒体源上）： - [`setBeautyEffectOptions:options:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions2) - [`setLowlightEnhanceOptions:options:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions2) - [`setVideoDenoiserOptions:options:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions2) - [`setColorEnhanceOptions:options:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions2) - [`enableVirtualBackground:backData:segData:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground2) #### 其他改进 [#其他改进-21] 该版本还进行了如下改进： - 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。 - 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用 [`setLocalAccessPoint:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_setlocalaccesspoint) 解析域名时的稳定性。 - 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。 - [`AgoraRtcLocalAudioStats`](/zh-CN/api-reference/rtc/macos/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。 - 在使用声卡进行采集时，支持采集双声道的音频数据。 - 新增 [`AgoraRtcMediaPlayer:cacheStats:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) 回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。 - 新增 [`AgoraRtcMediaPlayer:playbackStats:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) 回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过 [`AgoraMediaPlayerPlaybackStats`](/zh-CN/api-reference/rtc/macos/class-playerplaybackstats) 来获取当前音、视频的码率等信息。 ### 问题修复 [#问题修复-49] 该版本修复了以下问题： - 当同时共享两路屏幕共享视频流时，[`rtcEngine:localVideoStats:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-basic#callback_irtcengineeventhandler_onlocalvideostats) 回调上报的 `captureFrameRate` 为 0，不符合预期。 ### API 变更 [#api-变更-17] #### 新增 [#新增-17] - [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/macos/class-videocanvas) 新增 `subviewUid` 和 `uid` 成员 - [`AgoraAudioLocalReason`](/zh-CN/api-reference/rtc/macos/enum-localaudiostreamreason) 中新增以下枚举 - `AgoraAudioLocalReasonNoRecordingDevice` - `AgoraAudioLocalReasonNoPlayoutDevice` - [`enableCustomAudioLocalPlayback:enabled:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback) - [`queryDeviceScore`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_querydevicescore) - [`AgoraMediaSourceType`](/zh-CN/api-reference/rtc/macos/enum-mediasourcetype) 中新增 `AgoraMediaSourceTypeCustomVideo` 枚举 - [`setBeautyEffectOptions:options:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions2) - [`setLowlightEnhanceOptions:options:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions2) - [`setVideoDenoiserOptions:options:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions2) - [`setColorEnhanceOptions:options:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions2) - [`enableVirtualBackground:backData:segData:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground2) - [`AgoraAudioOutputRouting`](/zh-CN/api-reference/rtc/macos/enum-audioroute) 中新增 `AgoraAudioOutputRoutingBluetoothDeviceA2dp` 枚举 - [`AgoraRtcLocalAudioStats`](/zh-CN/api-reference/rtc/macos/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员 - [`selectMultiAudioTrack:publishTrackIndex:`](/zh-CN/api-reference/rtc/macos/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) - [`AgoraRtcMediaPlayer:cacheStats:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) - [`AgoraRtcMediaPlayer:playbackStats:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) #### 修改 [#修改-7] - 以下枚举名中的 `Error` 字段全部修改为 `Reason`： - `AgoraAudioLocalErrorOK` - `AgoraAudioLocalErrorFailure` - `AgoraAudioLocalErrorDeviceNoPermission` - `AgoraAudioLocalErrorDeviceBusy` - `AgoraAudioLocalErrorRecordFailure` - `AgoraAudioLocalErrorEncodeFailure` - `AgoraLocalVideoStreamErrorOK` - `AgoraLocalVideoStreamErrorFailure` - `AgoraLocalVideoStreamErrorDeviceNoPermission` - `AgoraLocalVideoStreamErrorDeviceBusy` - `AgoraLocalVideoStreamErrorCaptureFailure` - `AgoraLocalVideoStreamErrorCodecNotSupport` - `AgoraLocalVideoStreamErrorCaptureNoDeviceFound` - `AgoraLocalVideoStreamErrorCaptureDeviceDisconnected` - `AgoraLocalVideoStreamErrorCaptureDeviceInvalidId` - `AgoraLocalVideoStreamErrorScreenCaptureWindowMinimized` - `AgoraLocalVideoStreamErrorScreenCaptureWindowClosed` - `AgoraDirectCdnStreamingErrorOK` - `AgoraDirectCdnStreamingErrorFailed` - `AgoraDirectCdnStreamingErrorAudioPublication` - `AgoraDirectCdnStreamingErrorVideoPublication` - `AgoraDirectCdnStreamingErrorNetConnect` - `AgoraDirectCdnStreamingErrorBadName` - `AgoraMediaPlayerErrorNone` - `AgoraMediaPlayerErrorInvalidArguments` - `AgoraMediaPlayerErrorInternal` - `AgoraMediaPlayerErrorNoSource` - `AgoraMediaPlayerErrorInvalidMediaSource` - `AgoraMediaPlayerErrorUnknowStreamType` - `AgoraMediaPlayerErrorObjNotInitialized` - `AgoraMediaPlayerErrorCodecNotSupported` - `AgoraMediaPlayerErrorVideoRenderFailed` - `AgoraMediaPlayerErrorInvalidState` - `AgoraMediaPlayerErrorUrlNotFound` - `AgoraMediaPlayerErrorInvalidConnectState` - `AgoraMediaPlayerErrorSrcBufferUnderflow` - `AgoraMediaPlayerErrorInterrupted` - `AgoraMediaPlayerErrorNotSupported` - `AgoraMediaPlayerErrorTokenExpired` - `AgoraMediaPlayerErrorUnknown` - `AgoraRtmpStreamingErrorOK` - `AgoraRtmpStreamingErrorInvalidParameters` - `AgoraRtmpStreamingErrorEncryptedStreamNotAllowed` - `AgoraRtmpStreamingErrorConnectionTimeout` - `AgoraRtmpStreamingErrorInternalServerError` - `AgoraRtmpStreamingErrorRtmpServerError` - `AgoraRtmpStreamingErrorTooOften` - `AgoraRtmpStreamingErrorReachLimit` - `AgoraRtmpStreamingErrorNotAuthorized` - `AgoraRtmpStreamingErrorStreamNotFound` - `AgoraRtmpStreamingErrorFormatNotSupported` - `AgoraRtmpStreamingErrorNotBroadcaster` - `AgoraRtmpStreamingErrorTranscodingNoMixStream` - `AgoraRtmpStreamingErrorNetDown` - `AgoraRtmpStreamingErrorInvalidPrivilege` - `AgoraRtmpStreamingErrorUnpublishOK` #### 删除 [#删除-10] - `startChannelMediaRelay` - `updateChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - `didReceiveChannelMediaRelayEvent` - `AgoraChannelMediaRelayEvent` ## v4.2.6 [#v426-2] 该版本于 2023 年 11 月 16 日发布。 ### 问题修复 [#问题修复-50] 该版本修复了以下问题： - 在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。 ## v4.2.3 [#v423-2] 该版本于 2023 年 10 月 12 日发布。 ### 新增特性 [#新增特性-38] #### 本地截图上传更新 [#本地截图上传更新-2] 为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动： - [`AgoraContentInspectType`](/zh-CN/api-reference/rtc/macos/enum-contentinspecttype) 中新增 `AgoraContentInspectTypeImageModeration` 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。 - [`AgoraContentInspectConfig`](/zh-CN/api-reference/rtc/macos/class-contentinspectconfig) 中新增的 `serverConfig` 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请[联系技术支持](https://ticket.shengwang.cn/)。 此外，该版本还新增了 [`enableContentInspectEx:config:connection:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) 方法，支持同时对多条视频流截图并上传。 #### 进阶功能查询 [#进阶功能查询-2] 该版本新增了 [`isFeatureAvailableOnDevice:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_isfeatureavailableondevice) 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。 在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。 此外，自该版本起，调用 `enableVirtualBackground` 和 `setBeautyEffectOptions` 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 `-4` 表示该设备不支持开启该功能。 ### 改进 [#改进-44] #### 优化虚拟背景内存占用 [#优化虚拟背景内存占用-2] 该版本升级了虚拟背景算法，降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。 #### 其他改进 [#其他改进-22] 该版本还进行了如下改进： - 当调用 [`setPlaybackSpeed:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，传入非法参数后会返回错误码 `-2`，表示方法中设置了无效的参数，需要重新设置参数。 - 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。 ### 问题修复 [#问题修复-51] 该版本修复了以下问题： - 加入频道偶现的崩溃。 - 本地系统时间不正确时，偶现加入频道失败。 - 调用 `playEffect` 使用相同的 `soundId` 播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 - 调用一次 [`takeSnapshotEx:uid:filePath:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 获取视频截图会收到多次 [`rtcEngine:snapshotTaken:filePath:width:height:errCode:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 视频截图结果回调。 ### API 变更 [#api-变更-18] #### 新增 [#新增-18] - [`enableContentInspectEx:config:connection:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) - [`AgoraContentInspectType`](/zh-CN/api-reference/rtc/macos/enum-contentinspecttype) 新增 `AgoraContentInspectTypeImageModeration` - [`AgoraContentInspectConfig`](/zh-CN/api-reference/rtc/macos/class-contentinspectconfig) 中新增 `serverConfig` 可选参数 - [`isFeatureAvailableOnDevice:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_isfeatureavailableondevice) - [`AgoraFeatureType`](/zh-CN/api-reference/rtc/macos/enum-featuretype) ## v4.2.2 [#v422-2] 该版本于 2023 年 7 月 27 日发布。 ### 新增特性 [#新增特性-39] #### 通配 Token [#通配-token-2] 该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 :::warning[注意] 声网 4.x RTC SDK 均支持使用通配 Token。 ::: #### 预加载频道 [#预加载频道-2] 该版本新增 [`preloadChannelByToken:channelId:uid:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_preloadchannel) 和 [`preloadChannelByTokenWithUserAccount:channelId:userAccount:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_preloadchannelwithuseraccount) 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。 在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 #### 自定义视频画布背景颜色 [#自定义视频画布背景颜色-2] 该版本在 [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/macos/class-videocanvas) 中增加了 `backgroundColor` 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。 #### 指定视频源进行预览 [#指定视频源进行预览-1] 为支持用户选择不同类型的视频源进行本地视频预览，该版本新增 [`startPreview:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_startpreview2) 和 [`stopPreview:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_stoppreview2) 方法。你可以调用 [`startPreview:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_startpreview2) 并设置 `sourceType` 指定待预览的视频源类型；然后调用 [`stopPreview:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_stoppreview2) 关闭视频预览。 :::info[信息] 该方法中设置的视频源类型需要跟 `setupLocalVideo` 中 `AgoraRtcVideoCanvas` 的视频源类型一致。 ::: #### 发布多源采集的视频流 [#发布多源采集的视频流] 该版本在 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中新增下列成员，支持你发布第三个、第四个摄像头和屏幕采集到的视频流： - `publishThirdCameraTrack`：发布第三个摄像头采集的视频。 - `publishFourthCameraTrack`：发布第四个摄像头采集的视频。 - `publishThirdScreenTrack`：发布第三个屏幕采集的视频。 - `publishFourthScreenTrack`：发布第四个屏幕采集的视频。 :::warning[注意] 目前 SDK 支持在同一时间、同一 `AgoraRtcConnection` 中发布多路音频流、一路视频流。 ::: ### 改进 [#改进-45] #### 虚拟背景算法升级 [#虚拟背景算法升级-2] 该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。 #### 跨频道连麦优化 [#跨频道连麦优化-2] 该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 时，你可以指定最多 6 个目标频道。 #### 视频编解码查询能力增强 [#视频编解码查询能力增强-2] 为提升设备编解码能力查询功能，该版本在 `CodecCapAgoraVideoCodecCapInfoInfo` 中新增 `codecLevels` 成员。当成功调用 [`queryCodecCapability`](/zh-CN/api-reference/rtc/macos/device-management/video-device#api_irtcengine_querycodeccapability) 后，可通过 `codecLevels` 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。 #### 其他改进 [#其他改进-23] - 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。 - 为帮助用户了解更多类型的远端视频状态改变的原因，[`rtcEngine:remoteVideoStateChangedOfUid:state:reason:elapsed:`](/zh-CN/api-reference/rtc/macos/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调中新增了 `AgoraVideoRemoteReasonCodecNotSupport` 枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。 ### 问题修复 [#问题修复-52] 该版本修复了以下问题： - 加入频道后，偶现本地用户听自己及远端的声音时出现杂音。 - 网络异常导致频道连接断开后，频道连接恢复较慢。 - 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。 - 自采集场景下，`setBeautyEffectOptions`、`setLowlightEnhanceOptions`、`setVideoDenoiserOptions` 和 `setColorEnhanceOptions` 无法自动加载插件。 ### API 变更 [#api-变更-19] #### 新增 [#新增-19] - [`startPreview:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_startpreview2) - [`stopPreview:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_stoppreview2) - [`preloadChannelByToken:channelId:uid:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_preloadchannel) - [`preloadChannelByTokenWithUserAccount:channelId:userAccount:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_preloadchannelwithuseraccount) - [`updatePreloadChannelToken:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatepreloadchanneltoken) - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中增加下列成员： - `publishThirdCameraTrack` - `publishFourthCameraTrack` - `publishThirdScreenTrack` - `publishFourthScreenTrack` - [`AgoraVideoCodecCapLevels`](/zh-CN/api-reference/rtc/macos/class-codeccaplevels) - [`AgoraVideoCodecCapabilityLevel`](/zh-CN/api-reference/rtc/macos/enum-videocodeccapabilitylevel) - [`AgoraRtcVideoCanvas`](/zh-CN/api-reference/rtc/macos/class-videocanvas) 中增加 `backgroundColor` 成员 - `CodecCapAgoraVideoCodecCapInfoInfo` 中增加 `codecLevels` 成员 - [`AgoraVideoRemoteReason`](/zh-CN/api-reference/rtc/macos/enum-remotevideostatereason) 中增加 `AgoraVideoRemoteReasonCodecNotSupport` 枚举 ## v4.2.1 [#v421-2] 该版本于 2023 年 6 月 21 日发布。 ### 改进 [#改进-46] 该版本改进了网络传输策略，提升了音视频交互的流畅度。 ### 问题修复 [#问题修复-53] 该版本修复了以下问题： - SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。 - 发送端调用 [`setAINSMode:mode:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。 - 发送端启用屏幕共享功能后，偶现接收端看到共享画面的延迟较高。 ## v4.2.0 [#v420-2] 该版本于 2023 年 5 月 24 日发布。 ### 升级必看 [#升级必看-31] 该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。 #### 视频数据获取 [#视频数据获取-2] - [`onCaptureVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调中新增了 `sourceType` 参数，用于表示具体的视频源类型。 - 以下回调已删除，请通过 [`onPreEncodeVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 和 [`onCaptureVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 中的 `sourceType` 参数得知视频源类型。 - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` #### 媒体发布选项 [#媒体发布选项-2] - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` 已删除，请改用 `publishCustomAudioTrack`。 - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的成员 `publishTrancodedVideoTrack` 变更为 `publishTranscodedVideoTrack。` - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的成员 `publishCustomAudioSourceId` 变更为 `publishCustomAudioTrackId`。 #### 音视频录制 [#音视频录制-2] - 删除 `sharedMediaRecorderWithRtcEngine` 方法，可通过该版本新增的 [`createMediaRecorder:`](/zh-CN/api-reference/rtc/macos/recording#api_irtcengine_createmediarecorder) 方法来创建录制对象。 - 删除 [`startRecording:`](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_startrecording) 、[`stopRecording`](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderDelegate:`](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_setmediarecorderobserver) 中的 `connection` 参数。 - 删除 [`AgoraMediaRecorder`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder) 类中的 `destroy` 方法，你可直接调用该版本新增的 [`destroyMediaRecorder:`](/zh-CN/api-reference/rtc/macos/recording#api_irtcengine_destroymediarecorder) 方法来销毁录制对象以释放资源。 #### 虚拟声卡 [#虚拟声卡] 自该版本起，SDK 新增对第三方虚拟声卡的支持，你可以将第三方虚拟声卡作为 SDK 的音频输入或输出设备。你可以通过 [`rtcEngine:device:type:stateChanged:`](/zh-CN/api-reference/rtc/macos/device-management/common-device#api_irtcengine_statechanged) 回调来了解当前 SDK 选择的输入输出设备是否为虚拟声卡。 :::warning[注意] 加频道时如果设置 AgoraALD、Soundflower 作为系统的默认输入或输出设备，会造成无声。 ::: #### 其他兼容性变更 [#其他兼容性变更-2] - `didApiCallExecute` 已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。 - [`enableDualStreamMode:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_enabledualstreammode) 和 [`enableDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_enabledualstreammode3) 已废弃，请改用 [`setDualStreamMode:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setdualstreammode) 和 [`setDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setdualstreammode2)。 - `startChannelMediaRelay`、`updateChannelMediaRelay`、`startChannelMediaRelayEx` 和 `updateChannelMediaRelayEx` 已废弃，请改用 [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex)。 ### 新增特性 [#新增特性-40] #### AI 降噪 [#ai-降噪-2] 该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 [`setAINSMode:mode:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。 #### 增强虚拟背景 [#增强虚拟背景-2] 为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 `enableVirtualBackground` 方法时，将自定义背景设置为更多类型： - 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。 - 将背景替换为多种格式的本地视频。 #### 视频场景化设置 [#视频场景化设置-2] 该版本新增 [`setVideoScenario:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoscenario) 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化： - 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。 - 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。 #### 本地录制远端音视频 (Beta) [#本地录制远端音视频-beta-2] 该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 [`mediaRecorder:stateDidChanged:uid:state:reason:`](/zh-CN/api-reference/rtc/macos/recording#callback_imediarecorderobserver_onrecorderstatechanged) 、[`mediaRecorder:informationDidUpdated:uid:info:`](/zh-CN/api-reference/rtc/macos/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数，用于表示录制的音视频流的具体信息，并新增 [`createMediaRecorder:`](/zh-CN/api-reference/rtc/macos/recording#api_irtcengine_createmediarecorder) 方法，用于创建本地或远端的录制对象。 你可以通过如下方法体验本地录制远端音视频功能： - [`createMediaRecorder:`](/zh-CN/api-reference/rtc/macos/recording#api_irtcengine_createmediarecorder)：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。 - [`setMediaRecorderDelegate:`](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_setmediarecorderobserver)：设置录制回调对象。 - [`startRecording:`](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_startrecording)：开始录制。 - [`stopRecording`](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_stoprecording)：停止录制。 - [`destroyMediaRecorder:`](/zh-CN/api-reference/rtc/macos/recording#api_irtcengine_destroymediarecorder)：销毁录制对象。 #### 本地合图 [#本地合图-2] 该版本新增本地合图功能，用户可以调用 [`startLocalVideoTranscoder:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) 方法，在本地将多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）混合和渲染，以实现自定义布局和效果。通过这项功能，你可以轻松创建个性化的视频显示效果，满足各种场景需求，如远程会议、直播、在线教育场景，同时支持人像画中画等功能。 另外，SDK 还提供了[`updateLocalTranscoderConfiguration:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 方法和 [`rtcEngine:didLocalVideoTranscoderErrorWithStream:errorCode:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调。当你在开启本地合图后，可以调用 [`updateLocalTranscoderConfiguration:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 更新合图的配置；当你在开启本地合图或者更新本地合图配置失败时，可通过 [`rtcEngine:didLocalVideoTranscoderErrorWithStream:errorCode:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调得知合图失败的原因。 :::warning[注意] 本地合图对 CPU 的消耗较高，声网建议你在性能较高的设备上开启该功能。 ::: #### 多端同步 [#多端同步-2] 在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_getntpwalltimeinms) 方法获取当前的 NTP (网络时间协议) 时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。 ### 改进 [#改进-47] #### 优化变声 [#优化变声-2] 该版本新增了 [`setLocalVoiceFormant:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceformant) 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 [`setLocalVoicePitch:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch) 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。 #### 提升音视频同步能力 [#提升音视频同步能力-2] 针对自定义视频和音频采集场景，该版本新增 [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_getcurrentmonotonictimeinms) 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。 #### 优化多路摄像头及屏幕采集 [#优化多路摄像头及屏幕采集] 该版本新增 [`startCameraCapture:config:`](/zh-CN/api-reference/rtc/macos/video/camera-capture#api_irtcengine_startcameracapture) 和 [`startScreenCapture:config:`](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_startscreencapture2) 方法，通过多次调用并指定 `sourceType` 参数可以开启多路摄像头采集的视频流和多路屏幕采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头和显示器的场景。 #### 优化跨频道连麦 [#优化跨频道连麦-2] 该版本新增 [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。 #### 多路音频自采集 [#多路音频自采集-2] 为更好地满足音频自采集的场景需求，该版本新增了 [`createCustomAudioTrack:config:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) 和 [`destroyCustomAudioTrack:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#destroycustomaudiotrack) 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性： - 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。 - 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。 ### 问题修复 [#问题修复-54] 该版本修复了以下问题： - 当快速切换身份角色时，观众端听不到声音。 - 接收端默认接收小流几秒后自动变为大流。 - 调用 `getdefaultaudiodevice` 后返回值中的 `type` 字段信息错误。 - 屏幕共享偶现共享画面抖动。 ### API 变更 [#api-变更-20] #### 新增 [#新增-20] - [`startCameraCapture:config:`](/zh-CN/api-reference/rtc/macos/video/camera-capture#api_irtcengine_startcameracapture) - [`stopCameraCapture:`](/zh-CN/api-reference/rtc/macos/video/camera-capture#api_irtcengine_stopcameracapture) - [`startScreenCapture:config:`](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_startscreencapture2) - [`stopScreenCapture:`](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_stopscreencapture2) - [`startOrUpdateChannelMediaRelay:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) - [`startOrUpdateChannelMediaRelayEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) - [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_getntpwalltimeinms) - [`setVideoScenario:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoscenario) - [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_getcurrentmonotonictimeinms) - [`rtcEngine:didLocalVideoTranscoderErrorWithStream:errorCode:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) - [`startLocalVideoTranscoder:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) - [`updateLocalTranscoderConfiguration:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) - [`setAINSMode:mode:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) - [`createCustomAudioTrack:config:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#api_irtcengine_createcustomaudiotrack) - [`destroyCustomAudioTrack:`](/zh-CN/api-reference/rtc/macos/audio/audio-custom-capturenrendering#destroycustomaudiotrack) - [`createMediaRecorder:`](/zh-CN/api-reference/rtc/macos/recording#api_irtcengine_createmediarecorder) - [`destroyMediaRecorder:`](/zh-CN/api-reference/rtc/macos/recording#api_irtcengine_destroymediarecorder) - `AudioTrackConfig` - [`AgoraRecorderStreamInfo`](/zh-CN/api-reference/rtc/macos/class-recorderstreaminfo) - [`AUDIO_AINS_MODE`](/zh-CN/api-reference/rtc/macos/enum-audioainsmode) - [`AgoraAudioTrackType`](/zh-CN/api-reference/rtc/macos/enum-audiotracktype) - [`AgoraApplicationScenarioType`](/zh-CN/api-reference/rtc/macos/enum-videoapplicationscenariotype) - `AgoraScreenCaptureFrameRateCapability` - [`AgoraRtcEngineConfig`](/zh-CN/api-reference/rtc/macos/class-rtcengineconfig) 中新增 `domainLimit` 和 `autoRegisterAgoraExtensions` 属性 - [`mediaRecorder:stateDidChanged:uid:state:reason:`](/zh-CN/api-reference/rtc/macos/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`mediaRecorder:informationDidUpdated:uid:info:`](/zh-CN/api-reference/rtc/macos/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数 - [`onCaptureVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame:sourceType:`](/zh-CN/api-reference/rtc/macos/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 中增加 `sourceType` 参数 - [`AgoraVirtualBackgroundSourceType`](/zh-CN/api-reference/rtc/macos/enum-backgroundsourcetype) 中新增 `AgoraVirtualBackgroundNone` 和 `AgoraVirtualBackgroundVideo` #### 废弃 [#废弃-10] - [`enableDualStreamMode:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_enabledualstreammode) - [`enableDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_enabledualstreammode3) - `startChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelay` - `updateChannelMediaRelayEx` - `didReceiveChannelMediaRelayEvent` - `AgoraChannelMediaRelayEvent` #### 删除 [#删除-11] - `startPrimaryScreenCapture` - `startSecondaryScreenCapture` - `stopPrimaryScreenCapture` - `stopSecondaryScreenCapture` - `startPrimaryCameraCapture` - `startSecondaryCameraCapture` - `stopPrimaryCameraCapture` - `stopSecondaryCameraCapture` - `didApiCallExecute` - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的 ` publishCustomAudioTrackEnableAec` - `sharedMediaRecorderWithRtcEngine` - [`AgoraMediaRecorder`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediarecorder) 类中的 `destroy` - [`startRecording:`](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_startrecording)、[`stopRecording`](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderDelegate:`](/zh-CN/api-reference/rtc/macos/recording#api_imediarecorder_setmediarecorderobserver) 中删除 `connection` 参数 - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` ## v4.1.1 [#v411-2] 该版本于 2023 年 2 月 8 日发布。 ### 升级必看 [#升级必看-32] #### 默认分辨率 [#默认分辨率-1] 自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。 如果你想自定义视频编码分辨率，可调用 [`setVideoEncoderConfiguration:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法，重新设置视频编码参数配置中的视频编码分辨率。 :::warning[注意] 由于默认分辨率的提升，会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 设置远端视频流的订阅选项 [#设置远端视频流的订阅选项-1] 该版本起，`setRemoteVideo` 更名为 [`setRemoteVideoSubscriptionOptions:options:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions)；`setRemoteVideoEx` 更名为 [`setRemoteVideoSubscriptionOptionsEx:options:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex)。如果你将 SDK 升级至该版本或更高版本，请在调用处同步修改以上两个方法的名称。 ### 新增特性 [#新增特性-41] #### 快速出图出声 [#快速出图出声-2] 该版本新增 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_enableinstantmediarendering) 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。 #### 视频渲染数据打点 [#视频渲染数据打点-2] 该版本新增 [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_startmediarenderingtracing) 和 [`startMediaRenderingTracingEx:`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 [`rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:`](/zh-CN/api-reference/rtc/macos/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告相关事件的信息。 声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 [`rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:`](/zh-CN/api-reference/rtc/macos/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。 ### 改进 [#改进-48] #### 视频观测器 [#视频观测器-2] 自该版本起，SDK 对 [`onRenderVideoFrame:uid:channelId:`](/zh-CN/api-reference/rtc/macos/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 回调进行了优化，在不同的视频处理模式下返回值的意义不同： - 当视频处理模式为 `AgoraVideoFrameProcessModeReadOnly` 时，返回值无实际含义。 - 当视频处理模式为 `AgoraVideoFrameProcessModeReadWrite` 时，返回 `YES` 代表设置 SDK 接收视频帧；返回 `NO` 代表设置 SDK 丢弃视频帧。 ### 问题修复 [#问题修复-55] 该版本修复了以下问题： - 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。 - 把播放器的渲染视图设为 `UIViewController` 的视图后，使用播放器播放视频，视频窗口切到全屏时视频画面会从左下角开始逐渐放大。 - 加入频道后接入外接摄像头，调用 [`setDevice:deviceId:`](/zh-CN/api-reference/rtc/macos/device-management/video-device#api_irtcengine_setdevice_irtcengine) 指定视频采集设备为该外接摄像头，方法未生效。 - 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。 - 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。 ### API 变更 [#api-变更-21] #### 新增 [#新增-21] - [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_enableinstantmediarendering) - [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengine_startmediarenderingtracing) - [`startMediaRenderingTracingEx:`](/zh-CN/api-reference/rtc/macos/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) - [`rtcEngine:videoRenderingTracingResultOfUid:currentEvent:tracingInfo:`](/zh-CN/api-reference/rtc/macos/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) - [`AgoraMediaTraceEvent`](/zh-CN/api-reference/rtc/macos/enum-mediatraceevent) - [`AgoraVideoRenderingTracingInfo`](/zh-CN/api-reference/rtc/macos/class-videorenderingtracinginfo) #### 修改 [#修改-8] - `setRemoteVideo` 更名为 [`setRemoteVideoSubscriptionOptions:options:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) - `setRemoteVideoEx` 更名为 [`setRemoteVideoSubscriptionOptionsEx:options:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) #### 删除 [#删除-12] - `enableRemoteSuperResolution` - [`AgoraRtcRemoteVideoStats`](/zh-CN/api-reference/rtc/macos/class-remotevideostats) 中删除 `superResolutionType` ## v4.1.0 [#v410-2] 该版本于 2022 年 12 月 19 日发布。 ### 新增特性 [#新增特性-42] #### 耳机均衡器 [#耳机均衡器-2] 该版本新增 [`setHeadphoneEQParameters:highGain:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) 方法，用于调节耳机均衡器的低频和高频参数，主要应用于空间音频场景。如果在调用 [`setHeadphoneEQPreset:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。 #### 已编码视频帧观测器 [#已编码视频帧观测器-1] 该版本在 [`AgoraRtcEngineKit`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 及 [`AgoraRtcEngineKitEx`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineex) 中新增 `setRemoteVideo` 方法，当你调用 `setEncodedVideoFrameDelegate` 方法为编码后的视频注册视频帧观测器时，SDK 默认订阅编码后的视频帧。如果你想要修改订阅选项，可以调用该新增的方法进行设置。 有关更多注册视频观测器和订阅选项的介绍，详见 [API 参考](/zh-CN/api-reference/rtc/macos/video/video-encoded#api_irtcengine_registervideoencodedframeobserver)。 #### MPUDP (MultiPath UDP) [#mpudp-multipath-udp-2] 自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在移动端和桌面端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。 :::info[信息] 如果你希望体验该功能，请联系 sales@shengwang.cn。 ::: #### 设备管理 [#设备管理] 该版本新增了一系列回调，帮助你更好地了解音视频设备的状态。 - `onVideoDeviceStateChanged`（C++）：当视频设备的状态发生改变时上报。 - `onAudioDeviceStateChanged`（C++）：当音频设备的状态发生改变时上报。 - `onAudioDeviceVolumeChanged`（C++）：当音频设备或 App 的音量发生改变时上报。 #### 摄像头采集选项 [#摄像头采集选项-2] 该版本在 [`AgoraCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/macos/class-cameracapturerconfiguration) 中增加了 `followEncodeDimensionRatio` 成员，你可以在使用摄像头采集视频时，通过该成员设置是否跟随 [`setVideoEncoderConfiguration:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中已经设置的视频宽高比。 #### 多频道管理 [#多频道管理-2] 该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。 - 新增 [`muteLocalAudioStreamEx:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) 和 [`muteLocalVideoStreamEx:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) 方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增 [`muteAllRemoteAudioStreamsEx:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) 和 [`muteAllRemoteVideoStreamsEx:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) 方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增 [`startRtmpStreamWithoutTranscodingEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex)、[`startRtmpStreamWithTranscodingEx:transcoding:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex)、[`updateRtmpTranscodingEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) 和 [`stopRtmpStreamEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) 方法，用于实现多频道场景下的旁路推流。 - 新增 `startChannelMediaRelayEx`、`updateChannelMediaRelayEx`、[`pauseAllChannelMediaRelayEx:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex)、[`resumeAllChannelMediaRelayEx:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) 和 [`stopChannelMediaRelayEx:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) 方法，用于实现多频道场景下的跨频道媒体流转发。 - 新增 [`leaveChannelEx:options:leaveChannelBlock:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_leavechannelex2) 方法，相较于 [`leaveChannelEx:leaveChannelBlock:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_leavechannelex) 方法新增了 `options` 参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。 #### 视频编码偏好 [#视频编码偏好-2] 一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 [`AgoraVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/macos/class-videoencoderconfiguration) 中新增 `advancedVideoOptions` 成员，用于视频编码属性的进阶设置： - `compressionPreference`：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。 - `encodingPreference`：视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。 #### 日志上传 [#日志上传-2] 使用声网私有媒体服务器的场景下，为支持用户在调用 [`setLocalAccessPoint:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_setlocalaccesspoint) 方法时的进阶设置，该版本在 [`AgoraLocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/macos/class-localaccesspointconfiguration) 中新增 `advancedConfig` 成员参数，该参数支持如下设置： `logUploadServer`：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。 #### 用户角色切换 [#用户角色切换-2] 为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 [`rtcEngine:didClientRoleChanged:newRole:newRoleOptions:`](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调中新增 `newRoleOptions` 参数，该参数取值如下： - `AgoraAudienceLatencyLevelLowLatency`(1): 低延时，属于极速直播。 - `AgoraAudienceLatencyLevelUltraLowLatency`(2): 超低延时，属于互动直播。 ### 改进 [#改进-49] #### 屏幕共享 [#屏幕共享-3] 该版本对屏幕共享功能做了一系列优化，除以下列出的功能性改进之外，还有一部分可用性提升，详见问题修复。 - 兼容更多设备和场景，包括但不限于：双显卡设备，使用外接屏幕进行屏幕共享。 - 支持超高清视频 (分辨率为 4K，帧率为 60 fps)，你可以在满足要求的设备上使用该功能。声网推荐的最低设备规格为：2021年m1 MacBook pro 16 英寸。 #### CDN 推流 [#cdn-推流-2] 为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 `onDirectCdnStreamingStats:` 回调报告推送的视频流的实际分辨率。 #### 跨频道媒体流转发 [#跨频道媒体流转发-5] 该版本对 `updateChannelMediaRelay` 方法做了如下优化： - 4.1.0 版本前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码 `AgoraChannelMediaRelayEventUpdateDestinationChannelRefused`(8)，你需要重新调用 `updateChannelMediaRelay` 方法。 - 4.1.0 版本及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。 #### AIAEC [#aiaec-2] 该版本基于 AI 方法重构了AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。 #### 虚拟背景 [#虚拟背景-2] 该版本对虚拟背景算法做了如下优化： - 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。 - 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。 - 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。 - 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。 #### 其他改进 [#其他改进-24] - 降低了推送外部音频源时的上行延迟。 - 提升了会议场景 (`AgoraAudioScenarioMeeting`) 默认参数配置下的回声消除性能。 - 提升了 SDK 视频渲染的流畅度。 - 降低了当主播调用 [`muteLocalVideoStream:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_mutelocalvideostream) 方法时本地设备的 CPU 占用率和耗电量。 - 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。 ### 问题修复 [#问题修复-56] 该版本修复了以下问题： - 在屏幕共享场景下，将共享的窗口最小化或关闭共享窗口时，共享窗口自动切换为该 App 的其他窗口。 - 在屏幕共享场景下偶现系统声音音量变小。 - 在屏幕共享场景下，当共享的窗口为半屏模式时，对窗口的描边不正确。 - 在屏幕共享场景下，远端用户看到的画面偶现黑屏、卡顿、崩溃。 - 在屏幕共享场景下，偶现 [`rtcEngine:networkQuality:txQuality:rxQuality:`](/zh-CN/api-reference/rtc/macos/network#callback_irtcengineeventhandler_onnetworkquality) 回调报告频道内指定用户的上下行网络状态不准确。 - 启动并停止音频采集设备测试后，启动音频播放设备测试时必现无声。 - 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。 - [`rtcEngine:didVideoPublishStateChange:sourceType:oldState:newState:elapseSinceLastState:`](/zh-CN/api-reference/rtc/macos/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 回调报告的视频源类型不准确。 - 调用 `getExtensionPropertyWithVendor` 失败，返回空字符串。 - 当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。 ### API 变更 [#api-变更-22] #### 新增 [#新增-22] - [`setHeadphoneEQParameters:highGain:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) - [`setRemoteVideoSubscriptionOptions:options:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) - [`setRemoteVideoSubscriptionOptionsEx:options:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) - [`AgoraVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/macos/class-videosubscriptionoptions) - [`muteLocalAudioStreamEx:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) - [`muteLocalVideoStreamEx:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) - [`muteAllRemoteAudioStreamsEx:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) - [`muteAllRemoteVideoStreamsEx:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) - [`startRtmpStreamWithoutTranscodingEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex) - [`startRtmpStreamWithTranscodingEx:transcoding:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex) - [`updateRtmpTranscodingEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) - [`stopRtmpStreamEx:connection:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - [`pauseAllChannelMediaRelayEx:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex) - [`resumeAllChannelMediaRelayEx:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) - [`stopChannelMediaRelayEx:`](/zh-CN/api-reference/rtc/macos/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) - [`AgoraCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/macos/class-cameracapturerconfiguration) 中增加 `followEncodeDimensionRatio` - [`AgoraRtcLocalVideoStats`](/zh-CN/api-reference/rtc/macos/class-localvideostats) 中增加 `hwEncoderAccelerating` - [`leaveChannelEx:options:leaveChannelBlock:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_leavechannelex2) - [`AgoraVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/macos/class-videoencoderconfiguration) 中增加 `advancedVideoOptions` 成员 - [`AgoraLocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/macos/class-localaccesspointconfiguration) 中增加 `advancedConfig` 成员 - [`rtcEngine:didClientRoleChanged:newRole:newRoleOptions:`](/zh-CN/api-reference/rtc/macos/channel#callback_irtcengineeventhandler_onclientrolechanged) 中增加 `newRoleOptions` - [`adjustUserPlaybackSignalVolumeEx:volume:connection:`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#api_irtcengineex_adjustuserplaybacksignalvolumeex) - [`enableAudioVolumeIndicationEx:smooth:reportVad:connection:`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#api_irtcengineex_enableaudiovolumeindicationex) #### 废弃 [#废弃-11] - `didApiCallExecute`，改用具体方法触发的回调。 #### 删除 [#删除-13] - 删除了 [`AgoraLiveTranscoding`](/zh-CN/api-reference/rtc/macos/class-livetranscoding) 类中的废弃成员参数 `backgroundImage` 和 `watermark` - `didReceiveChannelMediaRelayEvent` 中删除 `AgoraChannelMediaRelayEventUpdateDestinationChannelRefused`(8) ## v4.0.1 [#v401-2] 该版本于 2022 年 9 月 29 日发布。 ### 升级必看 [#升级必看-33] 如果你已经使用了以下类或方法，请在升级到该版本后重新调用方法并更新参数设置。 1. 为提高代码易用性，该版本将以下类中 `Optional` 类型的参数变更为 `Bool`、`Int` 等基本数据类型： - `AgoraDirectCdnStreamingMediaOptions` 中 `publishCameraTrack`、`publishMicrophoneTrack`、`publishCustomAudioTrack`、`publishCustomVideoTrack`、`publishMediaPlayerAudioTrack` 的参数类型由 `Optional` 变为 `Bool` 型。 - [`AgoraMediaSource`](/zh-CN/api-reference/rtc/macos/class-mediasource) 中的 `isAgoraSource` 和 `isLiveSource` 由 `Optional` 型变为 `Bool` 型。 - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的所有参数类型由 `Optional` 变为 `Bool` 型或 `Int` 型。 2. [`destroyCustomVideoTrack:`](/zh-CN/api-reference/rtc/macos/video/video-custom-capturenrendering#api_irtcengine_destroycustomvideotrack) 方法中的 `position` 参数变更为 `trackid`。 3. 删除了 `enableDualStreamMode:sourceType:streamConfig:` 和 `enableDualStreamModeEx:sourceType:streamConfig:connection:` 中的 `sourceType` 参数以及 [`enableDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_enabledualstreammode3) 方法，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。 ### 新增特性 [#新增特性-43] #### 耳返 [#耳返-2] 该本版新增耳返功能。你可以调用 `enableInEarMonitoring` 开启耳返功能。 成功开启耳返功能后，你可以调用 [`setAudioFrameDelegate:`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#api_irtcengine_registeraudioframeobserver) 注册音频观测器，SDK 会触发 [`onEarMonitoringAudioFrame:`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#onearmonitoringaudioframe) 回调报告耳返原始音频数据。你可以使用自己的音效处理模块对耳返音频数据进行前处理，实现自定义音效，声网推荐你在如下两种方式中选其一来设置耳返音频数据格式： - 调用 [`setEarMonitoringAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#api_irtcengine_setearmonitoringaudioframeparameters) 方法设置耳返音频数据格式，SDK 会根据该方法中的参数计算采样间隔，并根据该采样间隔触发 [`onEarMonitoringAudioFrame:`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#onearmonitoringaudioframe) 回调。 - 在 [`getEarMonitoringAudioParams`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#getearmonitoringaudioparams) 回调的返回值中设置耳返音频数据格式，SDK 会根据该回调的返回值计算采样间隔，并根据该采样间隔触发 [`onEarMonitoringAudioFrame:`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#onearmonitoringaudioframe) 回调。 如需调节耳返音量，你可以调用 [`setInEarMonitoringVolume:`](/zh-CN/api-reference/rtc/macos/audio/audio-capture#api_irtcengine_setinearmonitoringvolume)。 #### 本地网络连接类型 [#本地网络连接类型-2] 为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 [`getNetworkType`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_getnetworktype) 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 `networkTypeChangedToType` 回调，报告当前的网络连接类型。 #### 音强选流 [#音强选流-2] 该版本新增音强选流功能。该功能开启后，声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请联系技术支持。 同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗，详见[音强选流](/zh-CN/realtime-media/rtc/build/audio/audio-stream-filter)。 :::info[信息] 如需开启该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: #### 双流模式 [#双流模式-2] 该版本对双流模式做了优化，在加入频道前后均可调用 `enableDualStreamMode` 和 `enableDualStreamModeEx。` 扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式（即：默认不主动发送小流），可通过以下步骤开启发送小流： 1. 接收端主播调用 `setRemoteVideoStreamType` 或 [`setRemoteDefaultVideoStreamType:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 发起接收小流申请。 2. 发送端收到申请后自动切换为发送小流模式。 如果你想修改上述发送端的默认行为，可以调用 [`setDualStreamMode:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setdualstreammode) 或 [`setDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setdualstreammode2) 方法，将 `mode` 参数设置为 `AgoraDisableSimulcastStream` （始终不发送小流）或 `AgoraEnableSimulcastStream` （始终发送小流）。 #### 空间音频 [#空间音频-4] 该版本新增了如下适用于空间音频场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。 - 隔声区域：你可以通过调用 [`setZones:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用 [`setPlayerAttenuation:playerId:forceSet:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 和 [`setRemoteAudioAttenuation:userId:forceSet:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) 方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖 [`setZones:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 中的声音衰减系数。 - 多普勒音效：你可以通过设置 `SpatialAudioParams` 中的 `enable_doppler` 参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下（比如赛车游戏场景），接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用 [`setHeadphoneEQPreset:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 方法使用预设的耳机均衡效果，以改善耳机的听感。 ### 改进 [#改进-50] #### 视频信息发生改变回调 [#视频信息发生改变回调-2] 该版本优化了 `videoSizeChangedOfUid` 的触发逻辑，当单独调用 [`startPreview`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_startpreview) 时，也可触发该回调并上报本地视频大小发生改变。 ### 问题修复 [#问题修复-57] 该版本修复了以下问题： - 通过摄像头采集视频时，如果在 [`AgoraCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/macos/class-cameracapturerconfiguration) 中设置的视频宽高比例和在 [`setVideoEncoderConfiguration:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中设置的不一致，导致本地视频预览的画面比例未按照后者的设置呈现。 - 在频道内调用 [`setVideoEncoderConfigurationEx:connection:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengineex_setvideoencoderconfigurationex) 将视频的分辨率调高时，偶现失效。 - 使用媒体播放器播放视频，先调用 [`play`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 再调用 [`pause`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/macos/play/rte-player#api_player_seek) 指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用 [`resume`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_resume) 恢复播放后，偶现视频画面出现快进。 ### API 变更 [#api-变更-23] #### 新增 [#新增-23] - `enableInEarMonitoring` - [`setEarMonitoringAudioFrameParametersWithSampleRate:channel:mode:samplesPerCall:`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#api_irtcengine_setearmonitoringaudioframeparameters) - [`onEarMonitoringAudioFrame:`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#onearmonitoringaudioframe) - [`setInEarMonitoringVolume:`](/zh-CN/api-reference/rtc/macos/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) - [`getEarMonitoringAudioParams`](/zh-CN/api-reference/rtc/macos/audio/audio-raw#getearmonitoringaudioparams) - [`getNetworkType`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_getnetworktype) - [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中新增 `isAudioFilterable` - [`setDualStreamMode:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setdualstreammode) - [`setDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setdualstreammode2) - [`setDualStreamModeEx:streamConfig:connection:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengineex_setdualstreammodeex) - [`AgoraSimulcastStreamMode`](/zh-CN/api-reference/rtc/macos/enum-simulcaststreammode) - [`setZones:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) - [`setPlayerAttenuation:playerId:forceSet:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) - [`setRemoteAudioAttenuation:userId:forceSet:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) - `muteRemoteAudioStream:mute:` - `SpatialAudioParams` - [`setHeadphoneEQPreset:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) - [`AgoraHeadphoneEQPreset`](/zh-CN/api-reference/rtc/macos/enum-headphoneequalizerpreset) #### 修改 [#修改-9] - `enableDualStreamMode:sourceType:streamConfig:` - `enableDualStreamModeEx:sourceType:streamConfig:connection:` #### 废弃 [#废弃-12] - `startEchoTestWithInterval:interval:successBlock:` #### 删除 [#删除-14] - [`enableDualStreamMode:streamConfig:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_enabledualstreammode3) ## v4.0.0 [#v400-2] 该版本于 2022 年 8 月 3 日发布。 ### 升级必看 [#升级必看-34] v4.0.0 SDK 对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见[迁移指南](/zh-CN/realtime-media/rtc/reference/migration-guide)。 - 多频道 - 媒体流发布控制 - 自定义视频采集与渲染（Media IO 方式） - 警告码 ### 新增特性 [#新增特性-44] #### 多路媒体流 [#多路媒体流-2] 该版本通过设置 [`AgoraRtcEngineKitEx`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineex) 和 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 实现一个 [`AgoraRtcEngineKit`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 实例同时采集多组音视频流并发布到远端： 调用 `joinChannelByToken` 加入首个频道后，多次调用 `joinChannelExByToken` 加入多个频道，通过不同的用户 ID (`localUid`) 和 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 设置发布指定的流到不同的频道。 支持通过设置 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的 `publishSecondaryCameraTrack` 和 `publishSecondaryScreenTrack` 同时发布多路摄像头采集或者屏幕共享的视频流。 同时，该版本支持通过 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/macos/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流： 1. 创建自采集视频轨道：调用 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/macos/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法创建一个自定义视频轨道，并获得视频轨道 ID。 2. 设置频道中待发布的自采集视频轨道：在每个频道的 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中，将 `customVideoTrackId` 参数设置为你想要发布的视频轨道 ID，并将 `publishCustomVideoTrack` 设置为 `YES`。 3. 推送外部视频源：调用 `pushExternalVideoFrame`，并将 `videoTrackId` 指定为步骤 2 中指定的视频轨道 ID，即可实现在多个频道中发布对应的自定义视频源。 结合多频道能力，你还可以体验如下功能： - 将多组音视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路音频流混音后通过一个用户 ID (`uid`) 发布到远端。 - 将多组视频频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路视频流合图后通过一个用户 ID (`uid`) 发布到远端。 #### 超高清分辨率 (Beta) [#超高清分辨率-beta] 为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持 4K 分辨率。优化了 FEC（Forward Error Correction）算法，可根据视频帧包数与帧率进行自适应切换，降低 4K 场景下的视频卡顿率。 你可以在调用 [`setVideoEncoderConfiguration:`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 时，设置编码分辨率为 4K (3840 × 2160)、帧率为 60 fps。当你的设备不支持 4K 时，SDK 支持自动回退到适合的分辨率和帧率。 :::info[信息] - 该功能对设备性能和网络带宽有一定要求，在不同的平台上支持的上下行帧率也不同，如需体验该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 - 高分辨率可能会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 内置媒体播放器 [#内置媒体播放器-2] 为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 [`createMediaPlayerWithDelegate:`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer) 创建媒体播放器后，你可以通过 [`AgoraRtcMediaPlayerProtocol`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer) 类的一系列方法体验内置媒体播放器的各类功能： - 自动播放本地、在线、自定义的媒体资源。 - 预先加载待播放的媒体资源。 - 根据网络情况切换媒体资源的播放线路。 - 将媒体播放器的音视频流推送到任意频道、分享给远端用户。 - 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。 #### 新版 AI 降噪 [#新版-ai-降噪-2] 自该版本起，SDK 支持新版 AI 降噪（相对于 v3.7.0 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。 :::info[信息] 如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。 ::: #### 超高音质 [#超高音质-2] 为还原音频的细节、提升音频的清晰度，该版本在 [`AgoraVoiceBeautifierPreset`](/zh-CN/api-reference/rtc/macos/enum-voicebeautifierpreset) 中新增 `AgoraVoiceBeautifierUltraHighQuality`。在语聊、歌唱等以人声为主的场景中，你可以调用 [`setVoiceBeautifierPreset:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) 并使用该枚举体验超高音质。 #### 空间音频 [#空间音频-5] :::info[信息] 空间音频功能当前处于实验阶段，请联系 sales@shengwang.cn 开通空间音频功能，如果需要技术支持，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: 该版本提供本地直角坐标系计算方案实现空间音频： - 该方案使用 [`AgoraLocalSpatialAudioKit`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_ilocalspatialaudioengine) 类实现空间音频，通过 SDK 计算远端用户的空间坐标。你需要分别调用 [`updateSelfPosition:axisForward:axisRight:axisUp:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`updateRemotePosition:positionInfo:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音频。 ![](https://web-cdn.agora.io/docs-files/1646815686507) - 该方案通过 SDK 计算媒体播放器的空间坐标。你需要在 `AgoraCloudSpatialAudioKit` 或 [`AgoraLocalSpatialAudioKit`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_ilocalspatialaudioengine) 类中分别调用 [`updateSelfPosition:axisForward:axisRight:axisUp:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`updatePlayerPositionInfo:positionInfo:`](/zh-CN/api-reference/rtc/macos/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateplayerpositioninfo) 更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音频。 ![](https://web-cdn.agora.io/docs-files/1646815708012) #### 实时合唱 [#实时合唱-2] 该版本为实时合唱赋予了如下能力： - 支持两人及两人以上合唱。 - 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。 - 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。 该版本在 [`AgoraAudioScenario`](/zh-CN/api-reference/rtc/macos/enum-audioscenariotype) 中新增 `AgoraAudioScenarioChorus` 枚举设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。 #### 云市场插件 [#云市场插件-2] 为在声网 SDK 的基础上增强实时音视频互动性，该版本支持[声网云市场](https://www.agora.io/cn/marketplace)插件的一站式解决方案： - 方便集成：只需执行简单统一的 API 即可实现模块化功能的集成，将实时互动模块集成效率提高约 95%。 - 可扩展性设计：模块化和可扩展的 SDK 设计风格赋予了声网 SDK 良好的可扩展性，更有利于开发者基于声网云市场插件生态快速搭建好用的实时互动应用。 - 打造生态系统：可容纳众多开发者的实时音视频 App 社区，提供多种扩展组合。添加并开启云市场插件后，开发者可以实现更为丰富的实时音视频互动功能。 - 助力服务商：支持服务商将技术产品以插件的形式与声网 SDK 做技术上的融合，在声网云市场中展示并售卖，与声网一起共建开发者的实时互动生态系统。如何开发和发布插件详见[云市场-开发插件](/zh-CN/realtime-media/marketplace/build/create-extensions/publish)。 #### 增强的频道管理 [#增强的频道管理-2] 为满足各类业务场景对频道管理的需求，该版本在 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中新增了如下功能： - 设置或切换多种音视频源的发布 - 设置或切换频道场景、用户角色 - 设置或切换订阅视频的大小流类型 - 控制音频发布时延 在调用 `joinChannelByToken` 或 `joinChannelExByToken` 时设置 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions)，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 [`updateChannelWithMediaOptions:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatechannelmediaoptions) 随时更新 [`AgoraRtcChannelMediaOptions`](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中的设置，例如，切换发布的音视频源。 #### 屏幕共享 [#屏幕共享-4] 该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享： - 在加入频道前调用 [`startScreenCaptureByDisplayId:regionRect:captureParams:`](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_startscreencapturebydisplayid)，然后调用 [`joinChannelByToken:channelId:uid:mediaOptions:joinSuccess:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_joinchannel2) 加入频道并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `YES`，即可开始屏幕共享。 - 在加入频道后调用 [`startScreenCaptureByDisplayId:regionRect:captureParams:`](/zh-CN/api-reference/rtc/macos/video/screencapture#api_irtcengine_startscreencapturebydisplayid)，然后调用 [`updateChannelWithMediaOptions:`](/zh-CN/api-reference/rtc/macos/channel#api_irtcengine_updatechannelmediaoptions) 设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `YES`，即可开始屏幕共享。 #### 设置音视频流订阅黑/白名单 [#设置音视频流订阅黑白名单-2] 该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通 [`AgoraRtcEngineKitEx`](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineex) 类下的同名方法来实现该功能。 - `setSubscribeAudioBlacklist`：设置音频订阅黑名单。 - `setSubscribeAudioWhitelist`：设置音频订阅白名单。 - `setSubscribeVideoBlacklist`：设置视频订阅黑名单。 - `setSubscribeVideoWhitelist`：设置视频订阅白名单。 如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。 #### 设置音频场景 [#设置音频场景-2] 为方便用户灵活修改音频场景，该版本新增 [`setAudioScenario:`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#api_irtcengine_setaudioscenario) 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (`AgoraAudioScenarioDefault`) 切换为高音质场景 (`AgoraAudioScenarioGameStreaming`)，你可以调用该方法。 #### 设置本地代理 [#设置本地代理-2] 该本版新增 [`setLocalAccessPoint:`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_setlocalaccesspoint) 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。 #### 垫片推流 [#垫片推流-2] 该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 [`enableVideoImageSource:options:`](/zh-CN/api-reference/rtc/macos/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 来开启该功能，并通过 `options` 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。 ### 改进 [#改进-51] #### 快速切换频道 [#快速切换频道-2] 该版本通过 `leaveChannel` 和 `joinChannelByToken` 切换频道即可实现和 v3.7.0 中 `switchChannelByToken` 一样的切换速度，无需额外调用 `switchChannelByToken` 方法。 #### 推送外部视频帧 [#推送外部视频帧-2] 该版本新增支持推送 I422 格式的外部视频帧，你可以通过 `pushExternalVideoFrame` 方法将 I422 格式的外部视频帧推送至 SDK。 #### 本地人声音调 [#本地人声音调-2] 该版本在 [`rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:`](/zh-CN/api-reference/rtc/macos/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 的 [`AgoraRtcAudioVolumeInfo`](/zh-CN/api-reference/rtc/macos/class-audiovolumeinfo) 中新增 `voicePitch` 参数。你可以通过 `voicePitch` 获取本地用户的人声音调，从而实现唱歌评分等业务功能。 #### 本地视频预览 [#本地视频预览-2] 该版本优化了 [`startPreview`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_startpreview) 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 [`startPreview`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_startpreview) 方法来开启视频预览，无调用时序要求。 #### 订阅视频流 [#订阅视频流-2] 你可以通过 [`setRemoteDefaultVideoStreamType:`](/zh-CN/api-reference/rtc/macos/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" /> Web SDK 4.x 是通过 HTML 网页加载的 JavaScript 和 TypeScript 库。你可以使用 SDK 在网页浏览器中调用 API 建立连接，控制音视频通话和直播服务。 :::info[信息] 本文仅适用于声网 Web SDK 4.x。这是基于 Web SDK 3.x 的全量重构版本，不向下兼容。声网已经停止维护 Web SDK 3.x 版本。建议你选择合适的时机，参考[迁移指南](/zh-CN/realtime-media/rtc/reference/migration-guide)从 3.x 及以下版本升级至 4.x 版本。 ::: ### 已知问题和兼容性 [#已知问题和兼容性] **浏览器兼容性说明** 为保证最佳的用户体验，声网强烈推荐使用桌面端 Google Chrome 浏览器[官方最新版本](https://www.google.com/intl/zh-CN/chrome/)。详见 [Web SDK 的浏览器兼容性](/zh-CN/realtime-media/rtc/reference/browser-compatibility)。 **Chrome 弃用和删除 Plan B 语义** 根据 [Google 官方说明](https://www.chromestatus.com/feature/5823036655665152)，Chrome 浏览器计划弃用和删除 WebRTC 中的 Plan B 语义。该改动影响声网 Web SDK 如下版本的使用和体验。如你使用下述版本的 Web SDK，请尽快升级至最新版本。 | Web SDK 版本 | 影响范围 | | :-----------------------------: | :----------------------------------------------------------- | | 2.5.0-2.9.0 和 3.0.0-3.6.1 | 在调用 `publish` 方法后再调用 `switchDevice` 方法，出现视频卡顿或无声问题。 | | 4.0.0-4.0.1 | `publish` 和 `subscribe` 方法不生效。 | ## v4.24.9 [#v4249] 该版本于 2026 年 10 月 13 日发布。 ### 新增特性 [#新增特性-45] #### 高分辨率屏幕共享 [#高分辨率屏幕共享] 该版本在 [`ScreenEncoderConfigurationPreset`](/zh-CN/api-reference/rtc/web/globals#screenencoderconfigurationpreset) 中新增 2K 和 4K 屏幕共享预设，支持 2560 × 1440 和 3840 × 2160 分辨率，以及 5、15、30 fps 帧率。新增预设如下： | 预设 | 分辨率 | 帧率 | | --- | --- | --- | | `1440p_1` | 2560 × 1440 | 5 fps | | `1440p`、`1440p_3` | 2560 × 1440 | 15 fps | | `1440p_2` | 2560 × 1440 | 30 fps | | `4k_1` | 3840 × 2160 | 5 fps | | `4k`、`4k_3` | 3840 × 2160 | 15 fps | | `4k_2` | 3840 × 2160 | 30 fps | ### 改进 [#改进-52] #### 首帧出图优化 [#首帧出图优化] - 该版本优化了连接建立和远端视频首帧流程，有助于缩短用户等待画面出现的时间。 ### 问题修复 [#问题修复-58] - 修复部分场景下视频双流的小流编码分辨率与配置不一致的问题。 ### API 变更 [#api-变更-24] #### 新增 [#新增-24] - `ScreenEncoderConfigurationPreset` 新增 `1440p`、`1440p_1`、`1440p_2`、`1440p_3`、`4k`、`4k_1`、`4k_2` 和 `4k_3`。 ## v4.24.8 [#v4248] 该版本于 2026 年 8 月 31 日发布，进行了一些内部改进。 ## v4.24.7 [#v4247] 该版本于 2026 年 8 月 3 日发布，进行了一些内部改进。 ## v4.24.6 [#v4246] 该版本于 2026 年 7 月 13 日发布。本版本新增远端音频自动接收和播放能力，并提升了 Safari、iOS 等环境下的音频播放及连接稳定性。 ### 新增特性 [#新增特性-46] #### 入会后自动接收并播放远端音频 [#入会后自动接收并播放远端音频] 该版本新增 `autoReceiveAndPlayAudio` 配置。开启后，用户加入频道时，SDK 会自动接收并尝试播放远端音频，减少入会后等待声音出现的时间。 该功能适用于语聊房、在线会议等需要入会后尽快听到声音的场景，直播观众端等默认需要接收频道内音频的场景，以及对远端音频首帧速度有较高要求的场景。 该功能默认关闭，不影响现有业务的订阅和播放逻辑。 ### 问题修复 [#问题修复-59] - 修复了部分 Safari 和 iOS 26 及以上版本中，音视频连接可能因兼容性问题出现异常的问题。 - 修复了使用 WebAudio 播放远端音频时，部分浏览器在自动播放受限后，用户完成交互仍可能无法恢复声音的问题。 ### 升级建议 [#升级建议] 如果你的业务使用 Safari 或 iOS 浏览器进行实时音视频通话，使用 WebAudio 播放远端音频且遇到自动播放受限后无法恢复声音的问题，或希望缩短用户入会后听到远端声音所需时间，建议升级至 v4.24.6。 :::info[信息] 受浏览器自动播放策略影响，页面首次播放音频时仍可能需要用户进行点击或触摸操作。 ::: ## v4.24.5 [#v4245] 该版本于 2026 年 6 月 24 日发布。 ### 升级必看 [#升级必看-35] #### 域名白名单变更 [#域名白名单变更] 自 v4.24.5 起，SDK 的域名白名单变更为： ``` *.agora.io *.edge.agora.io *.sd-rtn.com *.edge.sd-rtn.com *.rtnsvc.com *.edge.rtnsvc.com *.rtesvc.com *.edge.rtesvc.com ``` 为确保你在有网络访问限制的环境中能够使用声网产品，如果你将 SDK 升级至 v4.24.5，请务必更新防火墙的域名白名单。 ### 新增特性 [#新增特性-47] #### AI 降噪支持背景人声消除 [#ai-降噪支持背景人声消除] 该版本增强了 AI 降噪能力，支持背景人声消除。在嘈杂环境或多人发言场景下，该能力可以进一步突出目标人声，提升音频采集效果。 ### 改进 [#改进-53] #### 连通性与建连体验优化 [#连通性与建连体验优化] 该版本优化了信令流程，提升了会话建立阶段的处理效率以及复杂网络环境下的连接成功率。 #### 首帧与播放体验优化 [#首帧与播放体验优化] 该版本优化了音视频溯源相关链路和抖动缓冲区处理策略，有助于缩短首帧时间，减少特定场景下的音视频卡顿现象。 #### 订阅与自适应策略优化 [#订阅与自适应策略优化] 该版本优化了音频订阅流程，默认采用 presubscribe 模型，提升了订阅效率和播放稳定性；同时，在开启全链路反馈且使用保帧率模式时，为分辨率降档提供下限设置能力，便于更细粒度地平衡流畅度与画面清晰度。 ### 问题修复 [#问题修复-60] - 修复了部分场景下连接建立可能超时的问题，提升了连接稳定性。 - 修复了 string UID 用户离开频道后立即重新加入时，远端可能重复收到 `user-joined` 回调的问题。 - 修复了部分场景下 message 消息无法正常接收的问题。 - 修复了 Native 端发送 H.265 和 Metadata 后，Web 端可能无法正常接收的问题。 - 修复了 Safari 16.6 下部分场景本地画面可能黑屏或异常退出的问题。 - 修复了首次调用 `client.publish(video)` 后，远端视频可能短暂卡顿的问题。 - 修复了 npm 包中 TypeScript 类型定义文件缺失以及导出符号异常的问题。 ## v4.24.4 [#v4244] 该版本于 2026 年 5 月 27 日发布。 ### 改进 [#改进-54] 针对弱网场景进行了内部优化，提高了登录成功率。 ## v4.24.3 [#v4243] 该版本于 2026 年 3 月 27 日发布。 ### 新增特性 [#新增特性-48] #### AI 降噪插件低延迟模式 [#ai-降噪插件低延迟模式] AI 降噪插件 [agora-extension-ai-denoiser](https://www.npmjs.com/package/agora-extension-ai-denoiser) 升级至 v2.0.1 版本，新增低延迟模式和设置 WASM 模块的日志等级等特性，详见 [AI 降噪插件发版说明](/zh-CN/realtime-media/rtc/build/extensions/web/release#ai-降噪插件)。 ### 改进 [#改进-55] 该版本进行了以下改进： - 该版本优化了 H.264 编码场景下的视频互动体验。 - AI 画质插件升级至 v2.0.1 版本，优化了锐化算法，提升了部分场景下的视频体验。
## v4.24.2 [#v4242] 该版本于 2025 年 12 月 12 日发布，修复了一个由于 Chrome 浏览器升级（自 Chrome 143 起）引入的兼容性问题。 :::info[信息] Chrome 已于 2025 年 12 月 18 日修复了该问题。 ::: #### 问题表现 [#问题表现] A、B 正常互通过程中，A 先取消发布和订阅音频流，然后重新开始发布音频流时，会出现 `Session error code: ERROR_CONTENT` 的报错信息。 由于这是浏览器侧破坏式的改动，该问题会影响**所有版本的 RTC Web SDK**。 相关问题可参考 Chromium Bug Report：https://issues.chromium.org/issues/467468926 。 #### 解决办法 [#解决办法] 为避免该问题影响用户，我们在该版本 SDK 中进行了兼容性处理，确保在 Chrome 官方修复前，重新推流和重新订阅流程能够正常运行。同时，声网研发团队已将问题同步至 Chrome 团队。 最新进展：Chrome 已于 2025 年 12 月 18 日修复该问题。
## v4.24.1 [#v4241] 该版本于 2025 年 11 月 25 日发布。 ### 新增特性 [#新增特性-49] #### 通话前网络质量探测 [#通话前网络质量探测] 在通话前进行网络质量探测，可以有效帮助本地用户判断和预测上行网络质量是否良好。该版本新增 [`startLastmileProbeTest`](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#startlastmileprobetest) 接口，向用户反馈开始通话前上下行网络的丢包、网络抖动和往返时延数据。 #### 双流模式 [#双流模式-3] 该版本新增 [`setDualStreamMode`](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#setdualstreammode) 方法，扩展了订阅视频双流的实现方式。你可以通过将该方法的 `mode` 参数设为 `AUTO_SIMULCAST_MODE`，在发送端开启小流自适应模式（即默认不主动发送小流），然后通过以下步骤实现发送小流： - 接收端主播调用 `setRemoteVideoStreamType` 发起接收小流申请。 - 发送端收到申请后自动切换为发送小流模式。 此外，你还可以将 `mode` 参数设置为 `DISABLE_SIMULCAST_STREAM`（始终不发送小流）或 `ENABLE_SIMULCAST_STREAM`（始终发送小流）。 该方法和已有的 `enableDualStream` 和 `disableDualStream` 之间的关系详见 [API 参考](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#setdualstreammode)。为确保集成逻辑清晰，我们建议你选取一套 API 进行集成。声网规划在后续版本中逐渐废弃 `enableDualStream` 和 `disableDualStream`。 #### 水印插件 (BETA) [#水印插件-beta] 该版本新增发布水印插件 (BETA) [agora-extension-video-watermark](https://www.npmjs.com/package/agora-extension-video-watermark) v1.0.0，支持通过插件的方式向实时互动的视频流中添加图像水印。 水印插件支持自定义水印的位置、大小、透明度等属性，可应用于本地和远端的视频轨道。相关集成和使用步骤可以参考[使用水印插件 (BETA)](/zh-CN/realtime-media/rtc/build/extensions/web/watermark)。 #### 其他新增特性 [#其他新增特性] - 支持 H265 解码。支持的浏览器版本及使用限制详见 [API 参考](/zh-CN/api-reference/rtc/web/globals#sdk_codec)。 ### 改进 [#改进-56] #### 屏幕共享能力拓展 [#屏幕共享能力拓展] 该版本进一步拓展了屏幕共享的能力，在 `createScreenVideoTrack` 接口中通过如下参数，支持屏幕共享时共享音频等功能： - [`ScreenVideoTrackInitConfig`](/zh-CN/api-reference/rtc/web/interfaces/screenvideotrackinitconfig) 中新增 `windowAudio` 和 `monitorTypeSurfaces`，分别设置是否允许分享窗口音频和是否允许分享整个屏幕。 - [`ScreenAudioTrackInitConfig`](/zh-CN/api-reference/rtc/web/globals#screenaudiotrackinitconfig) 中新增 `suppressLocalAudioPlayback` 和 `restrictOwnAudio`，设置是否允许本地播放和采集音频。 :::info[信息] 在有屏幕共享的连麦场景中，我们不建议分享系统或者窗口音频，否则可能会产生类似回声的问题。你可以通过将 `ScreenVideoTrackInitConfig` 中的 `windowAudio` 和 `systemAudio` 均设为 `false` 来停止共享音频。 ::: #### AI 画质插件升级 [#ai-画质插件升级] 该版本对 AI 画质插件 [agora-extension-super-clarity](https://www.npmjs.com/package/agora-extension-super-clarity) 的算法进行了升级，在减小插件体积、提升视频体验、扩展浏览器兼容性等方面均有改进。新版本的插件需要在支持 SIMD 的浏览器中才能正常运行。具体变更及改进点可以参考 [AI 画质插件发版说明](/zh-CN/realtime-media/rtc/build/extensions/web/release#ai-画质插件)。 ### 问题修复 [#问题修复-61] 修复了 iOS 系统上，音频流销毁后，系统音量无法设置为 0 的问题。
## v4.24.0 [#v4240] 该版本于 2025 年 7 月 31 日发布。 ### 新增特性 [#新增特性-50] #### 快速首帧出图 [#快速首帧出图] 为降低用户等待主播视频首帧渲染出图的时间，该版本在 `join` 方法中新增参数 `options`，用来设置加入频道选项。通过将 [`IJoinOptions`](/zh-CN/api-reference/rtc/web/interfaces/ijoinoptions) 中的 `autoSubscribe` 设为 `true`，可以设置用户加入频道时即自动订阅频道中主播的媒体流。 在一对一、一对多等实时互动场景中，该功能可以有效降低首帧出图时间，提高互动体验。更多适用场景和最佳实践可以参考[频道秒开](/zh-CN/realtime-media/rtc/build/optimize-and-operate/preload)。参考最佳实践集成后，在 Windows 和 macOS 端 Chrome 浏览器上，首帧出图时间最低可降至 300 毫秒以内。 :::warning[注意] 如果设置自动订阅主播的媒体流，声网后台会在用户加入频道时就开始下发媒体流，并开始计费。 ::: ### 改进 [#改进-57] #### 弱网传输体验优化 [#弱网传输体验优化] 该版本优化了带宽估计算法，实现音频优先传输。有效降低极限弱网下视频卡顿风险；同时提升了弱网环境下大小流的切换流畅度，切换更平滑；网络恢复后的连接响应也更加灵敏。 #### 新的媒体建连策略 [#新的媒体建连策略] 该版本通过新的媒体建连策略，提升了在企业网络以及受限网络下 SDK 的重连和媒体登陆成功率。 #### 网络质量评估更精确 [#网络质量评估更精确] 该版本在网络质量评估 [`NetworkQuality`](/zh-CN/api-reference/rtc/web/interfaces/networkquality) 的算法中，增加了可用宽带作为参考，可以更准确地体现出 SDK 是否受到限宽网络条件的影响。 该改进需要通过私有参数开启，如果需要，可以联系[技术支持](https://ticket.shengwang.cn/)。 #### 其他改进 [#其他改进-25] - 优化了不同视频编码标准下的默认视频码率，通过合理分配网络上行码率，从而降低了弱网卡顿率。 - 完善了设备在不支持 AV1 解码情况下的回退机制。 - 改进了 Web 和 Web 互通、Web 和 Native 互通时 `rtc` 模式下，1v1 场景中的用户对话体验。 ### 问题修复 [#问题修复-62] - 修复了 Firefox 138+ 上因浏览器自身版本回退导致的接收端可能出现的黑屏问题。 - 对 Safari 18.4 和 18.5 上因浏览器本身的问题导致的卡顿进行了兼容性修复。 - 修复了分辨率过低时出现的编码失败的问题。 - 修复了使用 Plan-B 场景下偶现的黑屏问题。
## v4.23.4 [#v4234] 该版本于 2025 年 6 月 5 日发布。 v4.23.4 进行了一些内部改进，修复了特定场景下调用 `setMute` 或 `setEnable` 方法时，可能出现无声的问题。如果你使用的是 v4.23.0 及之后版本的 SDK，我们建议你升级到该版本，以获得更好的用户体验。 ## v4.23.3 [#v4233] 该版本于 2025 年 4 月 30 日发布。 v4.23.3 将虚拟背景插件升级到了 [2.1.0 版本](https://www.npmjs.com/package/agora-extension-virtual-background)，包含如下改动： - 优化了内存及 CPU 开销。 - 修复了特定分辨率时产生的黑屏问题。 ## v4.23.2 [#v4232] 该版本于 2025 年 3 月 5 日发布，主要包含以下改进： - 为支持[声网对话式 AI 引擎](/zh-CN/ai)作了一些内部改进。 - 进一步缩小了包体积。 ## v4.23.1 [#v4231] 该版本于 2025 年 1 月 16 日发布，进行了一些内部改进。 ## v4.23.0 [#v4230] 该版本于 2024 年 12 月 19 日发布。 ### 升级必看 [#升级必看-36] 为提升 SDK 可用性，该版本修改了 `RemoteVideoTrackStats` 中 [`freezeRate`](/zh-CN/api-reference/rtc/web/interfaces/remotevideotrackstats#freezerate) 的计算方式，由累计的平均卡顿率改为最近一秒的卡顿率。你可以使用该参数来判断视频是否存在瞬时卡顿。如果需要统计当前会话的累计平均卡顿率，可以使用 [`totalFreezeTime`](/zh-CN/api-reference/rtc/web/interfaces/remotevideotrackstats#totalfreezetime) / [`totalDuration`](/zh-CN/api-reference/rtc/web/interfaces/remotevideotrackstats#totalduration) 来进行计算。 ### 新增特性 [#新增特性-51] #### 本地媒体 PeerConnection 连接状态回调 [#本地媒体-peerconnection-连接状态回调] 在某些受限网络条件下，为获取媒体连接的实时状态变化，该版本新增 [`"peerconnection-state-change"`](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#event_peerconnection_state_change) 事件，用来获取 WebRTC [RTCPeerConnection](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection) 的连接状态。 #### 默认共享当前页面 [#默认共享当前页面] 为提升屏幕共享易用性，该版本在 `ScreenVideoTrackInitConfig` 中添加 [`preferCurrentTab`](/zh-CN/api-reference/rtc/web/interfaces/screenvideotrackinitconfig#prefercurrenttab) 参数，支持创建屏幕共享轨道时设置默认共享当前页面。 ### 改进 [#改进-58] #### 媒体重连策略改进 [#媒体重连策略改进] 该版本对媒体重连策略进行了改进，提升了弱网情况下 SDK 的重连和媒体登录成功率，对于部署了防火墙的企业网络提升尤为明显。如果希望应用该改进，请[联系技术支持](https://ticket.shengwang.cn/)开通。 #### 升级虚拟背景算法 [#升级虚拟背景算法] 该版本将虚拟背景算法升级到 2.0.0 版本。[虚拟背景插件 2.0.0](https://www.npmjs.com/package/agora-extension-virtual-background/v/2.0.0) 对人像算法进行全面升级，提供更加分明的人像边缘以及更加清晰稳定的视频画面。 #### 优化包体积 [#优化包体积] 为进一步减小包体积，该版本将 ESM-bundle 格式包中的兼容 WebRTC 中的 Plan-B 功能拆分成了独立的服务模块。用户可根据实际需求，手动导入进行集成。集成方式详见[使用 Tree shaking](/zh-CN/realtime-media/rtc/build/optimize-and-operate/tree-shaking)。 #### 其他改进 [#其他改进-26] - 优化了复杂网络场景下的登录时长。 - 优化了 VP9 的切层算法，能够降低延时、提升视频流畅度。 :::warning[注意] Safari 浏览器不支持 VP9 SVC。 ::: ### 问题修复 [#问题修复-63] 该版本修复了如下问题： - 特定场景下调用 `setMute` 和 `setEnable` 时可能出现黑屏。 - 断网重连之后，偶现音视频流发送失败。 - 128 人场景下，角色为观众（`audience`）的用户可以发流。 ### API 变更 [#api-变更-25] #### 新增 [#新增-25] - `AgoraRTC.on("peer-connection-state-change")` - `ScreenVideoTrackInitConfig` 中新增 `preferCurrentTab` 参数 ## v4.22.2 [#v4222] 该版本于 2024 年 10 月 28 日发布。 ### 新增特性 [#新增特性-52] #### 屏幕共享音频 3A 处理 [#屏幕共享音频-3a-处理] 自该版本起，调用 `createScreenVideoTrack` 方法创建屏幕共享视频轨道时，`withAudio` 参数支持传入 `ScreenAudioTrackInitConfig`，用于自定义音频共享的初始化配置。你可以根据使用场景，按需启用 3A 处理（自动增益、回声消除和噪声抑制），以优化共享音频质量。详见 [API 文档](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#createscreenvideotrack)。 :::warning[注意] 如果你的浏览器不支持共享音频，即使传入 `ScreenAudioTrackInitconfig` 也只会返回视频轨道。 ::: ### API 变更 [#api-变更-26] #### 新增 [#新增-26] - `createScreenVideoTrack` 方法中的 `withAudio` 参数支持传入 `ScreenAudioTrackInitconfig` ## v4.22.1 [#v4221] 该版本于 2024 年 9 月 19 日发布，进行了一些内部改进。
## v4.22.0 [#v4220] 该版本于 2024 年 8 月 15 日发布。 ### 升级必看 [#升级必看-37] 为进一步减小包体积，该版本将 ESM-bundle 格式包中的跨频道连麦、旁路推流、实时审核（鉴黄）等功能拆分成了独立的服务模块。用户可根据实际需求，手动导入进行集成。集成方式详见[使用 Tree shaking](/zh-CN/realtime-media/rtc/build/optimize-and-operate/tree-shaking)。 ### 新增特性 [#新增特性-53] #### 适配 HarmonyOS NEXT [#适配-harmonyos-next] 经过测试确认，该版本 SDK 支持使用 HarmonyOS NEXT 华为浏览器实现音视频推拉流。具体兼容性说明，见[浏览器兼容性和已知问题](/zh-CN/realtime-media/rtc/reference/browser-compatibility#移动端)。 #### 优化频道秒开 [#优化频道秒开] 使用频道秒开功能时，为减少首帧渲染时间，我们建议在调用加入频道方法时立即下发主播的媒体流，详见[频道秒开](/zh-CN/realtime-media/rtc/build/optimize-and-operate/preload#22-进入频道)。该设置下，用户一加入频道就会产生拉流，从而产生计费，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy#基础服务)。 #### 支持 AV1 编码 (Beta) [#支持-av1-编码-beta] SDK 新增了对 AV1 视频编码格式的支持。你可以通过设置 `ClientConfig.codec` 为 `av1` 来启用该编码格式。与同等码率的 H.264 相比，AV1 编码效率提升超过 30%，并且提供更佳的视频画质。 ### 改进 [#改进-59] 该版本有以下改进： - 优化了 VP9 编解码的 SVC（可伸缩视频编码）功能，进一步提升了视频质量和传输效率。 - 优化了 VAD（语音活动检测），新增音乐检测功能，提升了人声检测的准确率。 ### 问题修复 [#问题修复-64] 该版本修复了以下问题： - 修复了部分场景下 Safari 获取 `stats` 失败的问题。 - 修复了部分场景下弱网码率设置不准的问题。 ### API 变更 [#api-变更-27] 该版本新增以下 API: - `AgoraRTCClient.getRemoteAudioStats` 新增 `receivePacketsDiscarded` 返回字段 - `ClientConfig.codec` 新增 `av1` 枚举值 - ESM-bundle 格式包中的 `AgoraRTC` 新增 `use` 方法
## v4.21.0 [#v4210] 该版本于 2024 年 6 月 3 日发布。 ### 升级必看 [#升级必看-38] 该版本 SDK 引入视频质量控制模块 (Video Quality Control, VQC)。`ICameraVideoTrack` 默认开启 `"motion"`（流畅优先）模式，以保障在低带宽、高 CPU 占用的情形下视频的流畅性，进一步提升用户体验。你可以根据需求调用 [`setOptimizationMode`](/zh-CN/api-reference/rtc/web/interfaces/cameravideotrackinitconfig#optimizationmode) 方法来动态调整视频的传输模式。 ### 新增特性 [#新增特性-54] #### 预加载频道 [#预加载频道-3] 该版本新增 [`AgoraRTC.preload`](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#preload) 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。关于预加载频道的最佳实践，详见[频道秒开](/zh-CN/realtime-media/rtc/build/optimize-and-operate/preload)。 ### 改进 [#改进-60] 该版本有以下改进： - 优化了带宽估计算法和发送端的弱网拥塞控制算法，从而有效降低了弱网条件下发送端的卡顿率。 - 优化了 SDK 浏览器兼容性检测范围，解决了部分设备上浏览器兼容性检测不准确的问题。 - 增加了对部分阿里系 App（如支付宝、钉钉等）的兼容，你可以直接在这些 App 中收发音视频流。 - 为了优化 Safari 17.4 以下版本浏览器的用户体验，补充了视频质量自适应算法，提升了在网络带宽受限情况下的视频质量自适应能力，进一步确保视频流的流畅性。 ### 问题修复 [#问题修复-65] 该版本修复了以下问题： - 部分安卓设备上 `isPlaying` 返回的视频播放状态不准确。 - 移动端 Safari 上，调用 `getLocalVideoStats` 方法返回的本地视频轨道的分辨率信息不准确；调用 `setLowStreamParameter` 设置的小流分辨率不生效。 ### API 变更 [#api-变更-28] 该版本新增以下 API: - `AgoraRTC.preload` ## v4.20.2 [#v4202] 该版本于 2024 年 3 月 20 日发布。 该版本修复了在某些场景下调用 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#createcustomvideotrack) 方法，出现采集的视频分辨率被浏览器修改的问题。 ## v4.20.1 [#v4201] 该版本于 2024 年 2 月 26 日发布。 ### 新增特性 [#新增特性-55] #### 发送 SEI 信息 [#发送-sei-信息] 为了实现在 H.264 视频流中添加和发送 SEI 信息，该版本新增 `LocalVideoTrack.sendSeiData` 方法和 `RemoteVideoTrack.on("sei-received")` 事件。其中，SEI 信息包括动态面部捕捉数据、虚拟视频信息及数字水印等，该信息包的大小限制为 1 KB。在使用之前，你需要通过参数 `AgoraRTC.setParameter("ENABLE_VIDEO_SEI", true)` 启用该功能。 :::warning[注意] - SEI 信息发送功能仅在 Chrome 87 及以上或 Safari 15.4 及以上版本支持。由于该功能的实现依赖于浏览器的支持情况，我们更推荐你使用 Native 端发送或接收 SEI 信息。 - 由于浏览器基础组件冲突，SEI 信息发送不支持与[端到端媒体加密 (Beta)](/zh-CN/realtime-media/rtc/build/security-and-auth/e2e-encryption) 功能同时开启。 ::: #### 监控接收端视频状态 [#监控接收端视频状态] 自该版本起，新增了 `"video-state-changed"` 事件来监控 Web 端视频卡顿和恢复状况，以便应用层及时采取相应的处理措施。详见 [API 文档](/zh-CN/api-reference/rtc/web/interfaces/iremotevideotrack#on)。 #### 数据流加密 [#数据流加密-3] 为提升数据流传输的安全性，该版本在 `setEncryptionConfig` 方法中新增 `encryptDataStream`参数，用于开启数据流加密。详见[`AgoraRTCClient.setEncryptionConfig`](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#setencryptionconfig)。 ### 改进 [#改进-61] 该版本有以下改进： - 优化了移动端音频发流体验，单路音频场景下减少了因为浏览器缺陷导致的电流声、无声问题。 - 新增最低视频码率的默认设置，优化了视频码率设置。如果你在调用 `setEncoderConfiguration` 时没有设置 `bitrateMin` 的值，SDK 会根据已设置的分辨率和帧率为你设置一个合适的码率。该默认设置仅在 Chrome 和 Edge 上生效。 ### 问题修复 [#问题修复-66] 该版本修复了以下问题： - 单频道 128 位主播场景下，如果有用户在网络重连过程中离开频道，会导致本地用户订阅其他远端用户的音频流失败。 ### API 变更 [#api-变更-29] 该版本新增以下 API: - `LocalVideoTrack.sendSeiData` - `RemoteVideoTrack.on("sei-received")` - `RemoteVideoTrack.on("video-state-changed")` - `AgoraRTCClient.setEncryptionConfig` 中新增 `encryptDataStream` 参数
## v4.20.0 [#v4200] 该版本于 2023 年 12 月 8 日发布。 ### 升级必看 [#升级必看-39] 在 4.20.0 之前的版本中，你可以在 Firefox 上调用 `IRemoteAudioTrack.setPlaybackDevice` 方法，但由于 Firefox 存在 [Bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1849108)，会出现回声问题。为保障体验，SDK 自 4.20.0 起进行了限制，在 Firefox 上调用该方法会抛出 `NOT_SUPPORTED` 错误。 如果你使用了 `IRemoteAudioTrack.setPlaybackDevice` 方法，升级至该版本后请修改相关代码。 ### 新增特性 [#新增特性-56] 在某些版本的 iOS 设备上，App 通话被微信通话或系统电话打断后有概率无法自动恢复。为解决这一问题，该版本新增 `"audio-context-state-changed"` 事件用于监听 App 通话是否被打断，并且新增 `resumeAudioContext` 方法用于恢复通话。使用方法详见 [API 文档](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#resumeaudiocontext)。 ### 改进 [#改进-62] 该版本有以下改进： - 缩短了使用 String 型 UID 加入频道的时间。 - ChromeOS 平台上支持在共享整个屏幕和共享 Chrome 标签页时分享音频。 ### API 变更 [#api-变更-30] #### 新增 [#新增-27] - `resumeAudioContext` - `AgoraRTC.on("audio-context-state-changed")`
## v4.19.3 [#v4193] 该版本于 2023 年 11 月 2 日发布。 该版本修复了在低于 Safari 16 的版本上接收 H.264 编码视频流出现黑屏的问题：集成 4.19.2 版本 Web SDK 的客户端与集成声网 Native（包括 Android、iOS、Windows 和 macOS 平台）SDK 的客户端进行音视频通话时，如果 Native 客户端使用 H.264 编码发送视频流，低于 Safari 16 的 Web 客户端会出现黑屏。 如果你集成了 4.19.2 版本的 SDK，声网推荐你尽快升级到 4.19.3 版本。 ## v4.19.2 [#v4192] 该版本于 2023 年 10 月 20 日发布。 ### 改进 [#改进-63] #### VP9 编解码 [#vp9-编解码] 测试结果显示，在码率相同的条件下，VP9 的画质可以达到 VP8 的两倍。该版本将 VP9 编解码由 Beta 发布转为正式发布，并且进行了以下优化： - 更新浏览器兼容性：桌面端和移动端均支持 Safari 16.0 及以上版本。 - 在低版本的浏览器上支持自动回退到 VP8：只要频道内有一位用户的浏览器版本低于[兼容性表格](#vp9)列出的版本，该频道内所有以 VP9 编解码的视频都会回退到以 VP8 编解码。 #### Safari 动态调整编码分辨率 [#safari-动态调整编码分辨率] Safari 存在已知问题，不能在网络条件较差或者视频发送帧率下降时自动降低视频编码分辨率，因此可能导致视频画面模糊。为保障用户体验，该版本在视频属性预设值中新增 `"720p_auto"`，用于确保在 Safari 上能够动态调整视频编码分辨率。 升级到该版本后，如果你当前使用的视频属性为 720p，声网推荐你改用 `"720p_auto"` 并且将编码格式设为 `"vp9"`，以取得最佳效果。 ### API 变更 [#api-变更-31] #### 新增 [#新增-28] - `VideoEncoderConfigurationPreset` 中新增 `"720p_auto"` ## v4.19.1 [#v4191] 该版本于 2023 年 10 月 11 日发布。 该版本修复了使用 Webpack 4.x 对 SDK 二次打包导致运行出错的问题。二次打包指将 SDK 集成到 App 后再对 App 进行打包。 ## v4.19.0 [#v4190] 该版本于 2023 年 9 月 22 日发布。 :::warning[注意] 在 App 中集成该版本的 SDK 后，使用 Webpack 4.x 对 App 打包会出现错误。你可以通过以下方式解决该问题： - 如果你需要使用 Webpack 4.x 打包 App，请将 SDK 升级到 4.19.1 版本。 - 如果你想继续使用 4.19.0 版本的 SDK，声网推荐你使用 Webpack 5.x 或其它主流工具（比如 Vite）打包。 ::: ### 升级必看 [#升级必看-40] #### 动态调整小流视频属性 [#动态调整小流视频属性] 在 4.19.0 之前的版本中，你必须在 `publish` 之前调用 `setLowStreamParameter` 来设置小流视频属性。如果需要在发流后更改小流视频属性，则必须重新发布视频流，导致接收端的视频体验受到影响。 为提升接收端的视频体验，自该版本起，你可以在 `publish` 之后调用 `setLowStreamParameter`，实现在发流后动态调整小流分辨率、码率和帧率。声网推荐你在升级至该版本后根据需要修改 `setLowStreamParameter` 的调用时序。例如在直播、视频会议等场景中，随着频道中的发流人数增加，你可以动态调整小流视频属性来减轻带宽压力。 ### 新增特性 [#新增特性-57] #### 端到端媒体加密 (Beta) [#端到端媒体加密-beta] 在数据安全要求较高的场景下，除了使用[媒体流加密](/zh-CN/realtime-media/rtc/build/advanced-channel/channel-encryption)功能，你还可以使用该版本新增的端到端加密功能，实现在发送端设备上对媒体流进行加密、在接收端设备上对媒体流进行解密，确保数据不会在传输过程中被其它第三方获取。如需开通端到端加密功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### Tree shaking（摇树优化） [#tree-shaking摇树优化] 自该版本起，SDK 包支持 [Tree shaking](https://webpack.js.org/guides/tree-shaking/)，能够在构建过程中移除未引用的代码，从而减小集成 SDK 后的 App 体积。如需使用该功能，请确保通过 npm 集成 SDK 并且使用正确的导入 (`import`) 方式。详见[使用 Tree shaking](/zh-CN/realtime-media/rtc/build/optimize-and-operate/tree-shaking)。 #### 同一视频流两路显示 [#同一视频流两路显示] 该版本新增 `clone` 方法，用于复制当前的摄像头或屏幕共享视频轨道并设置显示参数。在视频会议、在线教育等场景中，你可以用该方法实现同一视频流的两路显示，并为每路显示设置不同的分辨率、帧率、码率等参数。例如，你可以将同一视频流以一路高分辨率、一路低分辨率同时展示在界面上。 #### 切换前置和后置摄像头 [#切换前置和后置摄像头] 为方便在移动端切换摄像头，该版本在 `ICameraVideoTrack.setDevice` 方法中新增 `facingMode` 参数，用于指定使用手机的前置或后置摄像头。详见 [`ICameraVideoTrack.setDevice`](/zh-CN/api-reference/rtc/web/interfaces/icameravideotrack#setdevice)。 #### AI 画质插件 (Beta) [#ai-画质插件-beta] 自该版本起，SDK 可以与 AI 画质插件搭配使用，在不改变分辨率的条件下智能提升视频画质，优化观看体验。详见[使用 AI 画质插件](/zh-CN/realtime-media/rtc/build/extensions/web/super-clarity)。 #### 第三方视频审核 [#第三方视频审核] 自该版本起，SDK 支持接入第三方视频审核服务。详见 [`setImageModeration`](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#setimagemoderation)。 ### 改进 [#改进-64] #### 优化自动模式 [#优化自动模式] 在自动模式下，SDK 优先连接 SD-RTN™ ，如果连接失败，会自动切换到 TCP/TLS 443。为提高网络受限环境下的接入体验，该版本优化了 SDK 的自动模式，提升了连接速度和稳定性。由于优化后的自动模式不再使用代理，该版本废弃了 `AgoraRTCClient.on("join-fallback-to-proxy")` 回调。 #### 其他改进 [#其他改进-27] 该版本还有以下改进： - 缩短了首帧出图时间。如需启用，请[联系技术支持](https://ticket.shengwang.cn/)。 - 在 `AgoraRTCClient.on("connection-state-change")` 回调报告的 SDK 断开连接原因中新增 token 过期导致用户离开频道，方便问题排查和调试。 - 在本地音频轨道的质量信息中增加 `sendJitterMs` 和 `sendRttMs`，分别报告发送数据包的抖动 (ms) 和往返时延 (ms)。 ### 问题修复 [#问题修复-67] 该版本修复了以下问题： - 正常网络环境下，SDK 在加入频道后的前几秒内偶现对上行网络质量的误报，即返回 `NetworkQuality.uplinkNetworkQuality` 为 `5`。 - SDK 统计的本地音频、视频丢包率以及远端音频、视频丢包率 （均为 `currentPacketLossRate` 属性） 不准确。 - 在 Windows 设备的 Chrome 115 浏览器上，如果本地用户分享的屏幕画面保持静止并且画面上没有鼠标移动，屏幕共享流会停止发送。 - 在订阅远端媒体流的过程中，如果远端用户重新发布音频流，本地用户接收到的音频偶现无声；如果远端用户重新发布视频流，本地用户接收到的视频偶现黑屏。 - 调用 `IBufferSourceAudioTrack.close` 后内存没有及时释放。 ### API 变更 [#api-变更-32] #### 新增 [#新增-29] - `ICameraVideoTrack.clone` 和 `ILocalVideoTrack.clone` 方法 - `setDevice` 中新增 `facingMode` 参数 - `ConnectionDisconnectedReason` 枚举中新增 `TOKEN_EXPIRE` - `setImageModeration` - `AgoraRTCClient.on("image-moderation-connection-state-change")` - `ImageModerationConfiguration` - `ImageModerationConnectionState` - `LocalAudioTrackStats` 中新增 `sendJitterMs` 和 `sendRttMs` - `LocalVideoTrackStats` 中新增 `sendJitterMs` 和 `sendRttMs` - `getRTCRtpTransceiver` - `AgoraRTCClient.on("transceiver-updated")` #### 废弃 [#废弃-13] - `AgoraRTCClient.on("join-fallback-to-proxy")` ## v4.18.3 [#v4183] 该版本于 2023 年 9 月 20 日发布。 该版本修复了 SDK 在 Safari 17 上音视频统计数据缺失的问题。 ## v4.18.2 [#v4182] 该版本于 2023 年 7 月 11 日发布。 该版本修复了 SDK 加载完成后，在特定情况下触发麦克风和摄像头设备权限申请弹窗的问题。 ## v4.18.1 [#v4181] 该版本于 2023 年 7 月 7 日发布。 ### 改进 [#改进-65] #### 事件监听支持错误处理 [#事件监听支持错误处理] 自该版本起，如果你在事件监听器 (`listener`) 中传入的回调函数在执行时发生错误，SDK 不会中断正常运行，而是捕获异常并在日志中输出错误信息。 #### 优化异步方法的并发控制 [#优化异步方法的并发控制] 该版本优化了异步方法的并发控制。如果以下异步方法出现并发执行的情况，SDK 会按照方法被调用的顺序依次执行，保证一致性： - `join` 和 `leave` - `publish` 和 `unpublish` - `subscribe` 和 `unsubscribe` 以 `publish` 和 `unpublish` 为例，如果你在调用 `publish` 之后立即调用 `unpublish`： - 在 4.18.1 之前， `unpublish` 有可能不生效，即仍然发布成功。 - 自 4.18.1 起，实际结果与你的调用顺序保持一致，即不会发布成功。 ### 问题修复 [#问题修复-68] 该版本修复了在不具备任何可用摄像头或麦克风的设备上，第一次插入外接摄像头或外接麦克风不会触发以下回调的问题： - `onCameraChanged` 或 `AgoraRTC.on("camera-changed")` - `onMicrophoneChanged` 或 `AgoraRTC.on("microphone-changed")` ## v4.18.0 [#v4180] 该版本于 2023 年 6 月 21 日发布。 ### 新增特性 [#新增特性-58] #### 可伸缩视频编码 (Beta) [#可伸缩视频编码-beta] 自 v4.18.0 起，SDK 支持在使用 [VP9 编解码](#vp9)时开启 SVC（可伸缩视频编码）。SVC 功能可以根据用户的网络环境和设备性能自适应调节视频流的编码质量，保证所有用户的观看体验。 如需开启 SVC 功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 获取已编码数据 (Beta) [#获取已编码数据-beta] 自 v4.18.0 起，你可以获取到 SDK 已编码的音频和视频数据。如需开启该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 提升网络受限环境下的连接体验 (Beta) [#提升网络受限环境下的连接体验-beta] v4.18.0 支持新的媒体建连策略，可以优化在网络受限环境下的连接体验。如需开启该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 倍速播放音频文件 [#倍速播放音频文件] 为方便在播放音效或音乐文件时调节当前文件的播放速度，v4.18.0 对 `IBufferSourceAudioTrack` 类做了以下修改： - 新增 `setAudioBufferPlaybackSpeed` 方法。在加入频道前和加入频道后，你都可以调用该方法。 - 新增 `playbackSpeed` 属性，用于获取当前的播放速度。 #### 自定义信令代理 [#自定义信令代理] 在使用声网混合云或私有化平台相关服务时，为方便你自定义 SDK 使用的信令代理服务器，v4.18.0 新增 `setProxyServer` 方法。 #### 灵活监听 AgoraRTC 对象的事件 [#灵活监听-agorartc-对象的事件] 自 v4.18.0 起，`IAgoraRTC` 类继承 EventEmitter 类的所有方法，用于监听 `AgoraRTC` 对象的所有事件。 以 `onCameraChanged` 为例： ```javascript // v4.18.0 以前的监听方式 AgoraRTC.onCameraChanged = (info) => { console.log("camera changed!", info.state, info.device); }; // v4.18.0 及以上版本新支持的监听方式 AgoraRTC.on("camera-changed", (info) => { console.log("Camera changed!", info.state, info.device); }); ``` 你可以继续沿用以前的监听方式，但如果你需要更高的灵活性和可拓展性，声网推荐你在升级 SDK 后修改以下事件的监听方式： - `onAutoplayFailed` - `onCameraChanged` - `onMicrophoneChanged` - `onPlaybackDeviceChanged` - `onSecurityPolicyViolation` - `onAudioAutoplayFailed` （已废弃，请改用 `onAutoplayFailed`） ### 改进 [#改进-66] #### 缩短加入频道耗时 [#缩短加入频道耗时] 自 v4.18.0 起，SDK 默认开启 WebSocket 消息压缩，可以缩短用户在弱网环境下加入频道的耗时。 #### 其他改进 [#其他改进-28] 该版本还有以下改进： - 缩短了弱网环境下从视频小流切换到视频大流的耗时。 - 升级了云代理服务以提升在不同网络环境下的稳定性。 ### 问题修复 [#问题修复-69] v4.18.0 修复了以下问题： - 开启消息通知服务后，移动端收到的主播离开频道事件通知（[`104 broadcaster leave channel`](/zh-CN/api-reference/rtc/restful/webhook/events#104-broadcaster-leave-channel)）可能出现延迟的问题。 - 在部分旧版本浏览器上，观看使用 H.264 编码的视频流出现黑屏的问题。 - SDK 和虚拟背景插件或美颜插件一起使用时，内存明显上涨的问题。 - 调用 `renewToken` 方法生成新的 Token 后，SDK 在尝试重连时依然使用已过期的 Token 加入频道的问题。 ### API 变更 [#api-变更-33] #### 新增 [#新增-30] - `setProxyServer` - `IBufferSourceAudioTrack` 中新增 `setAudioBufferPlaybackSpeed` 方法和 `playbackSpeed` 属性 - `IAgoraRTC` 类中新增以下继承自 `EventEmitter` 类的方法： - `on` - `off` - `once` - `getListeners` - `removeAllListeners` :::info[信息] 这些方法支持传入的事件名称如下： - `"camera-changed"` - `"microphone-changed"` - `"playback-device-changed"` - `"autoplay-failed"` - `"security-policy-violation"` ::: ## v4.17.2 [#v4172] 该版本于 2023 年 4 月 19 日发布。 该版本修复了 `getCurrentFrameData` 方法返回值异常的问题。 ## v4.17.1 [#v4171] 该版本于 2023 年 4 月 19 日发布。 ### 升级必看 [#升级必看-41] :::warning[注意] 在 Chrome 107 上进行屏幕共享时，默认不能共享当前标签页。如果你需要允许用户在 Chrome 107 及以上版本共享当前标签页，请尽快升级 SDK 至 4.17.1 或以上版本。 ::: 为兼容 Chrome 107 的屏幕共享相关改动（详见[官方说明](https://developer.chrome.com/docs/web-platform/screen-sharing-controls/)），该版本对 `createScreenVideoTrack` 方法中的 `config` 参数做了以下修改： - 废弃 `screenSourceType` 属性。如果你使用了该属性，升级到该版本后请改用新增的 `displaySurface` 属性。 - 新增 `selfBrowserSurface`、`surfaceSwitching` 和 `systemAudio` 属性。 以上属性的详细说明参考 [`ScreenVideoTrackInitConfig`](/zh-CN/api-reference/rtc/web/interfaces/screenvideotrackinitconfig)。 ### 改进 [#改进-67] #### 提高设置视频属性的灵活性 [#提高设置视频属性的灵活性] 该版本提高了对不同类型视频轨道设置视频属性的灵活性，具体包括： - 调用 `createCustomVideoTrack` 创建自定义视频轨道时，支持通过 `width`、`height`、`frameRate` 参数设置分辨率和帧率。 - 创建屏幕共享视频轨道或者自定义视频轨道后，可以调用 `setEncoderConfiguration` 动态调整视频属性。在特定的 macOS Safari 版本上，对屏幕共享视频轨道调用该方法会导致一个已知问题，[查看问题详情](/zh-CN/realtime-media/rtc/reference/browser-compatibility#desktop-issues)。 详细说明参考[设置视频属性](/zh-CN/realtime-media/rtc/build/video/video-profile)。 #### 其他改进 [#其他改进-29] 该版本还有以下改进： - 缩短在 Safari 浏览器上调用 `createMicrophoneAudioTrack` 或 `createMicrophoneAndCameraTracks` 创建轨道的时间。 - 当本地有两个 `AgoraRTCClient` 对象时，支持屏蔽其中一个 `AgoraRTCClient` 加入或离开频道、发布或取消发布的相关回调。以屏幕共享为例：Client A 用于发送屏幕共享视频轨道，Client B 用于发送摄像头视频轨道，开启屏蔽回调功能后，Client A 和 Client B 不会收到对方的以下回调： - `AgoraRTCClient.on("user-published")` - `AgoraRTCClient.on("user-joined")` - `AgoraRTCClient.on("user-unpublished")` - `AgoraRTCClient.on("user-left")` - `AgoraRTCClient.on("published-user-list")` - `AgoraRTCClient.on("user-info-update")` 如需开启该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 ### API 变更 [#api-变更-34] #### 新增 [#新增-31] - `ScreenVideoTrackInitConfig` 中的 `displaySurface`（替代 `screenSourceType`）、`selfBrowserSurface`、`surfaceSwitching` 和 `systemAudio` 属性 - `CustomVideoTrackInitConfig` 中的 `width`、`height`、`frameRate` 属性 - `LocalVideoTrack.setEncoderConfiguration` ## v4.17.0 [#v4170] 该版本于 2023 年 3 月 22 日发布。 ### 升级必看 [#升级必看-42] 为进一步减小包体积，该版本移除了 SDK 内置的美颜模块，并且删除了 `setBeautyEffect`。如果你需要实现美颜功能，声网推荐你使用效果升级、性能更优的美颜插件。详见[使用美颜插件 (Beta) ](/zh-CN/realtime-media/rtc/build/extensions/web/image-enhancement)。 ### 新增特性 [#新增特性-59] #### 千人主播 (Beta) [#千人主播-beta] 自 v4.17.0 起，单个频道可支持最多 1000 位主播同时在线并同时发布音视频流，观众人数无限制，每位主播或观众最多可同时订阅 50 位主播。 如需启用该功能，请联系 [sales@shengwang.cn](mailto:sales@shengwang.cn)。 #### 本地合图 (Beta) [#本地合图-beta] 自 v4.17.0 起，SDK 可以与合图插件搭配使用，在发送端将多路视频流以及图片合为一路视频流。你还可以同时使用合图插件和虚拟背景插件，实现人像画中画效果。详见[使用合图插件](/zh-CN/realtime-media/rtc/build/extensions/web/video-compositing)。 #### 动态切换本地视频流 [#动态切换本地视频流] 为方便灵活切换本地视频轨道，该版本新增 `ILocalVideoTrack.replaceTrack` 方法。 以发布本地视频流后、从摄像头 1 采集切换到摄像头 2 采集为例：在 v4.17.0 之前，你需要先调用 `IAgoraRTCClient.unpublish` 取消发布当前轨道，再调用 `IAgoraRTCClient.publish` 发布新的轨道；自 v4.17.0 起，直接调用 `ILocalVideoTrack.replaceTrack` 即可。 ### 改进 [#改进-68] #### 优化重连机制 [#优化重连机制] 自 v4.17.0 起，SDK 在断线重连时将默认展示断线之前的最后一帧视频画面，避免因为重连而出现黑屏。由于 Safari 自身限制，暂时无法在 Safari 浏览器上体验该优化。 #### 其他改进 [#其他改进-30] 该版本还有以下改进： - 提升了[水晶球](/zh-CN/realtime-media/usage-analytics)上 SDK 相关质量指标的准确性。 - 缩短了加入频道所需的时间。由于 Firefox 自身限制，暂时无法在 Firefox 浏览器上体验该优化。 ### API 变更 [#api-变更-35] #### 新增 [#新增-32] - `ILocalVideoTrack.replaceTrack` #### 删除 [#删除-15] - `ILocalVideoTrack.setBeautyEffect` ### 问题修复 [#问题修复-70] v4.17.0 修复了在 iOS 14.7 及以上版本的 Safari 浏览器上，反复订阅、取消订阅多路音频流可能导致听不到远端用户声音的问题。 ## v4.16.1 [#v4161] 该版本于 2023 年 2 月 8 日发布。 该版本修复了使用 v4.16.0 版本的 SDK 时，水晶球统计的视频卡顿率异常升高的问题。 ## v4.16.0 [#v4160] 该版本于 2023 年 1 月 5 日发布。 ### 新增特性 [#新增特性-60] #### 混合云或私有化平台 [#混合云或私有化平台] v4.16.0 新增 `setLocalAccessPointsV2` 方法，用于配置声网混合云或私有化平台的相关服务。你可以联系 [sales@shengwang.cn](mailto:sales@shengwang.cn) 了解和部署声网混合云或声网私有化平台。 ### 改进 [#改进-69] #### 兼容 Chrome 即将弃用的 RTCMediaStreamTrackStats [#兼容-chrome-即将弃用的-rtcmediastreamtrackstats] Chrome 计划弃用 `RTCMediaStreamTrackStats`，详见[官方说明](https://groups.google.com/g/discuss-webrtc/c/9c8ZjberEcI)。该改动影响声网 Web SDK 返回的一部分本地和远端媒体质量信息，具体如下： | 媒体质量信息 | 受影响的值 | | --- | --- | | `LocalVideoTrackStats` | [release-notes-javascript-html-0-1-1 details](#table-slot-release-notes-javascript-html-0-1-1) | | `RemoteVideoTrackStats` | [release-notes-javascript-html-0-2-1 details](#table-slot-release-notes-javascript-html-0-2-1) | | `RemoteAudioTrackStats` | [release-notes-javascript-html-0-3-1 details](#table-slot-release-notes-javascript-html-0-3-1) | **release-notes-javascript-html-0-1-1 details** - `sendFrameRate` - `sendResolutionHeight` - `sendResolutionWidth` **release-notes-javascript-html-0-2-1 details** - `receiveFrameRate` - `receiveResolutionHeight` - `receiveResolutionWidth` - `renderFrameRate` - `receiveDelay` **release-notes-javascript-html-0-3-1 details** - `receiveDelay` - `receiveLevel` 为确保以上媒体质量信息在 Chrome 上的准确性，请尽快升级 SDK 至 4.16.0 或以上版本。 #### 其他改进 [#其他改进-31] v4.16.0 还有以下改进： - 日志中支持打印 [HTMLMediaElement error 事件](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLMediaElement/error_event)的原因。 - 减小 SDK 包体积。 ### 问题修复 [#问题修复-71] v4.16.0 修复了以下问题： - 修复在 SDK 断网重连过程中，无法进行其它媒体操作的问题。 - 修复转发跨频道媒体流时， [`ChannelMediaRelayConfiguration.addDestChannelInfo`](/zh-CN/api-reference/rtc/web/interfaces/ichannelmediarelayconfiguration#adddestchannelinfo) 无法指定被转发媒体流在目标频道中 `uid` 为 0 的问题。 - 修复 iOS 14.x 上的已知问题。 ### API 变更 [#api-变更-36] #### 新增 [#新增-33] - `IAgoraRTCClient.setLocalAccessPointsV2` ## v4.15.1 [#v4151] 该版本于 2022 年 12 月 2 日发布。 该版本修复了在 iOS 13.7 上接收的音频流无声的问题。
## v4.15.0 [#v4150] 该版本于 2022 年 11 月 10 日发布。 ### 升级必看 [#升级必看-43] #### 云代理服务默认采用 Force UDP 模式 [#云代理服务默认采用-force-udp-模式] v4.15.0 将 `startProxyServer` 方法的 `mode` 参数默认值改为 `3`，即 Force UDP 云代理模式。在该模式下，SDK 始终通过 UDP 协议传输数据。详情参考[使用云代理服务](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)。 ### 新增特性 [#新增特性-61] #### 音强选流 (Beta) [#音强选流-beta] v4.15.0 新增音强选流功能。该功能开启后，声网服务器会根据音量大小对接收端已订阅的音频流进行筛选，选出 N 路音量最大的音频流传输至接收端。N 默认为 3 路。 同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗。 :::warning[注意] 如需开启音强选流功能或者自定义设置 N，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: #### VP9 编解码 (Beta) [#vp9-编解码-beta] 自 v4.15.0 起，Web SDK 在以下版本的浏览器上支持 VP9 视频编解码： | 支持的浏览器版本 ① | Column 2 | | --- | --- | | 桌面端 | [release-notes-javascript-html-1-1-1 details](#table-slot-release-notes-javascript-html-1-1-1) | | Android 端 | [release-notes-javascript-html-1-2-1 details](#table-slot-release-notes-javascript-html-1-2-1) | | iOS 端 | Safari 16+ | **release-notes-javascript-html-1-1-1 details** - Chrome 65+ - Firefox 69+ - Edge 79+ - Safari 16+ **release-notes-javascript-html-1-2-1 details** - Chrome 68+ - 微信 v8.0.6 及以上 - 其它内嵌 WebView 的应用：WebView v65.0.3325.109 及以上 :::info[信息] ① 为保证最佳的用户体验，声网建议使用上述浏览器的最新版本。 ::: 如果与集成声网 Native 端（包括 Android、iOS、Windows 和 macOS 平台）音视频 SDK 的 App 通过 VP9 进行音视频通话，请确保使用 v4.0.0 或以上版本的 Native 端 SDK。 #### 触发 CSP 规则回调 [#触发-csp-规则回调] v4.15.0 新增 `AgoraRTC.onSecurityPolicyViolation` 回调。当声网服务相关的资源加载或请求发送因为触发浏览器的 CSP（Content Security Policy，内容安全策略）规则而失败时，SDK 会触发该回调。收到该回调后，请及时调整你的 CSP 设置，确保能正常体验声网的服务。 ### 改进 [#改进-70] SDK 有以下改进： - 优化了某些场景下 `AgoraRTCClient.on("network-quality")` 回调的准确性。 - 缩短了切换 Wi-Fi 时音视频流的恢复时间。 ### API 变更 [#api-变更-37] #### 新增 [#新增-34] - `IAgoraRTC.onSecurityPolicyViolation`
## v4.14.2 [#v4142] 该版本于 2022 年 10 月 27 日发布。 该版本修复了在 iOS 14.x 上使用微信浏览器时，订阅的第一路音频流无声的问题。 ## v4.14.1 [#v4141] 该版本于 2022 年 10 月 24 日发布。 ### 问题修复 [#问题修复-72] v4.14.1 修复了以下问题： - 在 v17.x 版本的 Electron 上不能正常使用屏幕共享。解决方案详见 [Electron 屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share#electron-屏幕共享)。 - 在桌面端 Safari 浏览器上如果禁用所有视频的自动播放，视频会不断尝试重新播放，导致卡顿。 - 移动端浏览器切换到后台时，SDK 统计的视频卡顿率过高。 - Android WebView 中视频开始播放前会展示 video 元素默认的 poster（灰色播放图标）。 - SDK 断网重连后，跨频道媒体流转发失败。 - 使用跨频道媒体流转发时，用户离开源频道后，SDK 仍然在发送心跳包。 ## v4.14.0 [#v4140] 该版本于 2022 年 8 月 31 日发布。 ### 升级必看 [#升级必看-44] #### getVolumeLevel 准确性优化 [#getvolumelevel-准确性优化] 自 v4.14.0 起，SDK 校准了 `getVolumeLevel` 返回的音量值，能更准确地反映音量大小关系。该方法返回的音量值取值范围依然为 [0,1]，其中 1 代表理论最大音量。如果你的业务场景依赖 `getVolumeLevel` 返回的音量值（比如根据音量值显示用户说话的图标），升级 SDK 后你需要关注对应场景中该音量值的变化。 ### 问题修复 [#问题修复-73] v4.14.0 修复了以下问题： - 接收 Opus 格式的立体声后，听不到立体声效果。 - 在版本低于 Chrome 76 的浏览器上，调用 `getRemoteVideoStats` 获取的视频解码帧率`decodeFrameRate`为 0。 - 在 iOS 14.1 和 14.2 的微信浏览器上，订阅的第一路音频流无声。 - 调用 `LocalVideoTrack.setBeautyEffect` 开启美颜后，调用 `LocalVideoTrack.unpipe` 方法报错。 - 特定场景下，Windows Chrome 103 及以上版本的浏览器上开启小流不生效。 ### API 变更 [#api-变更-38] #### 新增 [#新增-35] - `enableContentInspect` - `client.on("content_inspect_result")` ## v4.13.0 [#v4130] 该版本于 2022 年 7 月 25 日发布。 ### 新增特性 [#新增特性-62] #### 媒体处理插件 [#媒体处理插件] 自 v4.13.0 起，SDK 支持对远端音视频轨道使用媒体处理插件（本地音视频轨道已经在 [v4.10.0](#410) 支持）。 声网目前提供以下用于远端音频轨道的插件： | 插件| 说明 | 相关文档 | | :------------------ | :--------------------------------------------------------- | :----------------------------------------------------------- | | 空间音频插件 (Beta) | 用户语音根据位置变化而实时改变，支持声音模糊、空气衰减等效果，打造沉浸式体验。 | 联系 [sales@shengwang.cn](mailto:sales@shengwang.cn) 了解详情。 | ### 改进 [#改进-71] #### AI 降噪和虚拟背景 [#ai-降噪和虚拟背景] AI 降噪插件和虚拟背景插件由 Beta 发布转变为正式发布（v1.0.0）。 相比之前的版本，v1.0.0 版本的 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。 :::warning[注意] - 使用 AI 降噪插件和虚拟背景插件可能会产生费用。请与 [sales@shengwang.cn](mailto:sales@shengwang.cn) 沟通后再使用。 - 如果当前提供的降噪效果不能满足你的场景，你可以联系 [sales@shengwang.cn](mailto:sales@shengwang.cn)定制降噪效果。 ::: #### Token 过期回调 [#token-过期回调] v4.13.0 完善了 token 过期回调的触发逻辑。如果 token 在设备休眠或断网时过期，当设备恢复并尝试重连时，SDK 会触发 `token-privilege-did-expire` 事件。 ### API 变更 [#api-变更-39] #### 新增 [#新增-36] - `RemoteAudioTrack.pipe` - `RemoteAudioTrack.unpipe` - `RemoteVideoTrack.pipe` - `RemoteVideoTrack.unpipe` ## v4.12.2 [#v4122] 该版本于 2022 年 7 月 7 日发布，优化了 SDK 的自动模式（在自动模式下，SDK 优先连接 SD-RTN™ ，如果连接失败，会自动切换到 TCP/TLS 443）。 ## v4.12.1 [#v4121] 该版本于 2022 年 6 月 27 日发布，修复了以下问题： - 在特定情况下，重连后订阅远端音视频流会失败。 - 在 Firefox 浏览器上反复订阅、取消订阅多路视频流可能导致视频卡住。 ## v4.12.0 [#v4120] 该版本于 2022 年 6 月 15 日发布。 ### 改进 [#改进-72] #### 媒体处理插件 [#媒体处理插件-1] 媒体处理插件有以下改动： - 新增[美颜插件 (Beta) ](https://www.npmjs.com/package/agora-extension-beauty-effect)。美颜插件封装了 Web SDK 4.x 内置的美颜功能（通过 `setBeautyEffect`），并且升级了美颜算法。通过该插件可以调节对比度、亮度、平滑度等参数，实现美白、磨皮、红润肤色等美颜效果。详见[使用美颜插件](/zh-CN/realtime-media/rtc/build/extensions/web/image-enhancement)。 - [虚拟背景插件 (Beta) ](https://www.npmjs.com/package/agora-extension-virtual-background)自 v1.0.0-beta-3 起支持动态虚拟背景，可以将用户的背景设置为一段视频。详见[使用虚拟背景插件](/zh-CN/realtime-media/rtc/build/extensions/web/virtual-background)。 ### 问题修复 [#问题修复-74] v4.12.0 修复了在 Safari 上开启双流模式后，调用 `Track.setEnabled(false)`、`Track.close()` 等方法无法关闭摄像头指示灯的问题。 ## v4.11.1 [#v4111] 该版本于 2022 年 5 月 9 日发布，修复了以下问题： - Firefox 浏览器中订阅音频流可能导致无声。 - iOS 12 Safari 浏览器以及 iOS 13 微信浏览器的兼容性问题。 ## v4.11.0 [#v4110] 该版本于 2022 年 4 月 1 日发布。 ### 升级必看 [#升级必看-45] 自 v4.11.0 起，为保障连通性，SDK 默认使用自动模式。在自动模式下，SDK 优先连接 SD-RTN™ ，如果连接失败，会自动切换到 TCP/TLS 443。你可以通过 `client.on("join-fallback-to-proxy")` 回调监听 SDK 自动切换到 TCP/TLS 443 的事件。 ### 改进 [#改进-73] #### 频道能力提升 [#频道能力提升] 自 v4.11.0 起，单个频道可支持最多 128 位主播同时在线并同时发布音视频流，观众人数无限制，每位主播或观众最多可同时订阅 50 位主播。 如有需要，请联系 [sales@shengwang.cn](mailto:sales@shengwang.cn)。 ### 问题修复 [#问题修复-75] v4.11.0 修复了以下问题： - Angular 依赖的 `zone.js` 导致 SDK 中的 `Promise.finally` 调用出错。 - 在 Chrome 上发送双声道音频时不能开启 AEC。 - SDK 在 Chrome 100 上获取的解码帧率和发送帧率数据不准确。 - 开启双流模式后，调用 `unpublish` 时不传参数会导致调用失败。 ### API 变更 [#api-变更-40] #### 新增 [#新增-37] - `AgoraRTCClient.massSubscribe` - `AgoraRTCClient.massUnsubscribe` - `AgoraRTCClient.on('published-user-list')` - 错误码中新增： - `ERR_TOO_MANY_BROADCASTERS` - `ERR_TOO_MANY_SUBSCRIBERS` ## v4.10.2 [#v4102] 该版本于 2022 年 3 月 24 日发布，修复了在特定场景下调用 `join` 会触发代理异常的问题。 ## v4.10.1 [#v4101] 该版本于 2022 年 3 月 17 日发布，在 `package.json` 中补充了对声网插件系统 `agora-rte-extension` 的 TypeScript 类型定义依赖。如果你使用 TypeScript 进行类型检查，建议将 Typescript 升级至 4.3.2 或以上版本。
## v4.10.0 [#v4100] 该版本于 2022 年 3 月 11 日发布。 ### 新增特性 [#新增特性-63] #### 支持媒体处理插件 [#支持媒体处理插件] v4.10.0 支持在 SDK 内使用媒体处理插件。声网当前提供以下插件可与 Web SDK 搭配使用。如需了解如何使用插件，请查看相关文档。 | 插件 | 说明 | 相关文档 | | :------------------ | :------------------------------------------------- | :----------------------------------------------------------- | | 虚拟背景插件 (Beta) | 支持将用户的背景设为纯色、自定义图片或虚化。 | [使用虚拟背景插件](/zh-CN/realtime-media/rtc/build/extensions/web/virtual-background) | | AI 降噪插件 (Beta) | 支持降低上百种噪声，减少多人同时说话时的人声失真。 | [使用 AI 降噪插件](/zh-CN/realtime-media/rtc/build/extensions/web/noise-reduction) | ### API 变更 [#api-变更-41] #### 新增 [#新增-38] - `AgoraRTC.registerExtensions` - `LocalAudioTrack.pipe` - `LocalAudioTrack.unpipe` - `LocalVideoTrack.pipe` - `LocalVideoTrack.unpipe`
## v4.9.4 [#v494] 该版本于 2022 年 3 月 16 日发布，修复了在 Chrome 隐身模式下的 iFrame 中加载 SDK 时访问 localStorage 报错的问题。 ## v4.9.3 [#v493] 该版本于 2022 年 3 月 3 日发布，修复了一些内部问题。 ## v4.9.1 [#v491] 该版本于 2022 年 2 月 24 日发布，修复了一些内部问题。 ## v4.9.0 [#v490] 该版本于 2022 年 2 月 17 日发布。 ### 新增特性 [#新增特性-64] #### 指定所有远端用户的视频流类型 [#指定所有远端用户的视频流类型] v4.9.0 新增 `setRemoteDefaultVideoStreamType` 方法，用于发流端通过 `enableDualStream` 开启双流模式后，接收端指定所有远端用户的视频流类型。 #### 云代理服务 Force TCP 模式 [#云代理服务-force-tcp-模式] v4.9.0 新增支持云代理服务 Force TCP 模式。该模式下，SDK 始终通过 TLS 443 传输数据。你可在调用 `startProxyServer` 时将 `mode` 设为 5 使用该模式。 #### HTML ` ## v4.8.2 [#v482] 该版本于 2022 年 1 月 27 日发布，修复了 iOS 微信浏览器上锁屏后解锁可能会黑屏的问题。 ## v4.8.1 [#v481] 该版本于 2022 年 1 月 6 日发布，修复了一个内部问题。 ## v4.8.0 [#v480] 该版本于 2021 年 12 月 29 日发布。 ### 改进 [#改进-75] v4.8.0 进行了一些内部改进。 ### 问题修复 [#问题修复-77] v4.8.0 修复了以下问题： - iOS Safari 上以观众角色收流时，能听到主播的声音但 `client.on("volume-indicator")` 回调返回的音量可能为 0。 - iOS Safari 上发流时，先调用 `setDevice` 再调用 `setEncoderConfiguration` 会报错。 ## v4.7.3 [#v473] 该版本于 2021 年 11 月 17 日发布，规避了 iOS 15.1 中 Safari 浏览器上音视频通话被打断后无法恢复播放的问题。 ## v4.7.2 [#v472] 该版本于 2021 年 10 月 14 日发布，有以下改动： - 规避了在某些场景下，iOS 15 中 Safari 浏览器上音视频通话被系统来电打断后，无法恢复音视频播放和发送的问题，详见[问题说明](https://bugs.webkit.org/show_bug.cgi?id=230537)。 - 规避了在桌面端和移动端 Safari 15 浏览器上，使用 `videoTrack.play(element, {mirror: true})` 播放视频时可能出现黑屏的问题，详见[问题说明](https://bugs.webkit.org/show_bug.cgi?id=230532)。 - 修复了在 Edge 浏览器上调用 `AgoraRTC.checkSystemRequirements()` 返回 `false` 的问题。 ## v4.7.1 [#v471] 该版本于 2021 年 9 月 13 日发布，修复了在 Safari 11 和 iPad Chrome 浏览器上的一些问题。 ## v4.7.0 [#v470-3] 该版本于 2021 年 9 月 1 日发布。 ### 升级必看 [#升级必看-46] 自 v4.7.0 起，如果你启用媒体流加密，用户离开频道后，SDK 会自动关闭加密并重置加密设置。如需重新开启加密，你需要在用户再次加入频道前调用 `setEncryptionConfig` 方法。 ### 改进 [#改进-76] v4.7.0 进行了以下改进： - 优化了 Web SDK 在移动端浏览器上的体验。 - 提升了 `getVolumeLevel` 方法获取到的音量的准确性。 - 支持在 Safari 上开启双流模式。 ### 问题修复 [#问题修复-78] v4.7.0 修复了以下问题： - 调用 `LocalAudioTrack.setVolume` 调整本地音量后，本地用户无法感知到音量变化。 - 设置日志等级为不打印日志时，SDK 仍会打印初始化的一些日志。 - `LocalAudioTrack.setDevice` 返回的 Promise 可能一直处于 pending 状态。 ## v4.6.3 [#v463-1] 该版本于 2021 年 8 月 10 日发布，修复了一个偶现问题：本地关闭标签页或浏览器后，远端没有立即收到 `user-left` 事件。 ## v4.6.2 [#v462-3] 该版本于 2021 年 7 月 30 日发布，修复了 SDK 内部存在未销毁的 Media Player 的问题。由于 Chrome 92 新增了一个页面最多创建 75 个 Media Player 的限制，数次播放轨道后，SDK 内未销毁的 MediaPlayer 会导致当前页面无法继续播放。 ## v4.6.1 [#v461-1] 该版本于 2021 年 7 月 21 日发布，修复了一个内部错误。 ## v4.6.0 [#v460-3] 该版本于 2021 年 7 月 16 日发布。 ### 新增特性 [#新增特性-65] #### 极速直播 [#极速直播] Web SDK 自 v4.6.0 起支持极速直播。极速直播与互动直播的区别主要在于主播到观众的延时不同： - 互动直播中观众端延时级别为超低延时 400 毫秒到 800 毫秒。 - 极速直播中观众端延时级别为低延时 1500 毫秒到 2000 毫秒。 声网针对不同级别的观众端延时收取不同的费用。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 你可通过以下两种方式实现低延时观众端： - 调用 `createClient` 创建客户端对象时，将 `role` 参数设为 `"audience"`（观众），将 `clientRoleOptions` 中的 `level` 参数设为 1（低延时）。 - 调用 `setClientRole` 方法，将 `role` 参数设为 `"audience"`（观众），将 `clientRoleOptions` 中的 level 参数设为 1（低延时）。 :::warning[注意] 极速直播暂不支持 Firefox 浏览器。 ::: #### 本地轨道 Mute 状态管理 [#本地轨道-mute-状态管理] v4.6.0 新增 `localTrack.setMuted` 方法用于暂停发送本地轨道的媒体数据。该方法与 `localTrack.setEnabled` 相比，主要有以下区别： - 调用 `localVideoTrack.setEnabled(false)` 停止发送视频后，SDK 会立刻关闭摄像头并停止采集视频，摄像头的指示灯会关闭。而 `localVideoTrack.setMuted` 不影响视频采集状态。 - 调用` setEnabled(true)` 恢复发送较慢，调用 `setMuted(false)` 恢复发送较快。 更多信息，参见 [setEnabled 和 setMuted 有什么区别？](/zh-CN/reference/faq/integration/set_enabled_set_muted) ### 改进 [#改进-77] #### 自动播放失败回调 [#自动播放失败回调] 为优化 iOS 上的视频自动播放处理机制，v4.6.0 废弃了原先的 `onAudioAutoplayFailed` 回调，新增 `onAutoplayFailed` 回调作为替代，用于提示音频或视频自动播放失败。在大部分浏览器中，播放纯视频不受到自动播放策略的限制，但是在低电量模式下的 iOS Safari 浏览器中以及开启过自定义自动播放限制的 iOS WKWebView 中（如 iOS 微信浏览器），纯视频的自动播放也会受到限制。 ### 问题修复 [#问题修复-79] v4.6.0 修复了以下问题： - 调用 `localAudioTrack.setVolume` 方法没有立即生效。 - 一个页面中使用多个 client 时出现的异常问题。 - SDK 没有检查 App ID 是否是大小为 1 到 256 字节的字符串。 ### API 变更 [#api-变更-43] #### 新增 [#新增-40] - `localTrack.setMuted` - `onAutoplayFailed` - `ClientConfig` 中新增 `clientRoleOptions` 参数 - `setClientRole` 方法新增 `options` 参数 #### 废弃 [#废弃-14] - `onAudioAutoplayFailed` ## v4.5.0 [#v450-3] 该版本于 2021 年 5 月 25 日发布。 ### 新增特性 [#新增特性-66] #### 本地播放音频回声消除 [#本地播放音频回声消除] 在多个用户同时播放一个媒体文件的场景中，例如一起看电影，如果用户 A 在 Chrome 浏览器上通过 [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) 使用扬声器播放媒体文件，扬声器播放的声音会和人声一起被 SDK 采集，因此其他用户会听到自己本地播放的媒体音频以及用户 A 发送的媒体音频，从而产生回声。针对这种情况，v4.5.0 提供 `processExternalMediaAEC` 方法。你可以在调用 `processExternalMediaAEC` 方法时传入 HTMLMediaElement，对本地播放的媒体进行回声消除，提升音频体验。 ### 改进 [#改进-78] #### 媒体流加密 [#媒体流加密] 为了加强密钥的安全性，v4.5.0 新增 `"aes-128-gcm2"` 和 `"aes-256-gcm2"` 加密模式，使用 PBKDF2 (Password-Based Key Derivation Function 2) 函数来派生密钥。调用 `setEncryptionConfig` 将加密模式设为 `"aes-128-gcm2"` 或 `"aes-256-gcm2"` 时，除了 `secret`，你还需要设置盐值 `salt`。`secret` 和 `salt` 的生成和设置方式详见[媒体流加密](/zh-CN/realtime-media/rtc/build/advanced-channel/channel-encryption)。 #### 屏幕共享视频属性预设值 [#屏幕共享视频属性预设值] v4.5.0 在屏幕共享视频属性 `ScreenEncoderConfigurationPreset` 中新增以下预设值： - `"480p_3"`: 分辨率为 640 × 480，帧率为 15 fps。 - `"720p_3"`: 分辨率为 1280 × 720，帧率为 15 fps。 - `"1080p_3"`: 分辨率为 1920 × 1080，帧率为 15 fps。 ### 问题修复 [#问题修复-80] v4.5.0 修复了以下问题： - `OptimizationMode` 设置不生效。 - 在 iOS 上使用 Web SDK 采集媒体流时，听到的对端的声音有杂声。 - Firefox 上切换成小流后，`getRemoteVideoStats` 方法获取到的视频分辨率仍然是大流的分辨率。 - Chrome 上调用 `remoteAudioTrack.setVolume` 修改音量后，暂停播放再恢复播放，音量修改失效。 - Chrome 上 `localAudioTrack.setVolume` 没有生效。 ### API 变更 [#api-变更-44] #### 新增 [#新增-41] - `processExternalMediaAEC` - `ClientConfig` 中新增 `clientRoleOptions` 参数 - `setClientRole` 方法新增 `options` 参数 - `setEncryptionConfig` 新增 `salt` 参数 - `EncryptionMode` 新增 `"aes-128-gcm2"` 和 `"aes-256-gcm2"` 属性 - `setArea` 方法新增 `excludedArea` 参数 ## v4.4.0 [#v440-3] 该版本于 2021 年 4 月 2 日发布。 ### 升级必看 [#升级必看-47] #### 域名白名单变更 [#域名白名单变更-1] 自 v4.4.0 起，SDK 的域名白名单变更为： ``` .agora.io .edge.agora.io .sd-rtn.com .edge.sd-rtn.com ``` 为确保你在有网络访问限制的环境中能够使用声网产品，如果你将 SDK 升级至 v4.4.0，请务必更新防火墙的域名白名单。 ### 改进 [#改进-79] #### AES-GCM 加密模式 [#aes-gcm-加密模式] 在安全要求高的场景中，为保证数据的保密性、完整性和真实性，提高数据加密的计算效率，v4.4.0 在 `EncryptionMode` 中新增以下加密模式： - `"aes-128-gcm"`: 128 位 AES 加密，GCM 模式。 - `"aes-256-gcm"`: 256 位 AES 加密，GCM 模式。 开启加密功能后，同一频道内的所有用户都必须使用相同的加密模式和密钥，包括服务端用户（例如声网录制服务）。 #### 云代理服务 [#云代理服务] v4.4.0 新增 `client.on("is-using-cloud-proxy")` 事件，SDK 会在本地成功发布媒体流后触发该事件，提示当前媒体流是否经[云代理服务](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)转发。 #### 错误码 [#错误码] Windows 上禁用采集设备后进行媒体采集，SDK 抛出的错误由 `UNEXPECTED_ERROR` 调整为 `NOT_READABLE`。 ### 问题修复 [#问题修复-81] v4.4.0 修复了以下问题： - 远端音频轨道的 `"first-frame-decoded"` 事件没有触发。 - `AgoraRTC.checkSystemRequirement` 的返回值不准确。 - 网络存在多出口 IP 时，开启云代理后没有生效。 ### API 变更 [#api-变更-45] #### 新增 [#新增-42] - `client.on("is-using-cloud-proxy")` - `EncryptionMode` 新增 `"aes-128-gcm"` 和 `"aes-256-gcm"` ## v4.3.0 [#v430-3] 该版本于 2021 年 1 月 26 日发布。 ### 新增特性 [#新增特性-67] #### 云代理服务 [#云代理服务-1] 该版本优化了声网云代理架构，进一步加强了有网络访问限制的环境中 SDK 的连通性，同时支持限定访问区域。 你可联系 [sales@shengwang.cn](mailto:sales@shengwang.cn) 或技术支持申请使用优化后的云代理服务，然后调用 `startProxyServer` 方法将 `mode` 参数设为 3 实现使用云代理服务。详见[使用云代理服务](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)。 ## v4.2.1 [#v421-3] 该版本于 2020 年 12 月 23 日发布，修复了 `client.publish` 方法传入非法参数时错误说明抛出异常的问题。 ## v4.2.0 [#v420-3] 该版本于 2020 年 12 月 1 日发布。 ### 新增特性 [#新增特性-68] #### 设置区域访问限制 [#设置区域访问限制] 该版本新增 `AgoraRTC.setArea` 方法用于指定服务器的访问区域。指定访问区域之后，SDK 只会连接到指定区域内的声网服务器。支持的区域如下： - 中国 - 北美 - 欧洲 - 亚洲（中国大陆除外） - 日本 - 印度 - 全球 该功能为高级设置，适用于有访问安全限制的场景。 #### 视频传输优化策略 [#视频传输优化策略] 该版本新增 `localVideoTrack.setOptimizationMode` 方法用于设置视频传输优化模式，可设为： - `"balanced"`: 使用默认的传输优化模式。 - `"detail"`: 清晰优先。 - `"motion"`: 流畅优先。 各个传输优化模式的介绍详见 API 参考。该方法适用于在视频通话、视频直播或屏幕共享过程中需要动态调整视频传输优化模式的场景。例如在屏幕共享过程中，如想要把屏幕共享内容从演示文稿切换为视频，可以调用此方法将传输优化模式从 `"detail"` 切换为 `"motion"`，确保视频画面在网络波动时不会出现卡顿。 #### 远端用户网络质量 [#远端用户网络质量] 该版本新增 `AgoraRTCClient.getRemoteNetworkQuality` 方法用于获取本地订阅的所有远端用户的上下行网络质量。 #### 云代理 [#云代理] 该版本中 `AgoraRTCClient.startProxyServer` 方法的 `mode` 参数类型由 `boolean` 改成 `number`。 ### 改进 [#改进-80] - 音频或视频轨道被 `setEnabled` 方法禁用时，依然可以调用 `setDevice` 方法切换设备。 - 调用 `AgoraRTCClient.setEncryptionConfig` 开启 SDK 内置加密功能后，当终端用户设置的密码为弱密码时，SDK 会在控制台打印警告信息，提醒用户设置强密码，即密码必须满足以下要求： - 包含大写字母、小写字母、数字和特殊字符。 - 长度至少 8 位。 ### 问题修复 [#问题修复-82] 该版本修复了以下问题： - 本地的某一个视频轨道被禁用时，不能发布另一个视频轨道。 - 开启双流模式后，发布视频轨道过程中，调用 `setEnabled(false)` 禁用该轨道，发布会失败且无法恢复。 - 直播模式下观众尝试发布本地轨道失败后，切换成主播后也不能发布轨道。 - 开启双流模式后，网络断开时偶现的 bug 导致重连后发布失败。 - 取消发布一个本地摄像头视频轨道再发布本地屏幕共享轨道时，视频码率固定为 700 Kbps 左右，分辨率和帧率下降。 - 由于 Safari 浏览器对于 WebAudio 的支持存在缺陷，在 Safari 浏览器上可能会出现 `BufferSourceAudioTrack` 的声音失真。 - 第一次获取设备权限时不会触发媒体设备变更事件（`onMicrophoneChanged`、`onCameraChanged` 或 `onPlaybackDeviceChanged`），之后再有设备变更时才会触发设备变更事件。 ### API 变更 [#api-变更-46] #### 新增 [#新增-43] - `AgoraRTC.setArea` - `localVideoTrack.setOptimizationMode` - `AgoraRTCClient.getRemoteNetworkQuality` #### 更新 [#更新] - `AgoraRTCClient.startProxyServer` 方法的 `mode` 参数类型由 `boolean` 改成 `number` ## v4.1.1 [#v411-3] 该版本于 2020 年 10 月 27 日发布。该版本修复了以下问题： - 提升了 `event_network_quality` 回调的准确性。 - Safari 上 SDK 无法找到视频采集设备时， `createCameraVideoTrack` 的调用无法结束。 - 调用 `unsubscribe` 取消订阅某远端用户的一路未发布的轨道后，后续对该用户的订阅和取消订阅操作都失效。 - 降低双流模式时频繁调用 `setEnabled` 方法启用和禁用视频轨道的消耗。 - Safari 14 上调用 `client.getLocalVideoStats` 方法的偶现报错。 ## v4.1.0 [#v410-3] 该版本于 2020 年 9 月 4 日发布。 ### 新增特性 [#新增特性-69] #### 客户端截图 [#客户端截图] v4.1.0 新增 `getCurrentFrameData` 方法，用于获取当前渲染的视频帧数据。 #### 音频播放设备管理 [#音频播放设备管理] v4.1.0 新增了以下方法和回调，用于音频播放设备的管理： - `setPlaybackDevice`: 用于设置音频播放设备，比如扬声器。该方法仅支持 Chrome 浏览器。 - `getPlaybackDevices`: 用于获取可用的音频播放设备。 - `onPlaybackDeviceChanged`: 用于提示有音频播放设备被添加或移除。 ### 改进 [#改进-81] - 全面支持基于 Chromium 内核的 Windows Edge 浏览器（80 及以上版本）。 - 提升了 `network-quality` 事件的准确性。 - 新增支持在 macOS 平台上共享 Chrome 标签页时分享标签页的音频。 ### 问题修复 [#问题修复-83] - Safari 上 `checkVideoTrackIsActive` 不准确。 - 开启双流模式后断线重连可能失败。 - 离开频道后调用 `setEnabled` 可能失败。 - CDN 推流转码和非转码不能同时使用。 - 断开连接后自动重新订阅可能失败，报错 `UNEXPECTED_RESPONSE: ERR_SUBSCRIBE_REQUEST_INVALID`。 - 在同一个标签页中相同 UID 加入不同频道会失败。 - 频繁加入离开频道可能导致的频道连接状态错误。 ### API 变更 [#api-变更-47] #### 新增 [#新增-44] - `AgoraRTC.getPlaybackDevices` - `AgoraRTC.onPlaybackDeviceChanged` - `Client.getLocalAudioStats` - `Client.getRemoteAudioStats` - `Client.getLocalVideoStats` - `Client.getRemoteVideoStats` - `LocalVideoTrack.getCurrentFrameData` - `RemoteVideoTrack.getCurrentFrameData` - `LocalAudioTrack.setPlaybackDevice` - `RemoteAudioTrack.setPlaybackDevice` #### 废弃 [#废弃-15] - 废弃了 `LocalTrack.getStats` 和 `RemoteTrack.getStats`，请使用 `Client.getLocalAudioStats` 等方法来获取本地和远端的媒体质量信息。 ## v4.0.1 [#v401-3] 该版本于 2020 年 7 月 18 日发布，该版本修复了以下问题： - 修复 Chrome 70 下发布失败的问题。 - 修复某些情况下离开频道发布操作没有被中止的问题。 ## v4.0.0 [#v400-3] 该版本于 2020 年 7 月 15 日发布。 ### 升级必看 [#升级必看-48] v4.0.0 删除了 `setMute` 方法，新增 `setEnabled` 方法来实现启用或禁用本地轨道。这样做的好处在于： - 彻底移除 Mute 这一概念，避免混淆 Mute 状态和发布状态。 - 在 v4.0.0 之前的版本中，Mute 状态发生改变后 SDK 会触发 `Client.on("user-mute-updated")` 回调。 - 在 v4.0.0 版本中，`setEnabled` 不会引入额外的远端回调事件。如果该本地轨道已发布，`setEnabled(false)` 后远端会触发 `Client.on("user-unpublished")` 回调，`setEnabled(true)` 后远端会触发 `Client.on("user-published")` 回调。 - `setMute(true)` 后，SDK 依然会发送黑帧和静音帧。对于视频轨道来说，Mute 后摄像头的指示灯并不会关闭，因而影响用户体验。而通过 `setEnabled(false)` 禁用本地视频轨道后，SDK 会立刻关闭摄像头并停止采集视频。 :::info[信息] 请注意，由于 `setEnabled` 涉及设备采集，所以是一个**异步方法**，通过 Promise 返回异步操作的结果。 ::: ### 新增特性 [#新增特性-70] #### 视频编码策略 [#视频编码策略] v4.0.0 在 `CameraVideoTrackInitConfig`、`ScreenVideoTrackInitConfig` 和 `CustomVideoTrackInitConfig` 类中新增 `optimizationMode` 字段，支持在调用 `createCameraVideoTrack`、`createCustomVideoTrack` 和 `createScreenVideoTrack` 方法创建视频轨道时选择视频画面是清晰优先还是流畅优先： - 清晰优先： - SDK 会自动根据你的采集分辨率和帧率设定一个最小码率。即使遭遇网络波动，发送码率也不会低于这个值，从而确保清晰的视频画面。 - 大部分情况下，视频编码器不会降低发送分辨率，但是可能会降低帧率。 - 流畅优先： - SDK 不会启用最小码率策略。遭遇网络波动时，发送端会降低码率来确保接收端的视频画面不会出现中断和卡顿。 - 大部分情况下，视频编码器不会降低帧率，但是可能会降低发送分辨率。 :::info[信息] 通过 `createScreenVideoTrack` 创建的视频轨道默认设置为清晰优先。 ::: ### 改进 [#改进-82] - 重新设计 `AgoraRTC.createScreenVideoTrack` 的 `withAudio` 参数，除了 `enable` 和 `disable` 外，还可设为 `auto`，根据浏览器是否支持决定是否分享音频，以满足更多屏幕共享音频的使用场景。 - 不允许 `mediaType` 参数携带 `"all"`，只能为 `"video"` 或 `"audio"`，以避免代码的重复。这一改动涉及以下 API： - `Client.subscribe` 方法中的 `mediaType` 参数不能设为 `"all"`，只能设为 `"audio"` 或 `"video"`。 - `Client.on("user-published")` 和 `Client.on("user-unpublished")` 回调的 `mediaType` 参数不再报告 `"all"`，只会报告 `"audio"` 或 `"video"`。 ### 问题修复 [#问题修复-84] v4.0.0 修复了以下问题： - 调用 `unpublish` 后远端会触发 `Client.on("user-left")` 回调。 - 在 `"rtc"` 模式下进行屏幕共享发生周期性模糊。 - 频繁发布和取消发布时偶现的发布失败。 - `Client.on("network-quality")` 回调不准。 ### API 变更 [#api-变更-48] #### 新增 [#新增-45] - 新增 `Client.localTracks`，用于保存已发布的本地轨道对象列表。 - 新增 `LocalTrack.setEnabled`，用于启用或禁用本地轨道。 - `CameraVideoTrackInitConfig`、`ScreenVideoTrackInitConfig` 和 `CustomVideoTrackInitConfig` 类中新增 `optimizationMode` 字段，用于在创建视频轨道时设置视频画面是清晰优先还是流畅优先。 #### 更新 [#更新-1] - `AgoraRTC.createScreenVideoTrack` 的 `withAudio` 参数新增支持设为 `auto`。 - `Client.subscribe` 的 `mediaType` 参数不能设为 `"all"`。 - `Client.on("user-published")` 和 `Client.on("user-unpublished")` 回调的 `mediaType` 参数不再报告 `"all"`。 #### 废弃 [#废弃-16] - 废弃了 `LocalAudioTrackStats.muteState` 属性。 - 废弃了 `LocalVideoTrackStats.muteState` 属性。 - 废弃了 `RemoteAudioTrackStats.muteState` 属性。 - 废弃了 `RemoteVideoTrackStats.muteState` 属性。 #### 删除 [#删除-16] - 删除了 `Client.on("user-mute-updated")` 回调。 - 删除了 `LocalTrack.setMute` 方法。 - 删除了 `AgoraRTCRemoteUser.audioMuted` 属性。 - 删除了 `AgoraRTCRemoteUser.videoMuted` 属性。 - 删除了 `LocalTrack.getUserId` 方法。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="windows" /> C++ C# ## v4.7.0 [#v470-4] 该版本于 2026 年 9 月 22 日发布。 ### 改进 [#改进-83] #### 音视频链路性能优化 [#音视频链路性能优化-3] 该版本针对音视频链路与线程调度机制做了专项优化，显著降低各音视频场景 CPU 消耗，同步提升长时间运行稳定性。 #### 视频首帧体验优化 [#视频首帧体验优化-3] 该版本优化了视频帧传输调度机制，提升了频道内首个用户订阅流的出图速度。 #### 1v1 连麦延时体验优化 [#1v1-连麦延时体验优化-3] 该版本优化了视频1v1等实时互动场景下的音视频策略，在保障画质的前提下改善端到端延迟，并提升突发抖动等弱网场景下的播放流畅性。 #### 音频场景码率优化 [#音频场景码率优化-3] 该版本优化了音频场景下的码率开销，保障音质的前提下提升了音频流传输效率。 #### 屏幕共享屏蔽窗口能力优化 [#屏幕共享屏蔽窗口能力优化] 该版本优化了 Windows 平台屏幕共享时的屏蔽窗口实现。调用 `startScreenCaptureByDisplayId` 开启屏幕共享，并通过 `ScreenCaptureParameters` 中的 `excludeWindowList` 屏蔽指定窗口时，SDK 会在满足条件时使用独立采集进程处理 MAG 采集，以降低多屏、负坐标、屏幕缩放或安全桌面切换等场景下屏蔽窗口失败或采集异常的风险，提升屏幕共享稳定性。 #### Native 与 Web 互通弱网体验优化 [#native-与-web-互通弱网体验优化-3] 该版本优化了视频 1v1 弱网场景下 Native 与 Web 互通的音视频体验。 ### 问题修复 [#问题修复-85] 该版本修复了以下问题： - 修复了 SDK 运行过程中麦克风被其他应用占用时，应用无法感知麦克风占用状态的问题。修复后，当音频采集设备被占用时，SDK 会通过警告码 `WARN_ADM_RECORD_IS_OCCUPIED`（1033）通知应用。 - 修复了连接 USB 摄像头并开启声卡采集时，环回音频声道数小于双声道后处理不正确，导致偶现电流声或杂音的问题。 - 修复了部分场景下摄像头偶现黑屏的现象，解决了视频采集偶现失败的问题。 - 修复了预加载音效场景下，调用 `stopEffect` 停止播放后再次调用 `playEffect` 时，上一段音效仍有残留的问题。 - 修复了管理员启动或屏幕采集场景下偶现崩溃的问题，提升了 SDK 稳定性。 ## v4.6.2 [#v462-4] 该版本于 2026 年 1 月 16 日 发布。 :::warning[注意] - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.dll` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.dll` 库。 - 4.6.2 RTC SDK `libaosl.dll` 库版本为 1.3.5。 ::: ### 升级必看 [#升级必看-49] #### EncodedVideoFrameInfo 结构体删除参数 uid [#encodedvideoframeinfo-结构体删除参数-uid-1] 该版本删除了 `EncodedVideoFrameInfo` 结构体中的 `uid` 参数。你可以直接从 [`onEncodedVideoFrameReceived`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-encoded#callback_ivideoencodedframeobserver_onencodedvideoframereceived) 回调中获取 `uid` 信息。如果你之前集成过相关代码，请相应更新集成逻辑。 #### 其他 [#其他-14] - 为保证整体解码兼容性，相关解码器插件已内置在 SDK 中。 ### 新增特性 [#新增特性-71] #### Android 新增支持共享单个 App [#android-新增支持共享单个-app] 从 Android 14 开始，系统支持用户在屏幕共享时选择共享整个屏幕或共享单个 App，以提升隐私保护和多任务处理能力。 该版本适配了该系统能力，在支持共享整个屏幕的基础上，新增支持共享单个 App。同时，为便于管理相关事件，新增 [`onLocalVideoEvent`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideoevent) 回调，用于报告本地视频，尤其是屏幕共享相关的事件。 #### Android 新增权限被授予回调 [#android-新增权限被授予回调] 为便于确认屏幕共享场景下的权限授权情况，该版本新增 [`onPermissionGranted`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onpermissiongranted) 回调。你可以通过该回调判断当前用户授予的是相机（Camera）权限还是屏幕（Screen）权限。 #### Media Player 支持获取音频缓冲延迟 [#media-player-支持获取音频缓冲延迟-3] 为解决 K 歌场景中可能会出现的主唱与伴唱伴奏不同步的问题，该版本在 Media Player 模块中新增 [`getAudioBufferDelay`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-info#api_imediaplayer_getaudiobufferdelay) 方法，用于获取播放媒体文件时毫秒级的音频缓冲延迟。 ### 改进 [#改进-84] #### playEffect 支持无缝切换 [#playeffect-支持无缝切换-3] 该版本新增支持音效文件的无缝切换。对于同一个音效文件，如果先调用 `preloadEffect` 再调用 `playEffect`，在播放完成或通过 `stopEffect` 停止播放后，SDK 不会关闭该音效文件。当再次调用 `playEffect` 时，SDK 会直接复用已加载的文件进行播放，从而实现循环播放和无缝切换。该能力同样适用于多频道场景。 #### 屏蔽窗口支持第二屏幕 [#屏蔽窗口支持第二屏幕] 在 4.6.2 之前的版本中，通过屏幕 ID（`startScreenCaptureByDisplayId`）进行屏幕共享时，不支持在多屏场景下配置屏蔽窗口（`ScreenCaptureParameters` 中的 `excludeWindowList`）。为提升屏幕共享体验，该版本新增支持该配置。 同时，为便于识别屏幕共享过程中屏蔽窗口的状态，该版本在 [`LOCAL_VIDEO_STREAM_REASON`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-localvideostreamreason) 中新增枚举值 `LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_EXCLUDE_WINDOW_FAILED (34)`，用于报告屏幕共享屏蔽窗口失败的情况。 #### onVideoDeviceStateChanged 回调时机优化 [#onvideodevicestatechanged-回调时机优化] 该版本优化了 `onVideoDeviceStateChanged` 回调的触发时机。在此前版本中，该回调仅在加入频道后才能触发。从 4.6.2 起，在 `IRtcEngine` 完成初始化后即可收到一次该回调，加入频道后仍可继续监听该事件。 #### onNetworkQuality 准确性提升 [#onnetworkquality-准确性提升-1] 该版本提升了 `onNetworkQuality` 回调中网络质量评估的准确性，使回调数据更贴近用户的主观体验。 #### onPlaybackAudioFrame 支持 24k 采样率的音频帧 [#onplaybackaudioframe-支持-24k-采样率的音频帧-2] 该版本在 `onPlaybackAudioFrame` 中新增支持采样率为 **24000 Hz** 的音频数据。在调用 [`setPlaybackAudioFrameParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#api_irtcengine_setplaybackaudioframeparameters) 设置播放音频数据格式时，可以将 `sampleRate` 设为 `24000`。 #### onEncodedVideoFrameReceived 回调支持获取频道 ID [#onencodedvideoframereceived-回调支持获取频道-id-2] 该版本在 `onEncodedVideoFrameReceived` 回调中新增 `channelId` 参数，方便你在获取编码后视频数据时识别其所属频道。 #### 其他 [#其他-15] - 新增错误码 `ERR_PCMSEND_FORMAT (200)` 和 `ERR_PCMSEND_BUFFEROVERFLOW (201)`，用于报告 PCM 数据发送相关错误。 ### 问题修复 [#问题修复-86] 该版本修复了以下问题： - 第二次调用 `enumerateVideoDevices` 接口获取设备列表不生效。 - Windows 7 设备上共享 PPT 窗口，当 PPT 以全屏自动播放模式运行且包含大量动画时，远端看到的画面有概率出现闪烁。 ## v4.6.0 [#v460-4] 该版本于 2025 年 8 月 18 日发布。 :::warning[注意] - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.dll` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.dll` 库。 - 4.6.0 RTC SDK `libaosl.dll` 库版本为 1.3.0。你可以通过查看 `libaosl.dll` 文件的属性来得知库的版本信息。 ::: ### 升级必看 [#升级必看-50] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的废弃及删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 各版本废弃及删除的 API 信息。详见 [API 下架说明](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-api-sunset)。 #### 直推 CDN 相关接口废弃 [#直推-cdn-相关接口废弃-3] 该版本废弃直推 CDN 功能的相关接口，并会在后续版本中删除，请改用[服务端旁路推流](/zh-CN/realtime-media/media-push)。 - `setDirectCdnStreamingAudioConfiguration` - `setDirectCdnStreamingVideoConfiguration` - `startDirectCdnStreaming` - `stopDirectCdnStreaming` - `DirectCdnStreamingMediaOptions` - `DirectCdnStreamingStats` - `DIRECT_CDN_STREAMING_STATE` - `DIRECT_CDN_STREAMING_REASON` #### 虚拟节拍器接口废弃 [#虚拟节拍器接口废弃-3] 该版本废弃虚拟节拍器功能的相关接口，并会在后续版本中删除。 - [`startRhythmPlayer`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rhythmplayer#api_irtcengine_startrhythmplayer) - [`configRhythmPlayer`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rhythmplayer#api_irtcengine_configrhythmplayer) - [`onRhythmPlayerStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) #### 水印接口废弃 [#水印接口废弃-3] 该版本废弃水印功能的相关接口，推荐使用该版本新增的水印接口。 - [`addVideoWatermark`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2)[2/3] - [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex)[1/2] #### 冗余接口删除 [#冗余接口删除-3] 该版本删除了下列冗余接口及参数： - `setLocalPublishFallbackOption` - `onLocalPublishFallbackToAudioOnly` - `onDownlinkNetworkInfoUpdated` - `onWlAccStats` - `enableWirelessAccelerate` #### 美妆功能实现变更 [#美妆功能实现变更-3] 受美颜重构的影响，自 v4.6.0 起，不再支持调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_setextensionproperty) 启用美妆功能，改用 `STYLE_MAKEUP` 节点实现。 #### 双流模式行为变更 [#双流模式行为变更] - v4.6.0 之前：发送端开启小流自适应模式 (AUTO_SIMULCAST_STREAM) 时，不会主动发送小流，仅当主播身份的接收端调用 [`setRemoteVideoStreamType`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setremotevideostreamtype) 发起小流申请后，发送端收到申请才会开始发送小流。 - v4.6.0 及之后版本：发送端开启小流自适应模式 (AUTO_SIMULCAST_STREAM) 时，会根据订阅端用户的下行网络质量，自动决定发送或停止发送小流。若将 **mode** 设置为其他发送模式或显式配置了小流的宽、高、码率或帧率，则此自适应功能失效。 #### 新增域名白名单 [#新增域名白名单-3] 如果你由之前的版本升级到 v4.6.0 且使用了域名白名单功能（`RtcEngineConfig` 下的 `domainLimit` 为 `true`），请在白名单中添加以下域名，以确保互通顺畅： - `*.rtnsvc.com` - `*.realtimemesh.com` ### 新增特性 [#新增特性-72] #### 多路分辨率视频流 [#多路分辨率视频流-3] 该版本新增多路分辨率视频流（Adaptive Bitrate Video Streaming，简称 ABR）功能，支持对同一视频源设置同时发送多路不同分辨率的视频流，并支持多频道场景。接收端通过自动/手动订阅目标分辨率的视频流。 启用 ABR 后，你可以配置不同分辨率的视频流，（最多四层分辨率，一个最高分辨率的主流和三层其他较低分辨率的视频流），并设置视频流的分辨率、码率、是否启用分层推流回退等选项来灵活控制流的发布。启用分层推流回退后，SDK 会在弱网环境下自动回退到低分辨率的视频流，确保流畅的观看体验。订阅端可根据实际需求选择想要接收的视频流。适用于会议场景、大班课、互动直播等多终端、多网络环境，可显著提升弱网下的观看体验。 具体实现方法以及和视频双流的对比可以参考进阶功能[发布多路视频流 (ABR)](/zh-CN/realtime-media/rtc/build/video/simulcast)。 #### 多路径网络传输 [#多路径网络传输-3] 该版本新增多路径传输功能，适用于终端支持多网卡传输(比如 5G， Wi-Fi，LAN)的设备，可以有效降低甚至消除弱网带来的体验回退，适用于弱网环境、对传输稳定性要求高的实时音视频通信场景，如车载、IoT、火车、高速公路等复杂网络环境。通过在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中设置 `enableMultipath` 为 `true`，可开启多路径传输能力。支持两种传输模式（[`MultipathMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-multipathmode)）： - 动态模式：（默认）根据网络状况动态选择最佳路径进行传输，适用于流量敏感、对体验要求比较高的场景，如会议、教育等。动态模式下，你可以通过 `preferMultipathType` 指定首选的网络传输路径（如优先 Wi-Fi 或移动网络）。 - 全冗余模式：数据会在所有可用网络路径上同时传输，适用于流量不敏感，对体验有极致要求的场景，如户外采播、平行操控等。该模式会产生额外费用，如需使用请[联系技术支持](https://ticket.shengwang.cn/)。 上下行还可分别通过 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的 `uplinkMultipathMode`、`downlinkMultipathMode` 配置。启用后，SDK 会通过回调 [`onMultipathStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onmultipathstats) 实时上报各路径的传输统计信息，包括每一个传输路径的流量消耗，便于开发者监控和优化网络表现。 #### 视频质量评分 [#视频质量评分-3] 该版本在 [`RemoteVideoStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-remotevideostats) 中新增 `mosValue` 成员，报告声网实时视频 MOS（平均主观意见分）评估系统对接收到的远端视频流的质量评分。评分共有 5 个档次，5 分表示视频画质优秀，画面清晰无噪点，1 分表示视频画质极差，画面严重模糊。你可以通过该参数实时观测远端视频流的主观画质表现，便于动态调整视频参数、优化用户体验，或用于质量监控和告警等场景。如需启用该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 支持添加多个水印 [#支持添加多个水印-3] 该版本废弃了 [`addVideoWatermark`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2)[2/3] 和 [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex)[1/2] 方法，新增 [`addVideoWatermark`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/watermark#api_irtcengine_addvideowatermark3)[3/3] 和 [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex1)[2/2] 方法，支持通过水印 ID 来给视频添加多个水印，并可对水印进行排序。如果你需要移除指定水印，可调用 [`removeVideoWatermark`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/watermark#api_irtcengine_removevideowatermark) 方法。 #### 异步销毁引擎 [#异步销毁引擎-3] 自该版本起，`release` 方法新增 `callback` 参数，支持以同步或异步方式销毁引擎。异步销毁引擎时，SDK 会触发 [`RtcEngineReleaseCallback`](/zh-CN/api-reference/rtc/cpp-all-platforms/initialize#rtcenginereleasecallback) 回调。 #### 美颜功能拓展 [#美颜功能拓展-3] 新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。 #### Token 更新结果回调 [#token-更新结果回调-3] 该版本新增 [`onRenewTokenResult`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调及 [`RENEW_TOKEN_ERROR_CODE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-renewtokenerrorcode) 错误码。当调用 `renewToken` 方法更新 Token 后，SDK 会通过 [`onRenewTokenResult`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调通知 Token 更新的结果，并通过 [`RENEW_TOKEN_ERROR_CODE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-renewtokenerrorcode) 返回详细的错误码，开发者可在回调中根据错误码及时处理 Token 更新失败的场景。 #### 其他 [#其他-16] - 新增 [`setPlaybackAudioFrameBeforeMixingParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#api_irtcengine_setplaybackaudioframebeforemixingparameters1)[2/2] 方法用于设置 [`onPlaybackAudioFrameBeforeMixing`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#onplaybackaudioframebeforemixing) 回调中返回的音频帧格式，包括采样率、声道数以及每次回调的数据采样点数。调用此方法后，SDK 会按照设定的参数返回混音前的原始音频数据，便于开发者进行自定义处理或分析。 - 新增 [`preloadEffectEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_preloadeffectex) 方法，用于将指定音效文件预加载到指定频道，支持本地或在线音效文件，便于后续快速播放，适合多频道场景。 - 新增 [`playEffectEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengineex_playeffectex) 方法，用于在指定频道播放音效文件，支持设置循环次数、音调、空间位置、音量、是否发布到频道及播放起始位置等参数，满足丰富的音效播放需求。 - 本地截图上传功能支持通过 [`ContentInspectModule`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-contentinspectmodule) 中新增的 `position` 成员设置截图的视频观测位置，从而实现对原始视频数据或效果处理前后的视频流进行截图并上传。 - 为了提升用户使用绿幕或蓝幕开启虚拟背景功能时，人像分割的准确性和稳定性，该版本在 [`SegmentationProperty`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-segmentationproperty) 中新增 `screenColorType` 属性，支持指定背景幕布的颜色为绿色、蓝色或自动识别。 ### 改进 [#改进-85] #### 美颜重构 [#美颜重构-3] 该版本对美颜功能进行了彻底重构和升级，不仅拓展了美颜功能，提升了美颜效果和性能，还解决了美颜参数配置复杂、集成成本高、美颜资源依赖网络易失效等痛点。主要改进包括： - **新增美颜功能**：新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。 - **API 大幅简化**：将过去版本中的基础美颜、美型、美妆、滤镜功能整合为 `BEAUTY`、`STYLE_MAKEUP`、`FILTER` 三个核心节点 (node)，通过 [`IVideoEffectObject`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-ivideoeffectobject) 统一管理生命周期和参数设置，减少频繁 API 调用带来的性能负担。 - **预设模板开箱即用**：提供多套预设风格模板（如“自然美颜”、“学姐妆”、“冷白滤镜”），大幅简化集成流程，无需手动调试数十项参数。 - **美颜参数动态控制**：该版本新增实时获取美颜参数的能力，开发者可通过 key-value 方式动态读取或修改任意细粒度参数（如磨皮强度、口红类型）。同时支持：调用预设模板快速启用风格效果、保存主播自定义参数配置、随时重置参数至默认状态，极大提升了业务层状态同步的灵活性和开发效率。 - **美颜资源外置**：该版本通过美颜资源外置化设计，将所有美颜资源（特效、滤镜、妆容）均打包为本地 bundle 文件，彻底消除因网络下载失败导致美颜失效的风险。 #### 其他改进 [#其他改进-32] - 优化了在 Windows 11 24H2 及后续版本上的权限请求，避免非必要地获取位置信息。 - 在与 Web 端互通时，新增对 g711 和 g722 音频编解码器的支持，进一步提升了跨平台音频播放的兼容性和清晰度。 - 优化了屏幕共享文档场景下的共享视频清晰度。 ### 问题修复 [#问题修复-87] 该版本修复了以下问题： - 调用 `open` 打开在线音效文件后，调用 [`playEffect`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 开始播放，当调用 [`seek`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定播放位置后，音效文件会从头开始播放。 - 在媒体音量模式下，主播在频道中发布麦克风采集的音频流，同时调用 [`playEffect`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效文件、调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_startaudiomixing2)[2/2] 播放音乐文件，偶现回声。 - 调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 加入频道，然后调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 开始跨频道媒体流转发，下麦、退出频道后重新加入频道开始连麦，偶现 [`onChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged)回调报告 `state` 为 `RELAY_STATE_FAILURE`，`code` 为 `RELAY_ERROR_SERVER_ERROR_RESPONSE`。 - 部分机型的笔记本电脑开启节能模式下，发送端共享屏幕和音频，偶现接收端听到回声。 - 在线教育场景下，偶现教师端本地看多个学生端音画不同步。 ## v4.5.2 [#v452-3] 该版本于 2025 年 4 月 22 日发布。 :::warning[注意] - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.dll` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.dll` 库。 - 4.5.2 RTC SDK `libaosl.dll` 库版本为 1.2.13。你可以通过查看 `libaosl.dll` 文件的属性来得知库的版本信息。 ::: ### 升级必看 [#升级必看-51] 该版本对部分功能的实现方式进行了优化，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 成员参数变更为方法 [#成员参数变更为方法-1] 为优化 API 设计，该版本对 `RtePlayerInfo` 结构体中的所有成员参数进行封装，变为 [`PlayerInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo) 类。如果你的 App 中调用了 `RtePlayerInfo` 结构体中的成员参数，请更新为 [`PlayerInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_rteplayerinfo) 类中对应的方法。 ### 改进 [#改进-86] #### URL 拉流播放 [#url-拉流播放-6] 该版本进一步拓展了 URL 拉流播放的功能，支持播放 CDN URL 和本地媒体资源文件，同时可以设置从指定位置开始播放、调节播放速度、设置播放音量、在播放过程中切换播放源等，详见[观众端 URL 拉流](/zh-CN/realtime-media/rtc/build/optimize-and-operate/playing-url)。 ### 问题修复 [#问题修复-88] 该版本修复了以下问题： - 开启导唱功能播放多音轨歌曲时，调用 [`setAudioPitch`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setaudiopitch) 方法调整歌曲音调后出现杂音。 - 主播端调用 [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-custom-capturenrendering#createcustomaudiotrack) 创建自定义音频采集轨道并将 `trackType` 设为 `AUDIO_TRACK_DIRECT`，调用 [`pushAudioFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-custom-capturenrendering#api_imediaengine_pushaudioframe0) 将自采集音频推送到频道内，然后调用 [`playEffect`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效，频道内的观众听主播的音频有杂音。 - 集成了 SDK 的 App 在音视频互动过程中偶现主线程阻塞导致的 UI 卡顿。 - 调用 [`startScreenCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapture2)[2/2] 开启屏幕共享并在 `config` 中将 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-screencaptureparameters) 的 `enableHighLight` 设为 `true` 对共享窗口进行描边，将共享窗口置于最上层并最大化后，本地预览的共享画面出现闪烁。 - 调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 共享指定屏幕的视频流，通过 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-screencaptureparameters) 的 `excludeWindowList` 来指定屏蔽的窗口，偶现部分窗口屏蔽失败。 - 应用程序共享外接屏幕的视频流，断开外接屏幕连接后偶现应用程序崩溃。 - 调用 [`openWithMediaSource`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 并通过 `source` 参数将 `isLiveSource` 设为 `true` 并播放纯视频流，播放失败。 - 发送端传输多声道编码音频时，接收端偶现杂音。 - App 集成媒体播放器场景下，先后两次调用 `open` 打开不同媒体资源，第二次打开时，媒体播放器信息变化回调 [`onPlayerInfoUpdated`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerinfoupdated)[1/2] 返回第一次媒体资源的信息，不符合预期。 - 调用 [`enableAudioVolumeIndication`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 启用用户音量提示本地发流用户和远端用户音量相关信息，用户音量提示回调 `onAudioVolumeIndication` 返回的本地用户音量为 0。 - 使用 21:9 的显示屏（带鱼屏）进行音视频互通和屏幕共享场景下，设置高分辨率，如 3840*2160，屏幕共享画面在本地预览和接收端显示被裁剪。 - App 调用 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 启用垫片推流功能，偶现发送端推流成功但是 [`onVideoPublishStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 返回当前的发布状态不是 PUB_STATE_PUBLISHED，不符合预期。 - 多频道场景下，App 在调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 成功前调用 [`setupRemoteVideoEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengineex_setupremotevideoex) 初始化远端用户视图，偶现远端用户视图首帧图像显示延时大。 ## v4.5.1 [#v451-3] 该版本于 2025 年 3 月 5 日发布。 :::warning[注意] - 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.dll` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.dll` 库。 - 4.5.1 RTC SDK `libaosl.dll` 库版本为 1.2.13。你可以通过查看 `libaosl.dll` 文件的属性来得知库的版本信息。 ::: ### 新增特性 [#新增特性-73] #### AI 对话场景 [#ai-对话场景-3] 该版本新增了专为与[声网对话式 AI 引擎](/zh-CN/ai)创建的智能体互动设计的 `AUDIO_SCENARIO_AI_CLIENT` 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。 ### 问题修复 [#问题修复-89] 该版本修复了以下问题： - 同时加入两个及以上的频道，连续调用 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex)[1/2] 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。 - 使用媒体播放器时，调用 [`pause`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 定位到指定播放位置、然后调用 [`play`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。 - 使用媒体播放器时，调用 [`switchSrc`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换媒体资源后，调用 [`getPlaySrc`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-info#api_imediaplayer_getplaysrc_imediaplayer) 获取当前正在播放的媒体资源的路径没有变化。 - 在极速直播场景下，观众通过 `string` 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。 - 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。 ## v4.5.0 [#v450-4] 该版本于 2024 年 11 月 26 日发布。 ### 升级必看 [#升级必看-52] 该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 :::warning[注意] 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.dll` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.dll` 库。4.5.1 RTC SDK `libaosl.dll` 库版本为 1.2.13。你可以通过查看 `libaosl.dll` 文件的属性来得知库的版本信息。 ::: #### 成员参数类型变更 [#成员参数类型变更] 为提升各框架对 Native SDK 的适配性，该版本对一些 API 中的成员或参数做了如下修改： | API | 成员/参数 | 变更 | | --- | --- | --- | | [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapturebydisplayid) | **displayId** | 由 uint32_t 型变更为 int64_t 型 | | [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapturebywindowid) | **windowId** | 由 view_t 型变更为 int64_t 型 | | [`ScreenCaptureConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-screencaptureconfiguration) | [release-notes-windows-html-0-3-1 details](#table-slot-release-notes-windows-html-0-3-1) | [release-notes-windows-html-0-3-2 details](#table-slot-release-notes-windows-html-0-3-2) | | [`ScreenCaptureSourceInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-screencapturesourceinfo) | [release-notes-windows-html-0-4-1 details](#table-slot-release-notes-windows-html-0-4-1) | [release-notes-windows-html-0-4-2 details](#table-slot-release-notes-windows-html-0-4-2) | **release-notes-windows-html-0-3-1 details** - **displayId** - **windowId** **release-notes-windows-html-0-3-2 details** - `displayId`：由 uint32_t 型变更为 int64_t 型 - `windowId`： 由 view_t 型变更为 int64_t 型 **release-notes-windows-html-0-4-1 details** - **sourceDisplayId** - **sourceId** **release-notes-windows-html-0-4-2 details** - `sourceDisplayId`：由 view_t 型变更为 int64_t 型 - `sourceId`：默认值由 `nullptr` 变更为 0 #### 强效视频降噪实现变更 [#强效视频降噪实现变更-3] 该版本调整了强效视频降噪的实现方式，在 [`VIDEO_DENOISER_LEVEL`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videodenoiserlevel) 中删除了 `VIDEO_DENOISER_LEVEL_STRENGTH`，改为调用 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 启用视频降噪后，调用 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions)方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)。 此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 [`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)。 #### 摄像头插拔状态变更 [#摄像头插拔状态变更-1] 在之前版本中，当摄像头拔出并重新插入时，[`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) 回调会将设备状态报告为 `MEDIA_DEVICE_STATE_ACTIVE`(1)（设备正在使用）。该版本起，摄像头重新插入后，设备状态将改为 `MEDIA_DEVICE_STATE_IDLE`(0)（设备就绪）。 #### 视频编码偏好变更 [#视频编码偏好变更-3] 为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好： - 在 [`COMPRESSION_PREFERENCE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-compressionpreference) 枚举类中新增 `PREFER_COMPRESSION_AUTO` (-1) 枚举，并替代原有的 `PREFER_QUALITY` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `PREFER_LOW_LATENCY` 或 `PREFER_QUALITY`，以获得最佳的用户体验。 - 在 [`DEGRADATION_PREFERENCE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-degradationpreference) 枚举类中新增 `MAINTAIN_AUTO` (-1) 枚举，并替代原有的 `MAINTAIN_QUALITY` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `MAINTAIN_FRAMERATE`、`MAINTAIN_BALANCED` 或 `MAINTAIN_RESOLUTION`，以获得最优的综合质量体验 (QoE)。 ### 新增特性 [#新增特性-74] #### 高级美颜 [#高级美颜-3] 该版本新增以下两种高级美颜功能： - 美型：调用 [`setFaceShapeBeautyOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 [`setFaceShapeAreaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapeareaoptions) 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。 - 美妆：调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_setextensionproperty) 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。 有关美型和美妆的实现步骤，详见[实现高级美颜](/zh-CN/realtime-media/rtc/build/video/advanced-beauty)。 :::info[信息] 目前，高级美颜功能为**限时免费**，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 秀场直播场景 [#秀场直播场景-3] 该版本在 [`VIDEO_APPLICATION_SCENARIO_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videoapplicationscenariotype) 类下新增枚举 `APPLICATION_SCENARIO_LIVESHOW`(3)（秀场直播），你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为[秀场直播](/zh-CN/solutions/showroom)。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，例如，默认开启音视频帧加速渲染来提升首帧出图体验，无需再额外调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_enableinstantmediarendering)，此外，也增强了在弱网环境和低端设备上的画质和流畅度表现。 #### 限制视频渲染帧率 [#限制视频渲染帧率-3] 该版本新增 [`setLocalRenderTargetFps`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setlocalrendertargetfps) 和 [`setRemoteRenderTargetFps`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setremoterendertargetfps) 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。 在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。 #### URL 拉流播放 [#url-拉流播放-7] URL 拉流播放功能主要用于直播场景，观众端可以直接通过 [`OpenWithUrl`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_player_openwithurl) 打开特定的 URL 来播放实时媒体流，无需显示调用加入频道、订阅等 API，极大简化了观众端观看直播流的 API 调用。 在播放的过程中，观众端可以通过 [`SetAbrSubscriptionLayer`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_playerconfig_setabrsubscriptionlayer) 设置订阅视频大小流，并可以在大小流之间实现平滑切换。如果对视频体验有更高要求，可以联系[联系技术支持](https://ticket.shengwang.cn/)开通 ABR（Adaptive Bitrate，自适应码率）功能。启用该功能后，可以自定义不同层级的视频流分辨率，观众可以实现不同分辨率视频流的平滑切换。 当网络情况不稳定时，观众端可以调用 [`SetAbrFallbackLayer`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/rte-player#api_playerconfig_setabrfallbacklayer) 来设置订阅的视频流的回退选项。SDK 会以你指定的最低质量层级对应的视频流分辨率为下限，在此范围内根据网络状况动态调整分辨率。实现细节详见[观众端 URL 拉流](/zh-CN/realtime-media/rtc/build/optimize-and-operate/playing-url)。 #### 滤镜效果 [#滤镜效果-3] 该版本新增 [`setFilterEffectOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setfiltereffectoptions) 方法，你可以在 **config** 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 `built_in_whiten_filter.cube` 文件，用于快速实现美白滤镜效果。 #### 本地音频合流 [#本地音频合流-3] 该版本新增本地音频合流功能，你可以调用 [`startLocalAudioMixer`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audiomixer#api_irtcengine_startlocalaudiomixer) 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 [`stopLocalAudioMixer`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audiomixer#api_irtcengine_stoplocalaudiomixer) 方法停止本地音频合流；在合流过程中，可以调用 [`updateLocalAudioMixerConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audiomixer#api_irtcengine_updatelocalaudiomixerconfiguration) 方法更新正在合流的音频流配置。 该功能的使用场景示例如下： - 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。 - 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。 - 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。 #### 色彩空间设置 [#色彩空间设置-3] 该版本在 [`VideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-externalvideoframe) 中新增了 **colorSpace**，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。 #### 其他 [#其他-17] - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调新增 `LOCAL_VIDEO_STREAM_REASON_DEVICE_DISCONNECTED` 枚举，表示当前正在使用的视频采集设备已经断开连接（例如，被拔出）。 - [`MEDIA_DEVICE_STATE_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediadevicestatetype) 新增 `MEDIA_DEVICE_STATE_PLUGGED_IN` 枚举，表示设备已插入。 ### 改进 [#改进-87] #### 虚拟背景算法优化 [#虚拟背景算法优化-6] 该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。 #### 录制本地预览视频 [#录制本地预览视频-3] 该版本在 [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-recorderstreaminfo) 中新增 **type** 成员。当调用 [`createMediaRecorder`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_irtcengine_createmediarecorder) 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 [`MediaRecorderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-mediarecorderconfiguration) 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 [`startRecording`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_imediarecorder_startrecording) 即可开始录制本地预览的视频。 #### 指定视频观测位置截图 [#指定视频观测位置截图-3] 该版本新增 [`takeSnapshot`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#api_irtcengine_takesnapshot2)[2/2] 和 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex2)[2/2] 方法，你可以在调用该方法时通过 **config** 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。 #### 自定义音频采集改进 [#自定义音频采集改进-3] 该版本在 [`AudioTrackConfig`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-audiotrackconfig) 中新增了 `enableAudioProcessing` 成员参数，用于控制是否对 `AUDIO_TRACK_DIRECT` 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 `false`，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。 #### 其他改进 [#其他改进-33] - 优化了调用 [`queryDeviceScore`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_querydevicescore) 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。 - 支持使用 YV 12 格式的虚拟摄像头作为视频采集设备。 - 调用 [`switchSrc`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 [`onPlayerEvent`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent) 回调报告 `PLAYER_EVENT_SWITCH_ERROR` 事件，表示媒体资源切换时发生错误。 - 调用 [`setPlaybackSpeed`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，最低支持 0.3 倍速播放。 ### 问题修复 [#问题修复-90] 该版本修复了以下问题： - 调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享屏幕时，通过 **regionRect** 指定的窗口采集区域不准确，导致接收端看到的屏幕共享窗口宽高错误。 - Windows 7 系统下进行音视频互动，偶现找不到系统文件的报错。 - 调用 [`followSystemRecordingDevice`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_followsystemrecordingdevice) 或 [`followSystemPlaybackDevice`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_followsystemplaybackdevice) 设置 SDK 使用的音频采集或播放设备不跟随系统默认的音频播放设备，当音频设备被移除时，本地音频状态回调 [`onLocalAudioStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) 没有被触发，不符合预期。 - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_startaudiomixing)[1/2] 后，立即调用 [`pauseAudioMixing`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_pauseaudiomixing) 暂停播放音乐文件不生效。 ## v4.4.0 [#v440-4] 该版本于 2024 年 8 月 5 日发布。 ### 升级必看 [#升级必看-53] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 :::warning[注意] 自 v4.4.0 起，RTC SDK 提供 API 下架说明，包含各版本废弃及删除的 API 信息。详见 [API 下架说明](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-api-sunset)。 ::: 1. 为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的 [`ExtensionContext`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-extensioncontext) 了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。 | 原有回调 | 现有回调 | | -------------------- | ------------------------------- | | `onExtensionEvent` | [`onExtensionEventWithContext`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#callback_irtcengineeventhandler_onextensioneventwithcontext) | | `onExtensionStarted` | [`onExtensionStartedWithContext`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) | | `onExtensionStopped` | [`onExtensionStoppedWithContext`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext) | | `onExtensionError` | [`onExtensionErrorWithContext`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#callback_irtcengineeventhandler_onextensionerrorwithcontext) | 2. 该版本修改了 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-externalvideoframe) 中的以下成员名称： - `d3d11_texture_2d` 更名为 `d3d11Texture2d`。 - `texture_slice_index` 更名为 `textureSliceIndex`。 - `metadata_buffer` 更名为 `metadataBuffer`。 - `metadata_size` 更名为 `metadataSize`。 ### 新增特性 [#新增特性-75] #### Alpha 透明特效 [#alpha-透明特效-3] 该版本新增 Alpha 透明特效功能，支持在 SDK 采集和自定义采集视频的场景下，在发送端发布视频帧的 Alpha 通道、在接收端对 Alpha 通道进行渲染处理，实现透明礼物特效、接收端自定义主播背景等： - [`VideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-externalvideoframe) 中新增 `alphaBuffer`：设置 Alpha 通道数据。 - [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-externalvideoframe) 中新增 `fillAlphaBuffer`：对于 BGRA 或 RGBA 格式的视频数据，设置是否自动提取 Alpha 通道数据并填入到 `alphaBuffer` 中。 - [`VideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-externalvideoframe) 中新增 `alphaStitchMode`：设置 `alphaBuffer` 和视频帧拼接的相对位置。 另外，[`AdvanceOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-advanceoptions) 中新增成员 `encodeAlpha`，用于设置是否将 Alpha 信息编码并发送到远端。SDK 默认不对 Alpha 信息进行编码发送；如果需要对 Alpha 信息编码发送至远端（例如开启了虚拟背景功能），请显式调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 设置视频编码属性，并将 `encodeAlpha` 设置为 `true`。 :::info[信息] 如需了解在各场景下实现 Alpha 特效的最佳实践，详见[实现 Alpha 透明特效](/zh-CN/realtime-media/rtc/build/video/alpha-effect)。 ::: #### AI 调音器 [#ai-调音器-3] 该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 [`enableVoiceAITuner`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_enablevoiceaituner) 方法并传入 [`VOICE_AI_TUNER_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-voiceaitunertype) 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。 #### 1v1 视频通话场景 [#1v1-视频通话场景-3] 该版本在 [`VIDEO_APPLICATION_SCENARIO_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videoapplicationscenariotype) 类下新增枚举 `APPLICATION_SCENARIO_1V1`（1v1 视频通话）。你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。 ### 改进 [#改进-88] #### 自适应硬解支持 [#自适应硬解支持-1] 该版本新增自适应硬解支持，改进了低端机的渲染流畅性，有效降低系统负载。 #### 渲染能力提升 [#渲染能力提升] Windows 设备上默认启用 DirectX 11 渲染器，可提供高性能、高质量的图形渲染能力。 #### 人脸区域美颜 [#人脸区域美颜-3] 为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。 #### 其他改进 [#其他改进-34] 该版本还进行了如下改进： - 优化了传输策略，调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_enableinstantmediarendering) 不再对传输链路的安全性产生影响。 - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增 `LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_DISPLAY_DISCONNECTED` 枚举，表示进行屏幕采集的显示器已断开连接。 - 优化了屏幕共享场景下的回声消除。 - 该版本在 [`Metadata`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-metadata) 中新增 `channelId` 参数，用于获取发送 Metadata 的源频道名称。 - 废弃了 [`CLIENT_ROLE_CHANGE_FAILED_REASON`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-clientrolechangefailedreason) 中的冗余枚举值 `CLIENT_ROLE_CHANGE_FAILED_REQUEST_TIME_OUT`、`CLIENT_ROLE_CHANGE_FAILED_CONNECTION_FAILED`。 ## v4.3.2 [#v432-3] 该版本于 2024 年 6 月 4 日发布。 ### 改进 [#改进-89] 提升了 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_setremotesubscribefallbackoption) 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_setremotesubscribefallbackoption) 动态切换弱网环境下的音视频流回退选项。 ### 问题修复 [#问题修复-91] 该版本修复了以下问题： - 音视频互动过程中偶现视频流畅度不佳。 - 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。 - 远端用户离开频道时偶现崩溃。 - 调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享 PPT 窗口，当 PPT 播放动画画面时，接收端偶现画面闪烁。 - 在 Windows 7 系统上调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享 WPS PPT 窗口，并设置 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-screencaptureparameters) 的 `enableHighLight` 为 `true` 开启窗口描边，放映该 PPT 后退出放映，之后选择最大化 PPT 窗口，窗口描边没有保留原始窗口大小，不符合预期。 - 调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享窗口，并设置 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-screencaptureparameters) 的 `windowFocus` 和 `enableHighLight` 为 `true` 以前置指定窗口并开启窗口描边，如果当前该窗口被其他窗口覆盖，无法前置该窗口，不符合预期。 - 在 Windows 7 设备上共享窗口并对窗口描边时，点击桌面控件导致描边部分闪烁。 ## v4.3.1 [#v431-3] 该版本于 2024 年 4 月 29 日发布。 ### 新增特性 [#新增特性-76] #### 数据流加密 [#数据流加密-4] 该版本在 [`EncryptionConfig`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` 成员用于启用数据流加密。你可以在调用 [`enableEncryption`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_enableencryption) 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` 和 `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` 枚举得知。 #### 视频小流自适应配置 [#视频小流自适应配置-3] 该版本新增视频小流的自适应配置功能，当你调用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2] 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示： - 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。 - 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。 #### 其他 [#其他-18] - 新增 [`enableEncryptionEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengineex_enableencryptionex) 方法，用于多频道场景下开启媒体流或数据流加密。 - 新增 [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) 方法，用于设置音乐文件的播放速度。 - 新增 [`getCallIdEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengineex_getcallidex) 方法，用于多频道场景下获取通话 ID。 ### 改进 [#改进-90] #### 屏幕共享游戏场景优化 [#屏幕共享游戏场景优化] 该版本对屏幕共享的游戏场景进行了专项优化，在超高清（4K, 60 fps）游戏场景下提升了性能表现，增强了窗口采集的稳定性，为游戏玩家带来更清晰、流畅、稳定的游戏体验。 #### 虚拟背景算法优化 [#虚拟背景算法优化-7] 为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法： - 支持识别任意纯色背景，不再局限于绿幕。 - 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。 - 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。 #### 降低耳返的 CPU 消耗 [#降低耳返的-cpu-消耗-3] 该版本在 [`EAR_MONITORING_FILTER_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-earmonitoringfiltertype) 中新增 `EAR_MONITORING_FILTER_REUSE_POST_PROCESSING_FILTER`(1<<15) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。 #### 其他改进 [#其他改进-35] 该版本还进行了如下改进： - 优化了非屏幕共享场景的视频编解码策略，节省系统性能开销。 - 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。 - 在 [`AUDIO_EFFECT_PRESET`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioeffectpreset) 中新增 `ROOM_ACOUSTICS_CHORUS`（合唱音效），可使人声在合唱场景下更具空间立体感。 - 在 [`RemoteAudioStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-remoteaudiostats) 中新增 `e2eDelay`，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。 ### 问题修复 [#问题修复-92] 该版本修复了以下问题： - 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。 - 屏幕共享场景中，App 调用 [`enableLoopbackRecording`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_enableloopbackrecording) 开启声卡采集功能采集共享屏幕的音频，本地用户手动禁用本地音频采集设备后，声卡采集的音频发送失败，远端用户听不见共享屏幕的声音。 - 用户插拔一次蓝牙或有线耳机，音频状态改变回调 [`onAudioDeviceStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicestatechanged) 会触发多次。 - 在音视频互动过程中，本地用户调用 `setDevice` 设置系统默认播放设备为扬声器后，听远端无声。 - 在共享 Excel 文档窗口时，偶现远端用户看到的画面出现绿屏。 - 在使用 Intel 显卡的设备上发布视频小流偶现性能回退。 - 当发送端用户的网络环境恶化（例如弱网）时，接收端偶现视频流畅度降低、卡顿增加。 ### API 变更 [#api-变更-49] #### 新增 [#新增-46] - [`EncryptionConfig`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` - [`ENCRYPTION_ERROR_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-encryptionerrortype) 中新增如下枚举： - `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` - `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` - [`RemoteAudioStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-remoteaudiostats) 新增 `e2eDelay` - [`ERROR_CODE_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-errorcodetype) 新增 `ERR_DATASTREAM_DECRYPTION_FAILED` - [`AUDIO_EFFECT_PRESET`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioeffectpreset) 新增 `ROOM_ACOUSTICS_CHORUS` - [`getCallIdEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengineex_getcallidex) - [`enableEncryptionEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengineex_enableencryptionex) - [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) - [`EAR_MONITORING_FILTER_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-earmonitoringfiltertype) 新增枚举 `EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS`(1<<15) ## v4.3.0 [#v430-4] 该版本于 2024 年 2 月 22 日发布。 ### 升级必看 [#升级必看-54] 该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 回调中的参数改名 [#回调中的参数改名-3] | 回调 | 原有参数名 | 现有参数名 | | --- | --- | --- | | [`onLocalAudioStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) | `error` | `reason` | | [`onLocalAudioStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) | `error` | `reason` | | `onDirectCdnStreamingStateChanged` | `error` | `reason` | | [`onPlayerSourceStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) | `ec` | `reason` | | [`onRtmpStreamingStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/media-push#callback_irtcengineeventhandler_onrtmpstreamingstatechanged) | `errCode` | `reason` | | 原有枚举类 | 现有枚举类 | | --- | --- | | `LOCAL_AUDIO_STREAM_ERROR` | [`LOCAL_AUDIO_STREAM_REASON`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-localaudiostreamreason) | | `LOCAL_VIDEO_STREAM_ERROR` | [`LOCAL_VIDEO_STREAM_REASON`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-localvideostreamreason) | | `DIRECT_CDN_STREAMING_ERROR` | `DIRECT_CDN_STREAMING_REASON` | | `MEDIA_PLAYER_ERROR` | [`MEDIA_PLAYER_REASON`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediaplayerreason) | | `RTMP_STREAM_PUBLISH_ERROR` | [`RTMP_STREAM_PUBLISH_REASON`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rtmpstreampublishreason) | 为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。 **注：** 有关具体枚举的改名详见 [API 变更](#apichange)。 #### 跨频道媒体流转发 [#跨频道媒体流转发-6] 为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项： | 已删除的方法和回调 | 替代的方法和回调 | | --- | --- | | [release-notes-slot-23-2-0 details](#table-slot-release-notes-slot-23-2-0) | [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) | | [release-notes-slot-23-3-0 details](#table-slot-release-notes-slot-23-3-0) | [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) | | [release-notes-slot-23-4-0 details](#table-slot-release-notes-slot-23-4-0) | [`onChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) | **release-notes-slot-23-2-0 details** - `startChannelMediaRelay` - `updateChannelMediaRelay` **release-notes-slot-23-3-0 details** - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` **release-notes-slot-23-4-0 details** - `onChannelMediaRelayEvent` - `CHANNEL_MEDIA_RELAY_EVENT` #### 本地视频状态改变原因 [#本地视频状态改变原因-3] 该版本对 [`LOCAL_VIDEO_STREAM_REASON`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-localvideostreamreason) 枚举类中的枚举进行了如下修改： - `LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_PAUSED` （原 `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_PAUSED`）的值从 23 变更为 28。 - `LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_RESUMED` （原 `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_RESUMED`）的值从 24 变更为 29。 - `LOCAL_VIDEO_STREAM_ERROR_CODEC_NOT_SUPPORT` 的枚举名变更为 `LOCAL_VIDEO_STREAM_REASON_CODEC_NOT_SUPPORT`。 #### 声卡采集 [#声卡采集-1] - 在 v4.3.0 之前，当你调用 [`disableAudio`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_disableaudio) 关闭整个音频模块后，声卡采集功能不会被关闭。 - 从 v4.3.0 起，当你调用 [`disableAudio`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_disableaudio) 关闭音频模块后，声卡采集功能也会被关闭，如果你需要再次启用声卡采集功能，需要在调用 [`enableAudio`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_enableaudio) 启用音频模块后再次调用 [`enableLoopbackRecording`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_enableloopbackrecording)。 #### 日志加密行为变更 [#日志加密行为变更-3] 出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案： - 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。 - 如有其他特殊需求，请[联系技术支持](https://ticket.shengwang.cn/)并附上对应的加密日志。 ### 新增特性 [#新增特性-77] #### 多视图本地预览 [#多视图本地预览-3] 该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下： 1. 调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第一个视图：在 [`VideoCanvas`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas) 中设置 `position` 参数为 `POSITION_POST_CAPTURER_ORIGIN`（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。 2. 调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第二个视图：在 [`VideoCanvas`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas) 中设置 `position` 参数为 `POSITION_POST_CAPTURER`，此处观测到的视频具备视频前处理的效果。 3. 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。 #### 查询设备评分等级 [#查询设备评分等级-3] 该版本新增 [`queryDeviceScore`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_querydevicescore) 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请[联系技术支持](https://ticket.shengwang.cn/)。 #### 本地播放及发布至远端的音轨控制 [#本地播放及发布至远端的音轨控制-3] 该版本新增 [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 [`openWithMediaSource`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并通过 [`MediaSource`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-mediasource) 中新增的 `enableMultiAudioTrack` 成员来开启音轨控制。 #### 其他 [#其他-19] 该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。 - [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_setremotesubscribefallbackoption)：设置弱网环境下订阅的音视频流回退选项。 - [`onRemoteSubscribeFallbackToAudioOnly`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly)：订阅流已回退为音频流或恢复为音视频流回调。 - [`setPlaybackDeviceVolume`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_setplaybackdevicevolume)：设置播放设备音量。 - [`getRecordingDeviceVolume`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_getrecordingdevicevolume)：获取音频采集设备音量。 - `setPlayerOption`：设置媒体播放器选项，用于提供技术预览或特别定制功能。 - [`enableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback)：设置是否在本地播放外部音频源。 ### 改进 [#改进-91] #### SDK 任务处理调度优化 [#sdk-任务处理调度优化-3] 该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面： - 远端及本地的首帧出图与出声速度提升了 10% 到 20%。 - API 的调用耗时和响应耗时缩短了 5% 到 50%。 - SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。 - SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。 #### 耳返音量提升 [#耳返音量提升-3] 该版本为用户提供更灵活的耳返音频调整选项，支持调用 [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) 将耳返音量设置为原始音量的 4 倍。 #### 空间音频易用性提升 [#空间音频易用性提升-3] - 该版本优化了 [`setZones`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setzones) 方法的设计，支持将 `zones` 参数设置为 `NULL`，表示清除所有隔声区域。 - 自该版本起，在调用 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ilocalspatialaudioengine) 中的方法之前，无需先取消订阅频道内所有远端用户的音频流。 #### 其他改进 [#其他改进-36] 该版本还进行了如下改进： - 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。 - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增 `LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_AUTO_FALLBACK` 枚举，表示屏幕共享过程中发生意外错误（可能由于窗口阻塞失败），导致性能下降，但屏幕共享过程本身没有受到影响。 - 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用 [setLocalAccessPoint](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_setlocalaccesspoint) 解析域名时的稳定性。 - 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。 - [`LocalAudioStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。 - 新增 [`onPlayerCacheStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) 回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。 - 新增 [`onPlayerPlaybackStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) 回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过 [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-playerplaybackstats) 来获取当前音、视频的码率等信息。 ### 问题修复 [#问题修复-93] 该版本修复了以下问题： - 当同时共享两路屏幕共享视频流时，[`onLocalVideoStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostats) 回调上报的 `captureFrameRate` 为 0，不符合预期。 - 在指定屏幕区域共享时，鼠标在共享区域内的坐标不准确。当鼠标位于共享区域的边界附近时，可能导致共享的画面中看不到鼠标。 - 使用 3.5 mm 耳机多次插拔设备后，SDK 未能检测到音频路由的变化。 ### API 变更 [#api-变更-50] #### 新增 [#新增-47] - [`VideoCanvas`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas) 新增 `subviewUid` 和 `uid` 成员 - [`enableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback) - [`queryDeviceScore`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_querydevicescore) - [`MEDIA_SOURCE_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediasourcetype) 中新增 `CUSTOM_VIDEO_SOURCE` 枚举 - [`AudioRoute`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioroute) 中新增 `ROUTE_BLUETOOTH_DEVICE_A2DP` 枚举 - [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) - [`onPlayerCacheStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) - [`onPlayerPlaybackStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) - [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-playerplaybackstats) #### 修改 [#修改-10] - 以下枚举名中的 `ERROR` 字段全部修改为 `REASON`： - `LOCAL_AUDIO_STREAM_ERROR_OK` - `LOCAL_AUDIO_STREAM_ERROR_FAILURE` - `LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION` - `LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY` - `LOCAL_AUDIO_STREAM_ERROR_RECORD_FAILURE` - `LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE` - `LOCAL_AUDIO_STREAM_ERROR_RECORD_INVALID_ID` - `LOCAL_AUDIO_STREAM_ERROR_PLAYOUT_INVALID_ID` - `LOCAL_VIDEO_STREAM_ERROR_OK` - `LOCAL_VIDEO_STREAM_ERROR_FAILURE` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY` - `LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE` - `LOCAL_VIDEO_STREAM_ERROR_CODEC_NOT_SUPPORT` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_DISCONNECTED` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_INVALID_ID` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_CLOSED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_OCCLUDED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_NO_PERMISSION` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_PAUSED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_RESUMED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_HIDDEN` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_HIDDEN` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_MINIMIZED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_FAILURE` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_SYSTEM_PRESSURE` - `DIRECT_CDN_STREAMING_ERROR_OK` - `DIRECT_CDN_STREAMING_ERROR_FAILED` - `DIRECT_CDN_STREAMING_ERROR_AUDIO_PUBLICATION` - `DIRECT_CDN_STREAMING_ERROR_VIDEO_PUBLICATION` - `DIRECT_CDN_STREAMING_ERROR_NET_CONNECT` - `DIRECT_CDN_STREAMING_ERROR_BAD_NAME` - `PLAYER_ERROR_NONE` - `PLAYER_ERROR_INVALID_ARGUMENTS` - `PLAYER_ERROR_INTERNAL` - `PLAYER_ERROR_NO_RESOURCE` - `PLAYER_ERROR_INVALID_MEDIA_SOURCE` - `PLAYER_ERROR_UNKNOWN_STREAM_TYPE` - `PLAYER_ERROR_OBJ_NOT_INITIALIZED` - `PLAYER_ERROR_CODEC_NOT_SUPPORTED` - `PLAYER_ERROR_VIDEO_RENDER_FAILED` - `PLAYER_ERROR_INVALID_STATE` - `PLAYER_ERROR_URL_NOT_FOUND` - `PLAYER_ERROR_INVALID_CONNECTION_STATE` - `PLAYER_ERROR_SRC_BUFFER_UNDERFLOW` - `PLAYER_ERROR_INTERRUPTED` - `PLAYER_ERROR_NOT_SUPPORTED` - `PLAYER_ERROR_TOKEN_EXPIRED` - `PLAYER_ERROR_UNKNOWN` - `RTMP_STREAM_PUBLISH_ERROR_OK` - `RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT` - `RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED` - `RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT` - `RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR` - `RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR` - `RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN` - `RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT` - `RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED` - `RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND` - `RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED` - `RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER` - `RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM` - `RTMP_STREAM_PUBLISH_ERROR_NET_DOWN` - `RTMP_STREAM_PUBLISH_ERROR_INVALID_PRIVILEGE` - `RTMP_STREAM_UNPUBLISH_ERROR_OK` #### 删除 [#删除-17] - `startChannelMediaRelay` - `updateChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - `onChannelMediaRelayEvent` - `CHANNEL_MEDIA_RELAY_EVENT` ## v4.2.6 [#v426-3] 该版本于 2023 年 11 月 16 日发布。 ### 问题修复 [#问题修复-94] 该版本修复了在特定场景下（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道），接收端的视频出现卡顿或冻结。 ## v4.2.3 [#v423-3] 该版本于 2023 年 10 月 12 日发布。 ### 新增特性 [#新增特性-78] #### 本地截图上传更新 [#本地截图上传更新-3] 为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动： - [`CONTENT_INSPECT_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-contentinspecttype) 中新增 `CONTENT_INSPECT_IMAGE_MODERATION` 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。 - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-contentinspectconfig) 中新增的 `serverConfig` 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请[联系技术支持](https://ticket.shengwang.cn/)。 此外，该版本还新增了 [`enableContentInspectEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) 方法，支持同时对多条视频流截图并上传。 #### 支持 ID3D11Texture2D 渲染 [#支持-id3d11texture2d-渲染] 自该版本起，SDK 支持 ID3D11Texture2D 类型的视频格式，提升了游戏场景中视频帧的渲染效果。你可以在调用 [`pushVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-custom-capturenrendering#pushvideoframe) 方法将外部原始视频帧推送到 SDK 时，设置 **format** 为 `VIDEO_TEXTURE_ID3D11TEXTURE2D`；并通过设置 **d3d11_texture_2d** 和 **texture_slice_index** 属性，来确定要使用的 ID3D11Texture2D 纹理对象。 #### 本地视频状态错误码更新 [#本地视频状态错误码更新] 为了帮助用户在屏幕共享场景下了解本地视频出错的准确原因，[`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增了如下几组枚举： - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_PAUSED`(23)：屏幕采集已暂停。当前屏幕可能已切换到安全桌面，例如 UAC 对话框或者 Winlogon 桌面。 - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_RESUMED`(24)：屏幕采集已从暂停状态中恢复。 - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_HIDDEN`(25)：当前屏幕采集的窗口处于隐藏状态，并且在当前屏幕上不可见。 - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_HIDDEN`(26)：进行屏幕采集的窗口已经从隐藏状态中恢复。 - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_MINIMIZED`(27)：进行屏幕采集的窗口已经从最小化状态中恢复。 #### 进阶功能查询 [#进阶功能查询-3] 该版本新增了 [`isFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_isfeatureavailableondevice) 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。 在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。 此外，自该版本起，调用 [`enableVirtualBackground`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 和 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 `-4: ERR_NOT_SUPPORTED` 表示该设备不支持开启该功能。 ### 改进 [#改进-92] #### 优化虚拟背景内存占用 [#优化虚拟背景内存占用-3] 该版本升级了虚拟背景算法，降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。 #### 屏幕共享场景优化 [#屏幕共享场景优化-1] 该版本优化了在超高清（4K，60 fps）游戏共享场景下的性能和编码效率，有效降低了屏幕共享时系统资源占用率。 #### 其他改进 [#其他改进-37] 该版本还进行了如下改进： - 当调用 [`setPlaybackSpeed`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，传入非法参数后会返回错误码 `-2`，表示方法中设置了无效的参数，需要重新设置参数。 - 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。 ### 问题修复 [#问题修复-95] 该版本修复了以下问题： - 在屏幕共享场景下偶现崩溃、掉帧。 - 本地系统时间不正确时，偶现加入频道失败。 - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/audio-mixing#api_irtcengine_startaudiomixing2)[2/2] 使用相同的 `soundId` 播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 - 调用一次 `takeSnapshotEx` 获取视频截图会收到多次 [`onSnapshotTaken`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 视频截图结果回调。 ### API 变更 [#api-变更-51] #### 新增 [#新增-48] - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 中新增如下枚举： - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_PAUSED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_RESUMED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_HIDDEN` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_HIDDEN` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_MINIMIZED` - [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-externalvideoframe) 中新增 `d3d11_texture_2d` 和 `texture_slice_index` 成员 - [`VIDEO_PIXEL_FORMAT`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videopixelformat) 中新增 `VIDEO_TEXTURE_ID3D11TEXTURE2D` 枚举 - [`enableContentInspectEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) - [`CONTENT_INSPECT_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-contentinspecttype) 新增 `CONTENT_INSPECT_IMAGE_MODERATION` - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-contentinspectconfig) 中新增 `serverConfig` 可选参数 - [`isFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_isfeatureavailableondevice) - [`FeatureType`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-featuretype) ## v4.2.2 [#v422-3] 该版本于 2023 年 7 月 27 日发布。 ### 新增特性 [#新增特性-79] #### 通配 Token [#通配-token-3] 该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 :::warning[注意] 声网 4.x RTC SDK 均支持使用通配 Token。 ::: #### 预加载频道 [#预加载频道-4] 该版本新增 [`preloadChannel`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_preloadchannel) 和 [`preloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_preloadchannelwithuseraccount) 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。 在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 #### 自定义视频画布背景颜色 [#自定义视频画布背景颜色-3] 该版本在 [`VideoCanvas`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas) 中增加了 `backgroundColor` 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。 #### 发布多源采集的视频流 [#发布多源采集的视频流-1] 该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中新增下列成员，支持你发布第三个、第四个摄像头和屏幕采集到的视频流： - `publishThirdCameraTrack`：发布第三个摄像头采集的视频。 - `publishFourthCameraTrack`：发布第四个摄像头采集的视频。 - `publishThirdScreenTrack`：发布第三个屏幕采集的视频。 - `publishFourthScreenTrack`：发布第四个屏幕采集的视频。 :::warning[注意] 目前 SDK 支持在同一时间、同一 `RtcConnection` 中发布多路音频流、一路视频流。 ::: ### 改进 [#改进-93] #### 虚拟背景算法升级 [#虚拟背景算法升级-3] 该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。 #### 跨频道连麦优化 [#跨频道连麦优化-3] 该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 时，你可以指定最多 6 个目标频道。 #### 视频编解码查询能力增强 [#视频编解码查询能力增强-3] 为提升设备编解码能力查询功能，该版本在 [`CodecCapInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-codeccapinfo) 中新增 `codecLevels` 成员。当成功调用 [`queryCodecCapability`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_irtcengine_querycodeccapability) 后，可通过 `codecLevels` 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。 #### 其他改进 [#其他改进-38] - 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。 - 为帮助用户了解更多类型的远端视频状态改变的原因，[`onRemoteVideoStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调中新增了 `REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT` 枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。 ### 问题修复 [#问题修复-96] 该版本修复了以下问题： - 网络异常导致频道连接断开后，频道连接恢复较慢。 - 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。 - 自采集场景下，[`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions)、[`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)、[`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 和 [`setColorEnhanceOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions) 无法自动加载插件。 - 多设备音频录制场景下，反复插拔或开启/禁用音频录制设备后，偶现调用 [`startRecordingDeviceTest`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#startrecordingdevicetest) 进行音频采集设备测试时听不到声音。 ### API 变更 [#api-变更-52] #### 新增 [#新增-49] - [`preloadChannel`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_preloadchannel) - [`preloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_preloadchannelwithuseraccount) - [`updatePreloadChannelToken`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_updatepreloadchanneltoken) - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中增加下列成员： - `publishThirdCameraTrack` - `publishFourthCameraTrack` - `publishThirdScreenTrack` - `publishFourthScreenTrack` - [`CodecCapLevels`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-codeccaplevels) - [`VIDEO_CODEC_CAPABILITY_LEVEL`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videocodeccapabilitylevel) - [`VideoCanvas`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas) 中增加 `backgroundColor` 成员 - [`CodecCapInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-codeccapinfo) 中增加 `codecLevels` 成员 - [`REMOTE_VIDEO_STATE_REASON`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-remotevideostatereason) 中增加 `REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT` 枚举 ## v4.2.1 [#v421-4] 该版本于 2023 年 6 月 21 日发布。 ### 改进 [#改进-94] 该版本改进了网络传输策略，提升了音视频交互的流畅度。 ### 问题修复 [#问题修复-97] 该版本修复了以下问题： - SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。 - 发送端调用 [`setAINSMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。 - 发送端将两路摄像头采集的视频进行本地合图并发布后，接收端偶现第二路摄像头画面缺失。 ## v4.2.0 [#v420-4] 该版本于 2023 年 5 月 24 日发布。 ### 升级必看 [#升级必看-55] 该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。 #### 视频采集 [#视频采集-1] 原有用于摄像头和屏幕采集的方法已删除，请改用下表中列出的替代方法，并通过设置 `sourceType` 来指定视频源。 | 已删除方法 | 替代方法 | | --- | --- | | [release-notes-windows-html-4-1-0 details](#table-slot-release-notes-windows-html-4-1-0) | [`startCameraCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/camera-capture#api_irtcengine_startcameracapture) | | [release-notes-windows-html-4-2-0 details](#table-slot-release-notes-windows-html-4-2-0) | [`stopCameraCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/camera-capture#api_irtcengine_stopcameracapture) | | [release-notes-windows-html-4-3-0 details](#table-slot-release-notes-windows-html-4-3-0) | [`startScreenCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapture2)[2/2] | | [release-notes-windows-html-4-4-0 details](#table-slot-release-notes-windows-html-4-4-0) | [`stopScreenCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_stopscreencapture2)[2/2] | **release-notes-windows-html-4-1-0 details** - `startPrimaryCameraCapture` - `startSecondaryCameraCapture` **release-notes-windows-html-4-2-0 details** - `stopPrimaryCameraCapture` - `stopSecondaryCameraCapture` **release-notes-windows-html-4-3-0 details** - `startPrimaryScreenCapture` - `startSecondaryScreenCapture` **release-notes-windows-html-4-4-0 details** - `stopPrimaryScreenCapture` - `stopSecondaryScreenCapture` #### 视频数据获取 [#视频数据获取-3] - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调中新增了 `sourceType` 参数，用于表示具体的视频源类型。 - 以下回调已删除，请通过 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 和 [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 中的 `sourceType` 参数得知视频源类型。 - `onSecondaryPreEncodeCameraVideoFrame` - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` - `onSecondaryPreEncodeScreenVideoFrame` #### 媒体发布选项 [#媒体发布选项-3] - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` 已删除，请改用 `publishCustomAudioTrack`。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的 `publishTrancodedVideoTrack` 变更为 `publishTranscodedVideoTrack。` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的 `publishCustomAudioSourceId` 变更为 `publishCustomAudioTrackId`。 #### 音视频录制 [#音视频录制-3] - 删除 [`INTERFACE_ID_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-interfaceidtype) 中的 `AGORA_IID_MEDIA_RECORDER`。在创建录制对象前无需再获取 `AGORA_IID_MEDIA_RECORDER` 接口类指针，你可以直接调用该版本新增的 [`createMediaRecorder`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_irtcengine_createmediarecorder) 方法创建录制对象。 - 删除 [`startRecording`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_imediarecorder_startrecording) 、[`stopRecording`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_imediarecorder_setmediarecorderobserver) 中的 `connection` 参数。 - 删除 [`IMediaRecorder`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediarecorder) 类中的 `release` 方法，你可直接调用该版本新增的 [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_irtcengine_destroymediarecorder) 方法来销毁录制对象以释放资源。 #### 本地合图 [#本地合图-3] - [`LocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-localtranscoderconfiguration) 中的 `VideoInputStreams` 变更为 `videoInputStreams`。 - [`TranscodingVideoStream`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-transcodingvideostream) 中的枚举类 [`MEDIA_SOURCE_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediasourcetype) 变更为 [`VIDEO_SOURCE_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。 #### 其他兼容性变更 [#其他兼容性变更-3] - `onApiCallExecuted` 已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。 - [`IAudioFrameObserver`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_iaudioframeobserver) 类名变更为 [`IAudioPcmFrameSink`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_iaudiopcmframesink)，因此下列方法原型也有相应更新： - `onFrame` - [`IMediaPlayer`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayer) 下的 [`registerAudioFrameObserver`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#registeraudioframeobserver)[1/2]、[`registerAudioFrameObserver`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#api_imediaplayer_registeraudioframeobserver2)[2/2] - [`enableDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_enabledualstreammode)[1/2] 和 [`enableDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_enabledualstreammode3)[2/2] 已废弃，请改用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setdualstreammode)[1/2] 和 [`setDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2]。 - `startChannelMediaRelay`、`updateChannelMediaRelay`、`startChannelMediaRelayEx` 和 `updateChannelMediaRelayEx` 已废弃，请改用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex)。 - `OnRecordAudioEncodedFrame` 变更为 [`onRecordAudioEncodedFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-encoded#callback_iaudioencodedframeobserver_onrecordaudioencodedframe)。 - `OnPlaybackAudioEncodedFrame` 变更为 [`onPlaybackAudioEncodedFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-encoded#callback_iaudioencodedframeobserver_onplaybackaudioencodedframe)。 - `OnMixedAudioEncodedFrame` 变更为 [`onPlaybackAudioEncodedFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-encoded#callback_iaudioencodedframeobserver_onplaybackaudioencodedframe)。 ### 新增特性 [#新增特性-80] #### AI 降噪 [#ai-降噪-3] 该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 [`setAINSMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。 #### 增强虚拟背景 [#增强虚拟背景-3] 为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 [`enableVirtualBackground`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 方法时，将自定义背景设置为更多类型： - 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。 - 将背景替换为多种格式的本地视频。 #### 视频场景化设置 [#视频场景化设置-3] 该版本新增 [`setVideoScenario`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoscenario) 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化： - 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。 - 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。 #### 本地录制远端音视频 (Beta) [#本地录制远端音视频-beta-3] 该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 [`onRecorderStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#callback_imediarecorderobserver_onrecorderstatechanged) 、[`onRecorderInfoUpdated`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数，用于表示录制的音视频流的具体信息，并新增 [`createMediaRecorder`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_irtcengine_createmediarecorder) 方法，用于创建本地或远端的录制对象。 你可以通过如下方法体验本地录制远端音视频功能： - [`createMediaRecorder`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_irtcengine_createmediarecorder)：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。 - [`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_imediarecorder_setmediarecorderobserver)：设置录制回调对象。 - [`startRecording`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_imediarecorder_startrecording)：开始录制。 - [`stopRecording`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_imediarecorder_stoprecording)：停止录制。 - [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_irtcengine_destroymediarecorder)：销毁录制对象。 #### 本地合图 [#本地合图-4] 该版本新增了 [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调，当你在开启本地合图或者更新本地合图配置失败时，SDK 会触发该回调并报告合图失败的原因。 #### 多端同步 [#多端同步-3] 在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_getntpwalltimeinms) 方法获取当前的 NTP（网络时间协议）时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。 ### 改进 [#改进-95] #### 优化变声 [#优化变声-3] 该版本新增了 [`setLocalVoiceFormant`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceformant) 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 [`setLocalVoicePitch`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch) 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。 #### 提升渲染兼容性 [#提升渲染兼容性] 提升了渲染的兼容性，解决了部分设备渲染失败而导致的黑屏问题。 #### 提升音视频同步能力 [#提升音视频同步能力-3] 针对自定义视频和音频采集场景，该版本新增 [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_getcurrentmonotonictimeinms) 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。 #### 优化多路摄像头及屏幕采集 [#优化多路摄像头及屏幕采集-1] 该版本新增 [`startCameraCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/camera-capture#api_irtcengine_startcameracapture) 和 [`startScreenCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapture2)[2/2] 方法，通过多次调用并指定 `sourceType` 参数可以开启多路摄像头采集的视频流和多路屏幕采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头和显示器的场景。 #### 优化跨频道连麦 [#优化跨频道连麦-3] 该版本新增 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。 #### 多路音频自采集 [#多路音频自采集-3] 为更好地满足音频自采集的场景需求，该版本新增了 [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-custom-capturenrendering#createcustomaudiotrack) 和 [`destroyCustomAudioTrack`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-custom-capturenrendering#destroycustomaudiotrack) 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性： - 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。 - 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。 ### 问题修复 [#问题修复-98] 该版本修复了当快速切换身份角色时，观众端听不到声音的问题。 ### API 变更 [#api-变更-53] #### 新增 [#新增-50] - [`startCameraCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/camera-capture#api_irtcengine_startcameracapture) - [`stopCameraCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/camera-capture#api_irtcengine_stopcameracapture) - [`startScreenCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapture2)[2/2] - [`stopScreenCapture`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_stopscreencapture2)[2/2] - [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) - [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) - [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_getntpwalltimeinms) - [`setVideoScenario`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoscenario) - [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_getcurrentmonotonictimeinms) - [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) - [`setAINSMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) - [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-custom-capturenrendering#createcustomaudiotrack) - [`destroyCustomAudioTrack`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-custom-capturenrendering#destroycustomaudiotrack) - [`createMediaRecorder`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_irtcengine_createmediarecorder) - [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_irtcengine_destroymediarecorder) - [`AudioTrackConfig`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-audiotrackconfig) - [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-recorderstreaminfo) - [`AUDIO_AINS_MODE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audioainsmode) - [`AUDIO_TRACK_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-audiotracktype) - [`VIDEO_APPLICATION_SCENARIO_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videoapplicationscenariotype) - [`SCREEN_CAPTURE_FRAMERATE_CAPABILITY`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-screencaptureframeratecapability) - [`RtcEngineContext`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcengineconfig) 中新增 `domainLimit` 和 `autoRegisterAgoraExtensions` 属性 - [`onRecorderStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`onRecorderInfoUpdated`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数 - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 中增加 `sourceType` 参数 - [`BACKGROUND_SOURCE_TYPE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-backgroundsourcetype) 中新增 `BACKGROUND_NONE` 和 `BACKGROUND_VIDEO` #### 修改 [#修改-11] - `OnRecordAudioEncodedFrame` 变更为 [`onRecordAudioEncodedFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-encoded#callback_iaudioencodedframeobserver_onrecordaudioencodedframe) - `OnPlaybackAudioEncodedFrame` 变更为 [`onPlaybackAudioEncodedFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-encoded#callback_iaudioencodedframeobserver_onplaybackaudioencodedframe) - `OnMixedAudioEncodedFrame` 变更为 [`onPlaybackAudioEncodedFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-encoded#callback_iaudioencodedframeobserver_onplaybackaudioencodedframe) #### 废弃 [#废弃-17] - [`enableDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_enabledualstreammode)[1/2] - [`enableDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_enabledualstreammode3)[2/2] - `startChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelay` - `updateChannelMediaRelayEx` - `onChannelMediaRelayEvent` - `CHANNEL_MEDIA_RELAY_EVENT` #### 删除 [#删除-18] - `startPrimaryScreenCapture` - `startSecondaryScreenCapture` - `stopPrimaryScreenCapture` - `stopSecondaryScreenCapture` - `startPrimaryCameraCapture` - `startSecondaryCameraCapture` - `stopPrimaryCameraCapture` - `stopSecondaryCameraCapture` - `onSecondaryPreEncodeCameraVideoFrame` - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame ` - `onSecondaryPreEncodeScreenVideoFrame` - `onApiCallExecuted` - `ChannelMediaOptions `中的` publishCustomAudioTrackEnableAec` - `getMediaRecorder` - [`IMediaRecorder`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediarecorder) 类中的 `release` - `AGORA_IID_MEDIA_RECORDER` - [`startRecording`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_imediarecorder_startrecording)、[`stopRecording`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/cpp-all-platforms/recording#api_imediarecorder_setmediarecorderobserver) 中删除 `connection` 参数 ## v4.1.1 [#v411-4] 该版本于 2023 年 2 月 8 日发布。 ### 升级必看 [#升级必看-56] 自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。 如果你想自定义视频编码分辨率，可调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法，重新设置视频编码参数配置中的视频编码分辨率。 :::info[信息] 由于默认分辨率的提升，会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: ### 新增特性 [#新增特性-81] #### 快速出图出声 [#快速出图出声-3] 该版本新增 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_enableinstantmediarendering) 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。 #### 视频渲染数据打点 [#视频渲染数据打点-3] 该版本新增 [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_startmediarenderingtracing) 和 [`startMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告相关事件的信息。 声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。 ### 改进 [#改进-96] #### 视频观测器 [#视频观测器-3] 自该版本起，SDK 对 [`onRenderVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 回调进行了优化，在不同的视频处理模式下返回值的意义不同： - 当视频处理模式为 `PROCESS_MODE_READ_ONLY` 时，返回值无实际含义。 - 当视频处理模式为 `PROCESS_MODE_READ_WRITE` 时，返回 `true` 代表设置 SDK 接收视频帧；返回 `false` 代表设置 SDK 丢弃视频帧。 ### 问题修复 [#问题修复-99] 该版本修复了以下问题： - 使用媒体播放器播放网络摄像头的 RTSP 码流时，偶现花屏。 - 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。 - 在本地合图场景下，不支持对 PNG 和 GIF 图片的 Alpha 通道渲染，导致透明底色的图片显示为非透明底色。 - 加入频道后添加水印然后删除，远端仍能看到水印。 - 开始屏幕共享后添加水印，远端接收的屏幕共享画面没有水印。 - 加入频道后接入外接摄像头，调用 `setDevice` 指定视频采集设备为该外接摄像头，方法未生效。 - 在屏幕共享场景下，如果将一个窗口设置为前置和描边，则必现窗口前置失败。 - 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。 - 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。 ### API 变更 [#api-变更-54] #### 新增 [#新增-51] - [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_enableinstantmediarendering) - [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_startmediarenderingtracing) - [`startMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) - [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) - [`MEDIA_TRACE_EVENT`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediatraceevent) - [`VideoRenderingTracingInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videorenderingtracinginfo) #### 删除 [#删除-19] - `enableRemoteSuperResolution` - [`RemoteVideoStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-remotevideostats) 中删除 `superResolutionType` ## v4.1.0 [#v410-4] 该版本于 2022 年 12 月 19 日发布。 ### 新增特性 [#新增特性-82] #### 耳机均衡器 [#耳机均衡器-3] 该版本新增 [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) 方法，用于调节耳机均衡器的低频和高频参数，主要应用于空间音频场景。如果在调用 [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。 #### 已编码视频帧观测器 [#已编码视频帧观测器-2] 该版本新增 [`setRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) 和 [`setRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) 方法，当你调用 [`registerVideoEncodedFrameObserver`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-encoded#registervideoencodedframeobserver) 方法为编码后的视频注册视频帧观测器时，SDK 默认订阅编码后的视频帧。如果你想要修改订阅选项，可以调用该新增的方法进行设置。 有关更多注册视频观测器和订阅选项的介绍，详见[API 参考](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-encoded#registervideoencodedframeobserver)。 #### MPUDP (MultiPath UDP) [#mpudp-multipath-udp-3] 自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在移动端和桌面端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。 :::info[信息] 如果你希望体验该功能，请联系 sales@shengwang.cn。 ::: #### 注册插件 [#注册插件] 该版本新增 [`registerExtension`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_registerextension) 方法，用于注册插件。当使用第三方插件时，你需要按照以下顺序调用插件相关的 API： 调用 [`loadExtensionProvider`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_loadextensionprovider) -> [`registerExtension`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_registerextension) -> [`setExtensionProviderProperty`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_setextensionproviderproperty) -> [`enableExtension`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_enableextension)。 #### 设备管理 [#设备管理-1] 该版本新增了一系列回调，帮助你更好地了解音视频设备的状态。 - [`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged)：当视频设备的状态发生改变时上报。 - [`onAudioDeviceStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicestatechanged)：当音频设备的状态发生改变时上报。 - [`onAudioDeviceVolumeChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicevolumechanged)：当音频设备或 App 的音量发生改变时上报。 #### 摄像头采集选项 [#摄像头采集选项-3] 该版本在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-cameracapturerconfiguration) 中增加了 `followEncodeDimensionRatio` 成员，你可以在使用摄像头采集视频时，通过该成员设置是否跟随 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中已经设置的视频宽高比。 #### 多频道管理 [#多频道管理-3] 该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。 - 新增 [`muteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) 和 [`muteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) 方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增 [`muteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) 和 [`muteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) 方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增 [`startRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex)、[`startRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex)、[`updateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) 和 [`stopRtmpStreamEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) 方法，用于实现多频道场景下的旁路推流。 - 新增 `startChannelMediaRelayEx`、`updateChannelMediaRelayEx`、[`pauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex)、[`resumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) 和 [`stopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) 方法，用于实现多频道场景下的跨频道媒体流转发。 - 新增 [`leaveChannelEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_leavechannelex2)[2/2] 方法，相较于[`leaveChannelEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_leavechannelex)[1/2] 方法新增了 `options` 参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。 #### 视频编码偏好 [#视频编码偏好-3] 一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoencoderconfiguration) 中新增 `advanceOptions` 成员，用于视频编码属性的进阶设置： - `compressionPreference`：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。 - `encodingPreference`：视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。 #### 日志上传 [#日志上传-3] 使用声网私有媒体服务器的场景下，为支持用户在调用 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_setlocalaccesspoint) 方法时的进阶设置，该版本在 [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-localaccesspointconfiguration) 结构体中新增 `advancedConfig` 成员参数，该参数支持如下设置： `logUploadServer`：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。 #### 用户角色切换 [#用户角色切换-3] 为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 [`onClientRoleChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调中新增 `newRoleOptions` 参数，该参数取值如下： - `AUDIENCE_LATENCY_LEVEL_LOW_LATENCY`(1): 低延时，属于极速直播。 - `AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY`(2): 超低延时，属于互动直播。 ### 改进 [#改进-97] #### 屏幕共享 [#屏幕共享-5] 该版本对屏幕共享功能做了一系列优化，除以下列出的功能性改进之外，还有一部分可用性提升，详见[问题修复](#windows-v4.1.0-bugfix)。 - 在 [`ScreenCaptureSourceInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-screencapturesourceinfo) 中增加了 `minimizeWindow` 成员，用于表示目标窗口是否已最小化。 - 在 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-screencaptureparameters) 中增加了 `enableHighLight`、`highLightColor` 和 `highLightWidth` 成员，支持你在屏幕共享时对目标窗口或屏幕进行描边。 - 兼容更多主流 App，包括但不限于：WPS Office，Microsoft Office PowerPoint，Visual Studio Code，Adobe Photoshop，Windows Media Player，Scratch。 - 兼容更多设备和操作系统，包括但不限于：Windows 8 系统，无独立显卡的设备，双显卡设备。 - 支持超高清视频 (分辨率为 4K，帧率为 60 fps)，你可以在满足要求的设备上使用该功能。声网推荐的最低设备规格为：intel(R) Core(TM) i7-9750H CPU @ 2.60GHZ。 #### CDN 推流 [#cdn-推流-3] 为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 `onDirectCdnStreamingStats` 回调报告推送的视频流的实际分辨率。 #### 跨频道媒体流转发 [#跨频道媒体流转发-7] 该版本对 `updateChannelMediaRelay` 方法做了如下优化： - 4.1.0 版本前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码 `RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED`(8)，你需要重新调用 `updateChannelMediaRelay` 方法。 - 4.1.0 版本及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。 #### AIAEC [#aiaec-3] 该版本基于 AI 方法重构了 AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。 #### 虚拟背景 [#虚拟背景-3] 该版本对虚拟背景算法做了如下优化： - 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。 - 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。 - 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。 - 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。 #### 其他改进 [#其他改进-39] - 降低了推送外部音频源时的上行延迟。 - 提升了会议场景 (`AUDIO_SCENARIO_MEETING`) 默认参数配置下的回声消除性能。 - 提升了 SDK 视频渲染的流畅度。 - 降低了当主播调用 [`muteLocalVideoStream`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalvideostream) 方法时本地设备的 CPU 占用率和耗电量。 - 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。 ### 问题修复 [#问题修复-100] 该版本修复了以下问题： - 在屏幕共享场景下，将共享的窗口最小化时，偶现远端用户出现黑屏或远端画面切换为视频小流。 - 在直播场景下，主播开启屏幕共享时，偶现观众听主播说话有回声。 - 在屏幕共享场景下偶现系统声音音量变小。 - 在屏幕共享场景下，在横屏显示器与竖屏显示器之间共享屏幕时出现黑屏。 - 在屏幕共享场景下屏蔽窗口时，屏幕共享区域超出屏幕分辨率导致崩溃。 - 调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 进行屏幕共享时无法屏蔽窗口。 - 在屏幕共享场景下，远端用户看到的画面偶现黑屏、卡顿、崩溃。 - 在屏幕共享场景下，偶现 [`onNetworkQuality`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onnetworkquality) 回调报告频道内指定用户的上下行网络状态不准确。 - 在屏幕共享场景下，在共享窗口中看到的鼠标位置与实际位置有偏差。 - 从普通场景切换屏幕共享场景后，由于两种场景下设置的分辨率不同导致偶现崩溃。 - 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。 - [`onVideoPublishStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 回调报告的视频源类型不准确。 - 调用 [`getExtensionProperty`](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_getextensionproperty2) 失败，返回空字符串。 - 当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。 ### API 变更 [#api-变更-55] #### 新增 [#新增-52] - [`enableAudioVolumeIndicationEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengineex_enableaudiovolumeindicationex) - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) - [`setRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) - [`setRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) - [`leaveChannelEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_leavechannelex2)[2/2] - [`VideoSubscriptionOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videosubscriptionoptions) - [`muteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) - [`muteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) - [`muteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) - [`muteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) - [`startRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex) - [`startRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex) - [`updateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) - [`stopRtmpStreamEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - [`pauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex) - [`resumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) - [`stopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-cameracapturerconfiguration) 中增加 `followEncodeDimensionRatio` - [`LocalVideoStats`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-localvideostats) 中增加 `hwEncoderAccelerating` - [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoencoderconfiguration) 中增加 `advanceOptions` 成员 - [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-localaccesspointconfiguration) 中增加 `advancedConfig` 成员 - [`onClientRoleChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#callback_irtcengineeventhandler_onclientrolechanged) 中增加 `newRoleOptions` - [`adjustUserPlaybackSignalVolumeEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengineex_adjustuserplaybacksignalvolumeex) - [`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) - [`onAudioDeviceStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicestatechanged) - [`onAudioDeviceVolumeChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicevolumechanged) - [`IRtcEngine`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 类中的 `setParameters` #### 废弃 [#废弃-18] - `onApiCallExecuted`，改用具体方法触发的回调 #### 删除 [#删除-20] - `onChannelMediaRelayEvent` 中删除 `RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED`(8) ## v4.0.1 [#v401-4] 该版本于 2022 年 9 月 29 日发布。 ### 升级必看 [#升级必看-57] 如果你已经使用了以下类或方法，请在升级到该版本后重新调用方法并更新参数设置。 删除了 `enableDualStreamMode`[3/3] 和 [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_enabledualstreammodeex) 中的 `sourceType` 参数以及 `enableDualStreamMode`[2/3] 方法，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。 ### 新增特性 [#新增特性-83] #### 耳返 [#耳返-3] 该版本新增耳返功能。你可以调用 [`enableInEarMonitoring`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_enableinearmonitoring2) 开启耳返功能。 成功开启耳返功能后，你可以调用 [`registerAudioFrameObserver`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#registeraudioframeobserver) 注册音频观测器，SDK 会触发 [`onEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#onearmonitoringaudioframe) 回调报告耳返原始音频数据。你可以使用自己的音效处理模块对耳返音频数据进行前处理，实现自定义音效，声网推荐你在如下两种方式中选其一来设置耳返音频数据格式： - 调用 [`setEarMonitoringAudioFrameParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#api_irtcengine_setearmonitoringaudioframeparameters) 方法设置耳返音频数据格式，SDK 会根据该方法中的参数计算采样间隔，并根据该采样间隔触发 [`onEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#onearmonitoringaudioframe) 回调。 - 在 [`getEarMonitoringAudioParams`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#getearmonitoringaudioparams) 回调的返回值中设置耳返音频数据格式，SDK 会根据该回调的返回值计算采样间隔，并根据该采样间隔触发 [`onEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#onearmonitoringaudioframe) 回调。 如需调节耳返音量，你可以调用 [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_setinearmonitoringvolume)。 #### 本地网络连接类型 [#本地网络连接类型-3] 为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 [`getNetworkType`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_getnetworktype) 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 [`onNetworkTypeChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#callback_irtcengineeventhandler_onnetworktypechanged) 回调，报告当前的网络连接类型。 #### 音强选流 [#音强选流-3] 该版本新增音强选流功能。该功能开启后，声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请联系[技术支持](https://ticket.shengwang.cn/)。 同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗，详见[音强选流](/zh-CN/realtime-media/rtc/build/audio/audio-stream-filter)。 :::info[信息] 如需开启该功能，请联系[技术支持](https://ticket.shengwang.cn/)。 ::: #### 双流模式 [#双流模式-4] 该版本对双流模式做了优化，在加入频道前后均可调用 `enableDualStreamMode` 和 `enableDualStreamModeEx`。 扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式（即：默认不主动发送小流），可通过以下步骤开启发送小流： 1. 接收端主播调用 [`setRemoteVideoStreamType`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setremotevideostreamtype) 或 [`setRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 发起接收小流申请。 2. 发送端收到申请后自动切换为发送小流模式。 如果你想修改上述发送端的默认行为，可以调用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setdualstreammode)[1/2] 或 [`setDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2] 方法，将 `mode` 参数设置为 `DISABLE_SIMULCAST_STREAM`（始终不发送小流）或 `ENABLE_SIMULCAST_STREAM`（始终发送小流）。 #### 声卡采集设备 [#声卡采集设备] SDK 默认使用播放设备为声卡采集设备，自该版本起，你可以另外指定声卡采集设备并将其采集到的音频发布到远端。 - [`setLoopbackDevice`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_setloopbackdevice)：用于指定声卡采集设备，当你不希望当前的播放设备为声卡采集设备时，可以调用该方法另外指定别的设备作为声卡采集设备。 - [`getLoopbackDevice`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_getloopbackdevice)：用于获取当前的声卡采集设备。 - [`followSystemLoopbackDevice`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_followsystemloopbackdevice)：用于设置声卡采集设备是否跟随系统默认的播放设备。 #### 空间音频 [#空间音频-6] 该版本新增了如下适用于空间音频场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。 - 隔声区域：你可以通过调用 [`setZones`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setzones) 设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用 [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setplayerattenuation) 和 [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) 方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖 [`setZones`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setzones) 中的声音衰减系数。 - 多普勒音效：你可以通过设置 [`SpatialAudioParams`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-spatialaudioparams) 中的 `enable_doppler` 参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下（比如赛车游戏场景），接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用 [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 方法使用预设的耳机均衡效果，以改善耳机的听感。 ### 改进 [#改进-98] #### 视频信息发生改变回调 [#视频信息发生改变回调-3] 该版本优化了 [`onVideoSizeChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged) 的触发逻辑，当单独调用 `startPreview` 时，也可触发该回调并上报本地视频大小发生改变。 #### 首帧出图 [#首帧出图] 该版本缩短了首帧出图时间，以提升用户视频体验。 ### 问题修复 [#问题修复-101] 该版本修复了以下问题： 1. 调用 `stopPreview` 关闭本地视频预览时，导致已设置的虚拟背景一定概率失效。 2. 开启虚拟背景并设置为背景虚化效果时，多次退出频道再加入频道时偶现崩溃。 3. 本地端使用 1920 x 1080 的摄像头作为视频采集源，偶现远端视频的分辨率与本地端不一致。 4. 通过摄像头采集视频时，如果在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-cameracapturerconfiguration) 中设置的视频宽高比例和在 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中设置的不一致，导致本地视频预览的画面比例未按照后者的设置呈现。 5. 在频道内调用 [`setVideoEncoderConfigurationEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengineex_setvideoencoderconfigurationex) 将视频的分辨率调高时，偶现失效。 6. 使用媒体播放器播放视频，先调用 [`play`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 再调用 [`pause`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用 [`resume`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_resume) 恢复播放后，偶现视频画面出现快进。 ### API 变更 [#api-变更-56] #### 新增 [#新增-53] - [`enableInEarMonitoring`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_enableinearmonitoring2) - [`setEarMonitoringAudioFrameParameters`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#api_irtcengine_setearmonitoringaudioframeparameters) - [`onEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#onearmonitoringaudioframe) - [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) - [`getEarMonitoringAudioParams`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-raw#getearmonitoringaudioparams) - [`getNetworkType`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_getnetworktype) - [`setRecordingDeviceVolume`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_setrecordingdevicevolume) - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中新增 `isAudioFilterable` - [`setDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setdualstreammode)[1/2] - [`setDualStreamMode`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2] - [`setDualStreamModeEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_setdualstreammodeex) - [`SIMULCAST_STREAM_MODE`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-simulcaststreammode) - [`setLoopbackDevice`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_setloopbackdevice) - [`getLoopbackDevice`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_getloopbackdevice) - [`followSystemLoopbackDevice`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/audio-device#api_iaudiodevicemanager_followsystemloopbackdevice) - [`setZones`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setzones) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#setplayerattenuation) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) - `muteRemoteAudioStream` - [`SpatialAudioParams`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-spatialaudioparams) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) - [`HEADPHONE_EQUALIZER_PRESET`](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-headphoneequalizerpreset) #### 修改 [#修改-12] - `enableDualStreamMode`[3/3] - [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengineex_enabledualstreammodeex) #### 废弃 [#废弃-19] - `startEchoTest`[2/3] #### 删除 [#删除-21] - `enableDualStreamMode`[2/3] ## v4.0.0 [#v400-4] 该版本于 2022 年 9 月 13 日发布。 ### 升级必看 [#升级必看-58] #### 兼容性变更 [#兼容性变更-2] v4.0.0 SDK 对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见[迁移指南](/zh-CN/realtime-media/rtc/reference/migration-guide)。 - 多频道 - 媒体流发布控制 - 自定义视频采集与渲染（Media IO 方式） - 警告码 ### 新增特性 [#新增特性-84] #### 多路媒体流 [#多路媒体流-3] 该版本通过设置 [`IRtcEngineEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex) 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 实现一个 [`IRtcEngine`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 实例同时采集多组音视频流并发布到远端： - 调用 `joinChannel` 加入首个频道后，多次调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 加入多个频道，通过不同的用户 ID (`localUid`) 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 设置发布指定的流到不同的频道。 - 支持通过设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的 `publishSecondaryCameraTrack` 和 `publishSecondaryScreenTrack` 同时发布多路摄像头采集或者屏幕共享的视频流。 该版本支持通过 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流： 1. 创建自采集视频轨道：调用 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法创建一个自定义视频轨道，并获得视频轨道 ID。 2. 设置频道中待发布的自采集视频轨道：在每个频道的 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中，将 `customVideoTrackId` 参数设置为你想要发布的视频轨道 ID，并将 `publishCustomVideoTrack` 设置为 `true`。 3. 推送外部视频源：调用 [`pushVideoFrame`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-custom-capturenrendering#pushvideoframe)，并将 `videoTrackId` 指定为步骤 2 中指定的视频轨道 ID，即可实现在多个频道中发布对应的自定义视频源。 结合多频道能力，你还可以体验如下功能： - 将多组音视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路音频流混音后通过一个用户 ID (`uid`) 发布到远端。 - 将多组视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路视频流合图后通过一个用户 ID (`uid`) 发布到远端。 #### 超高清分辨率 (Beta) [#超高清分辨率-beta-1] 为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持 4K 分辨率。优化了 FEC（Forward Error Correction）算法，可根据视频帧包数与帧率进行自适应切换，降低 4K 场景下的视频卡顿率。 你可以在调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 时，设置编码分辨率为 4K (3840 × 2160)、帧率为 60 fps。当你的设备不支持 4K 时，SDK 支持自动回退到适合的分辨率和帧率。 :::info[信息] - 该功能对设备性能和网络带宽有一定要求，在不同的平台上支持的上下行帧率也不同，如需体验该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 - 高分辨率可能会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 内置媒体播放器 [#内置媒体播放器-3] 为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 [`createMediaPlayer`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer) 创建媒体播放器后，你可以通过 [`IMediaPlayer`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayer) 类的一系列方法体验内置媒体播放器的各类功能： - 自动播放本地、在线、自定义的媒体资源。 - 预先加载待播放的媒体资源。 - 根据网络情况切换媒体资源的播放线路。 - 将媒体播放器的音视频流推送到任意频道、分享给远端用户。 - 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。 #### 新版 AI 降噪 [#新版-ai-降噪-3] 自该版本起，SDK 支持新版 AI 降噪（相对于 v3.7.0 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。 :::info[信息] 如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。 ::: #### 超高音质 [#超高音质-3] 为还原音频的细节、提升音频的清晰度，该版本新增 `ULTRA_HIGH_QUALITY_VOICE`。在语聊、歌唱等以人声为主的场景中，你可以调用 [`setVoiceBeautifierPreset`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) 并使用该枚举体验超高音质。 #### 空间音频 [#空间音频-7] :::info[信息] 空间音频功能当前处于实验阶段，请联系 sales@shengwang.cn 开通空间音频功能，如果需要技术支持，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: 该版本提供直角坐标系方案实现空间音频： - 使用 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ilocalspatialaudioengine) 类实现空间音频，通过 SDK 计算远端用户的空间坐标。你需要分别调用 [`updateSelfPosition`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#updateselfposition) 和 [`updateRemotePosition`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音频。 ![](https://web-cdn.agora.io/docs-files/1656645542473) - 通过 SDK 计算媒体播放器的空间坐标。你需要在 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ilocalspatialaudioengine) 类中分别调用 [`updateSelfPosition`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#updateselfposition) 和 [`updatePlayerPositionInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-prenpost/spatial-audio#updateplayerpositioninfo) 更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音频。 ![](https://web-cdn.agora.io/docs-files/1656646829637) #### 实时合唱 [#实时合唱-3] 该版本为实时合唱赋予了如下能力： - 支持两人及两人以上合唱。 - 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。 - 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。 该版本新增 `AUDIO_SCENARIO_CHORUS` 枚举来设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。 #### 云市场插件 [#云市场插件-3] 为在声网 SDK 的基础上增强实时音视频互动性，该版本支持[声网云市场](https://www.agora.io/cn/marketplace)插件的一站式解决方案： - 方便集成：只需执行简单统一的 API 即可实现模块化功能的集成，将实时互动模块集成效率提高约 95%。 - 可扩展性设计：模块化和可扩展的 SDK 设计风格赋予了声网 SDK 良好的可扩展性，更有利于开发者基于声网云市场插件生态快速搭建好用的实时互动应用。 - 打造生态系统：可容纳众多开发者的实时音视频 App 社区，提供多种扩展组合。添加并开启云市场插件后，开发者可以实现更为丰富的实时音视频互动功能。 - 助力服务商：支持服务商将技术产品以插件的形式与声网 SDK 做技术上的融合，在声网云市场中展示并售卖，与声网一起共建开发者的实时互动生态系统，详见[云市场文档](/zh-CN/realtime-media/marketplace)。 #### 增强的频道管理 [#增强的频道管理-3] 为满足各类业务场景对频道管理的需求，该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 结构体中新增了如下功能： - 设置或切换多种音视频源的发布 - 设置或切换频道场景、用户角色 - 设置或切换订阅视频的大小流类型 - 控制音频发布时延 在调用 `joinChannel` 或 [`joinChannelEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 时设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions)，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_updatechannelmediaoptions) 随时更新 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中的设置，例如，切换发布的音视频源。 #### 屏幕共享 [#屏幕共享-6] 该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享： - 在加入频道前调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapturebydisplayid)，然后调用 [`joinChannel`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_joinchannel2)[2/2] 加入频道并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `true`，即可开始屏幕共享。 - 在加入频道后调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/screencapture#api_irtcengine_startscreencapturebydisplayid)，然后调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_updatechannelmediaoptions) 设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `true`，即可开始屏幕共享。 #### 设置音视频流订阅黑/白名单 [#设置音视频流订阅黑白名单-3] 该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通过 [`IRtcEngineEx`](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex) 类下的同名方法来实现该功能。 - `setSubscribeAudioBlacklist`：设置音频订阅黑名单。 - `setSubscribeAudioWhitelist`：设置音频订阅白名单。 - `setSubscribeVideoBlacklist`：设置视频订阅黑名单。 - `setSubscribeVideoWhitelist`：设置视频订阅白名单。 如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。 #### 设置音频场景 [#设置音频场景-3] 为方便用户灵活修改音频场景，该版本新增 [`setAudioScenario`](/zh-CN/api-reference/rtc/cpp-all-platforms/audio/audio-basic#api_irtcengine_setaudioscenario) 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (`AUDIO_SCENARIO_DEFAULT`) 切换为高音质场景 (`AUDIO_SCENARIO_GAME_STREAMING`)，你可以调用该方法。 #### 设置本地代理 [#设置本地代理-3] 该版本新增 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/cpp-all-platforms/network#api_irtcengine_setlocalaccesspoint) 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。 #### 垫片推流 [#垫片推流-3] 该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 来开启该功能，并通过 `options` 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。 #### 本地合图 [#本地合图-5] 该版本新增本地合图功能，可支持在本地将多路视频流合并为一路视频流。常见场景如下： 在直播场景或使用旁路推流功能时，可以在本地将多个主播的画面合并为一个画面。 将本地采集的多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）合并为一路视频流，然后在频道内发布已合图的视频流。 你可以调用 [`startLocalVideoTranscoder`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) 方法开启本地合图、调用 [`stopLocalVideoTranscoder`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/local-transcoder#api_irtcengine_stoplocalvideotranscoder) 方法停止本地合图；在开启本地合图后，可以调用 [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 进行本地合图的配置更新。 #### 视频设备管理 [#视频设备管理] 视频采集设备可能支持多种视频格式，每一种格式都支持不同的视频帧宽度、视频帧高度、帧率组合。 该版本新增 [`numberOfCapabilities`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_ivideodevicemanager_numberofcapabilities) 和 [`getCapability`](/zh-CN/api-reference/rtc/cpp-all-platforms/device-management/video-device#api_ivideodevicemanager_getcapability) 方法，用于获取视频采集设备支持的视频格式数量以及指定视频格式下的视频帧详细信息。在调用 `startPrimaryCameraCapture` 或 `startSecondaryCameraCapture` 方法使用摄像头采集视频时，你可以使用指定的视频格式进行采集。 :::info[信息] SDK 会根据你在 `VideoEncoderConfiguration` 中的设置，自动选择选择视频采集设备的最佳视频格式进行采集。一般情况下，你不需要用到该组新增方法。 ::: ### 改进 [#改进-99] #### 快速切换频道 [#快速切换频道-3] 该版本通过 `leaveChannel` 和 `joinChannel` 切换频道即可实现和 v3.7.0 中 `switchChannel` 一样的切换速度，无需额外调用 `switchChannel` 方法。 #### 推送外部视频帧 [#推送外部视频帧-3] 该版本新增支持推送 I422 格式的外部视频帧，你可以通过 `pushVideoFrame`[1/2] 方法将 I422 格式的外部视频帧推送至 SDK。 #### 本地人声音调 [#本地人声音调-3] 该版本在 `onAudioVolumeIndication` 的 [`AudioVolumeInfo`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-audiovolumeinfo) 中新增 `voicePitch` 参数。你可以通过 `voicePitch` 获取本地用户的人声音调，从而实现唱歌评分等业务功能。 #### 本地视频预览 [#本地视频预览-3] 该版本优化了 `startPreview` 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 `startPreview` 方法来开启视频预览，无调用时序要求。 #### 订阅视频流 [#订阅视频流-3] 你可以通过 [`setRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。 ## v4.2.1 [#v421-5] 该版本于 2023 年 6 月 21 日发布。 ### 改进 [#改进-100] 该版本改进了网络传输策略，提升了音视频交互的流畅度。 ### 问题修复 [#问题修复-102] 该版本修复了以下问题： - SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。 - 发送端调用 `SetAINSMode` 开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。 - 发送端将两路摄像头采集的视频进行本地合图并发布后，接收端偶现第二路摄像头画面缺失。 ## v4.2.0 [#v420-5] 该版本于 2023 年 5 月 26 日发布，是 C# SDK 的第一个版本。 **功能简介** 该版本基于 RTC Windows SDK v4.2.0 封装，功能特性详见 C++ 发版说明。 **参考文档** 你可以参考以下文档集成 SDK，实现相应的实时音视频功能： - [实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start) - [实现纯语音互动](/zh-CN/realtime-media/rtc/build/audio/audio-quick-start) - [实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start) - [API 参考](/zh-CN/api-reference/rtc/csharp-windows/rtc-api-overview) 声网在 GitHub 提供一个开源的 [CSharp API Example](https://github.com/AgoraIO-Extensions/Agora-C_Sharp-SDK/tree/master/APIExample) 示例项目，你也可以前往下载并体验。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="harmonyos" /> ## v4.6.3 [#v463-harmonyos] 该版本于 2026 年 9 月 20 日发布。 ### 升级必看 [#升级必看-59] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### playEffect 和 preloadEffect 改为异步方法 [#playeffect-和-preloadeffect-改为异步方法] 为避免连续播放网络音效时阻塞主线程，该版本将 [`playEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_playeffect3) 和 [`preloadEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_preloadeffect) 改为异步方法，返回 `Promise`。如果你的 App 中调用了这两个方法，请按异步方式处理返回值。 #### VideoFrame 变更 [#videoframe-变更] - `yStride` 更名为 `stride`，含义不变，仍表示视频帧的行跨度。 - `buffer` 的类型由 `ArrayBuffer | null` 变更为 `ArrayBuffer | undefined`。 如果你的 App 中使用了上述成员变量，请相应更新代码。 #### 冗余接口和参数删除 [#冗余接口和参数删除] 该版本删除了下列参数： - [`LiveTranscoding`](/zh-CN/api-reference/rtc/harmonyos/class-livetranscoding#class_livetranscoding).`metadata`（该属性已废弃） ### 新增特性 [#新增特性-85] #### 语聊房和合唱音频场景 [#语聊房和合唱音频场景] 该版本在 [`setAudioScenario`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-basic#api_irtcengine_setaudioscenario) 方法的音频场景中新增 `CHATROOM` 和 `CHORUS`。其中，`CHORUS` 场景支持低延迟采集模式。 #### 人声音效 [#人声音效] 该版本新增人声音效能力，你可以根据需求调用以下方法： - [`setLocalVoicePitch`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch)：调节本地人声的音调。 - [`setLocalVoiceEqualization`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceequalization)：调节本地人声的均衡器。 - [`setLocalVoiceReverb`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicereverb)：调节本地人声的混响。 - [`setAudioEffectPreset`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset)：使用预设音效，支持浴室、楼梯间和自然环境等场景的混响效果。 - [`setVoiceBeautifierPreset`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset)：使用人声美化预设。 #### 版权音乐 [#版权音乐-2] 该版本新增版权音乐支持。你可以通过 [`IAgoraMusicContentCenter`](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_imusiccontentcenter) 管理音乐资源，并通过 [`IAgoraMusicPlayer`](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_imusicplayer) 播放音乐。相关接口详见[版权音乐 API](/zh-CN/api-reference/rtc/harmonyos/play/drm)。 #### 观众本地预览截图 [#观众本地预览截图] 该版本支持观众角色在加入频道后开启本地预览，并调用 [`takeSnapShotEx`](/zh-CN/api-reference/rtc/harmonyos/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 进行本地视频截图。 #### 播放系统文件选择器中的媒体文件 [#播放系统文件选择器中的媒体文件] 该版本支持通过 [`IMediaPlayer`](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_imediaplayer) 播放系统文件选择器获取的媒体文件。你可以将文件选择器返回的 URI 传入播放器打开并播放，不再局限于应用沙箱内的文件路径。 #### 基础美颜 [#基础美颜] 该版本新增 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/harmonyos/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions)，用于开启或关闭美颜效果并配置美颜参数。 #### 垫片推流 [#垫片推流-4] 该版本新增 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/harmonyos/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource)，用于开启或关闭图片源推流，并新增 [`ImageTrackOptions`](/zh-CN/api-reference/rtc/harmonyos/class-imagetrackoptions#class_imagetrackoptions) 配置类型。 #### 音效文件播放 [#音效文件播放] 在此前已支持的 `playEffect`、`stopEffect` 等音效文件播放能力基础上，该版本新增音效预加载、音量管理、多音效控制、暂停/恢复和批量卸载能力，包括 [`getEffectsVolume`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_geteffectsvolume)、[`setEffectsVolume`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_seteffectsvolume)、[`setVolumeOfEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_setvolumeofeffect)、[`playAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_playalleffects)、[`pauseEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_pauseeffect)、[`pauseAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_pausealleffects)、[`resumeEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_resumeeffect)、[`resumeAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_resumealleffects)、[`stopAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_stopalleffects)、[`unloadEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_unloadeffect)、[`unloadAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_unloadalleffects) 和 [`getVolumeOfEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_getvolumeofeffect)。`preloadEffect` 的异步调用方式详见“升级必看”。 #### 本地音频设备测试 [#本地音频设备测试] 该版本新增 [`startRecordingDeviceTest`](/zh-CN/api-reference/rtc/harmonyos/device-management/audio-device#api_iaudiodevicemanager_startrecordingdevicetest) 和 [`stopRecordingDeviceTest`](/zh-CN/api-reference/rtc/harmonyos/device-management/audio-device#api_iaudiodevicemanager_stoprecordingdevicetest) 方法，用于启动或停止本地录音设备测试。 #### 其他 [#其他-20] - 新增 [`enableEncryptionEx`](/zh-CN/api-reference/rtc/harmonyos/network#api_irtcengineex_enableencryptionex) 方法，用于多频道场景下开启或关闭媒体流加密。 - 新增 [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/harmonyos/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) 方法，用于设置音乐文件的播放速度。 - 新增 [`getCallIdEx`](/zh-CN/api-reference/rtc/harmonyos/network#api_irtcengineex_getcallidex) 方法，用于多频道场景下获取通话 ID。 - 新增 [`muteRecordingSignal`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-capture#api_irtcengine_muterecordingsignal) 方法，用于设置是否将录音信号静音。 - 新增 [`onAudioRouteChanged`](/zh-CN/api-reference/rtc/harmonyos/device-management/audio-route#callback_irtcengineeventhandler_onaudioroutechanged) 回调，用于监听音频路由的变化。 - 新增 [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/harmonyos/network#api_irtcengine_getntpwalltimeinms) 方法，用于获取当前 NTP 时间。 - 新增 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/harmonyos/network#api_irtcengine_setremotesubscribefallbackoption) 方法，用于设置弱网环境下订阅的音视频流回退选项。 ### 改进 [#改进-101] 该版本包含以下改进： - 提升在手机前后置摄像头、PC 和平板设备上开启 [`enableFaceDetection`](/zh-CN/api-reference/rtc/harmonyos/video/video-prenpro/face-detection#api_irtcengine_enablefacedetection) 时的人脸检测准确性。 - 优化重力传感器监听，提升手机旋转时应用界面与摄像头画面同步旋转的效率。 - 优化平板设备的本地摄像头画面渲染方向。 - 新增鸿蒙电视设备适配。 - 新增鸿蒙设备低延迟耳返支持。 ### 问题修复 [#问题修复-103] 该版本修复了以下问题： - 修复通过 [`startScreenCapture`](/zh-CN/api-reference/rtc/harmonyos/video/screencapture#api_irtcengine_startscreencapture) 进行屏幕共享时旋转手机导致远端共享画面缩小的问题。 - 修复音频路由切换不正确的问题。 - 修复私有化场景下 `setLocalAccessPoint` 无法正常使用的问题。 - 修复调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/harmonyos/video/video-rendering#api_irtcengine_setuplocalvideo) 切换本地渲染大小窗时有概率导致崩溃的问题。 - 修复屏幕共享过程中应用切换到后台时有概率发生崩溃的问题。 - 修复 C++ 层调用 [`pushExternalVideoFrame`](/zh-CN/api-reference/rtc/harmonyos/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe4) 推送纹理格式视频帧不能正常工作的问题。 - 修复通话被来电打断后音频路由未能正确恢复的问题。 - 修复获取本地 IP 地址时偶现崩溃的问题。 - 修复折叠屏设备反复折叠后有概率导致摄像头无法正常打开的问题。 - 修复 PC 通话过程中摄像头被系统占用结束后，SDK 无法恢复摄像头采集的问题。 - 修复第三方应用播放声音时，远端声音音量过小的问题。 - 修复应用退到后台后被第三方应用抢占音频播放设备，回到前台后播放无声的问题。 - 修复使用蓝牙耳机时声音偶现断断续续的问题。 - 修复 2K 高分辨率视频硬解码时有概率卡死的问题。 - 修复应用切后台时切换到蓝牙设备，回到前台后蓝牙耳机无法正常采集的问题。 - 修复纹理自采集场景下通话画面偶现闪屏的问题。 ### API 变更 [#api-变更-57] #### 新增 [#新增-54] - [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/harmonyos/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) - [`enableVideoImageSource`](/zh-CN/api-reference/rtc/harmonyos/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) - [`ImageTrackOptions`](/zh-CN/api-reference/rtc/harmonyos/class-imagetrackoptions#class_imagetrackoptions) - [`preloadEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_preloadeffect) - [`playAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_playalleffects) - [`pauseEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_pauseeffect) - [`pauseAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_pausealleffects) - [`resumeEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_resumeeffect) - [`resumeAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_resumealleffects) - [`stopAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_stopalleffects) - [`unloadEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_unloadeffect) - [`unloadAllEffects`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_unloadalleffects) - [`getEffectsVolume`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_geteffectsvolume) - [`setEffectsVolume`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_seteffectsvolume) - [`getVolumeOfEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_getvolumeofeffect) - [`setVolumeOfEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_setvolumeofeffect) - [`setLocalVoicePitch`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch) - [`setLocalVoiceEqualization`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceequalization) - [`setLocalVoiceReverb`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicereverb) - [`setAudioEffectPreset`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-prenpost/audio-effect#api_irtcengine_setaudioeffectpreset) - [`setVoiceBeautifierPreset`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) - [`AudioEffectPreset`](/zh-CN/api-reference/rtc/harmonyos/enum-audioeffectpreset#enum_audioeffectpreset) - [`VoiceBeautifierPreset`](/zh-CN/api-reference/rtc/harmonyos/enum-voicebeautifierpreset#enum_voicebeautifierpreset) - [`onAudioRouteChanged`](/zh-CN/api-reference/rtc/harmonyos/device-management/audio-route#callback_irtcengineeventhandler_onaudioroutechanged) - [`startRecordingDeviceTest`](/zh-CN/api-reference/rtc/harmonyos/device-management/audio-device#api_iaudiodevicemanager_startrecordingdevicetest) - [`stopRecordingDeviceTest`](/zh-CN/api-reference/rtc/harmonyos/device-management/audio-device#api_iaudiodevicemanager_stoprecordingdevicetest) - [`muteRecordingSignal`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-capture#api_irtcengine_muterecordingsignal) - [`enableEncryptionEx`](/zh-CN/api-reference/rtc/harmonyos/network#api_irtcengineex_enableencryptionex) - [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/harmonyos/network#api_irtcengine_getntpwalltimeinms) - [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/harmonyos/network#api_irtcengine_setremotesubscribefallbackoption) - [`setAudioScenario`](/zh-CN/api-reference/rtc/harmonyos/audio/audio-basic#api_irtcengine_setaudioscenario) 新增 `CHATROOM` 和 `CHORUS` #### 修改 [#修改-13] - [`playEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_playeffect3) 和 [`preloadEffect`](/zh-CN/api-reference/rtc/harmonyos/play/audio-effect-file#api_irtcengine_preloadeffect) 改为异步方法，返回 `Promise` - [`VideoFrame`](/zh-CN/api-reference/rtc/harmonyos/class-videoframe#class_videoframe).`yStride` 更名为 `stride` - [`VideoFrame`](/zh-CN/api-reference/rtc/harmonyos/class-videoframe#class_videoframe).`buffer` 类型由 `ArrayBuffer | null` 变更为 `ArrayBuffer | undefined` - [`MediaPlayer`](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_imediaplayer) 支持打开 HarmonyOS 系统的 URL 和 URI #### 删除 [#删除-22] - [`LiveTranscoding`](/zh-CN/api-reference/rtc/harmonyos/class-livetranscoding#class_livetranscoding).`metadata` ## v4.4.2 [#v442] 该版本于 2024 年 11 月 29 日发布。 ### 升级必看 [#升级必看-60] - 该版本将访问区域（`areaCode`）的默认值从 `GLOB` 变更为 `CN`。 ### 新增特性 [#新增特性-86] - 该版本新增 `setEnableSpeakerphone` 方法，支持设置是否使用扬声器播放。 ### 问题修复 [#问题修复-104] 该版本修复了以下问题： - `isSpeakerphoneEnabled` 回调返回结果不准确。 - 在鸿蒙 NEXT 0.0.107 系统的设备上，调用 `leaveChannel` 后偶现崩溃。 ## v4.4.1 [#v441-1] 该版本于 2024 年 10 月 24 日发布，适配 HarmonyOS NEXT Release 版本，确保其在最新操作系统上的兼容性和性能表现。 ### 升级必看 [#升级必看-61] 该版本对 SDK 进行了以下优化和变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 - 包名变更为 `@shengwang/rtc-full`（视频 SDK）或 `@shengwang/rtc-voice`（音频 SDK），请在添加依赖项和导入 SDK 组件的代码处修改包名，详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)或[实现纯语音互动](/zh-CN/realtime-media/rtc/build/audio/audio-quick-start)。 - HAR 包变更为字节码格式，你需要在 `build-profile.json5` 项目文件中增加以下编译选项： ```json "products": [ { "name": "default", "signingConfig": "default", "compatibleSdkVersion": "5.0.0(12)", "runtimeOS": "HarmonyOS", // highlight-start "buildOption": { "strictMode": { "useNormalizedOHMUrl": true } } // highlight-end } ], ``` ### 新增特性 [#新增特性-87] 该版本包含以下新增特性： - SDK 中包含 C/C++ 头文件，你可以在项目中直接使用 C/C++ 语言开发，无需另外拷贝。 - 支持内置媒体播放器和播放版权音乐功能。 ### 改进 [#改进-102] 该版本包含以下改进： - 提升了视频解码的流畅度。 - 优化了音频路由切换的体验。 - 提升了视频解码器的稳定性。 ### 问题修复 [#问题修复-105] 该版本修复了以下问题： - 音视频录制偶现崩溃。 - 偶现 `onVideSizeChanged` 回调无法正常上报。 ## v4.4.0 [#v440-5] 该版本于 2024 年 10 月 8 日发布。 #### 功能简介 [#功能简介] 该 SDK 由声网为开发者设计，旨在为鸿蒙系统的开发者提供简单且用户友好的实时互动解决方案。 SDK 提供了一套强大的 API，使开发者可以轻松构建具备实时音视频互动功能的应用程序，并可以利用鸿蒙系统的独特优势，增强应用的性能和用户体验。通过集成该 SDK，开发者可以快速实现高质量的音视频通话和互动直播等功能，提升应用的互动性和用户粘性。 #### 参考文档 [#参考文档] 你可以参考以下文档集成 SDK，实现相应的实时音视频功能： - [跑通 API 示例项目](/zh-CN/realtime-media/rtc/get-started/run-demo) - [实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start) - [实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start) - [实现纯语音互动](/zh-CN/realtime-media/rtc/build/audio/audio-quick-start) - [API 参考](/zh-CN/api-reference/rtc/harmonyos/rtc-api-overview) 声网提供了开源的[示例项目](https://gitee.com/agoraio-community/API-Examples/tree/main/HarmonyOS)，你可以前往下载并体验。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="mini-program" /> 本文提供声网小程序 SDK 的发版说明。 自 2.5.3 版本起，你需要在小程序的开发设置里将如下域名添加至服务器域名。如果你从 2.4.6 及以下版本升级到 2.5.3 及以上版本，请添加如下域名至服务器域名并删除原域名： ```shell - wss://miniapp.agoraio.cn - https://uap-ap-web-1.agora.io - https://uap-ap-web-2.agoraio.cn - https://uap-ap-web-3.agora.io - https://uap-ap-web-4.agoraio.cn - https://report-ad.agoralab.co - https://rest-argus-ad.agoralab.co ``` 具体步骤详见[配置服务器域名](/zh-CN/realtime-media/rtc/get-started/run-demo#add-ip)。 ## v2.6.5 [#v265] 该版本于 2024 年 8 月 21 日发布。 ### 新增特性 [#新增特性-88] 该版本新增支持 IoT 场景下的加、解密功能。具体的参数设置及加解密类型详见 [API 参考](/zh-CN/api-reference/rtc/mini-program/classes/client#constructor)。 ## v2.6.4 [#v264] 该版本于 2024 年 1 月 11 日发布。 ### 新增特性 [#新增特性-89] 该版本新增了用户网络状态日志上报功能。 ### 问题修复 [#问题修复-106] 该版本修复了反复调用 `join`/`leave` 方法导致的 Client 对象无法复用的问题。 ## v2.6.3 [#v263] 该版本于 2023 年 12 月 22 日发布。 该版本修复了断网情况下调用 `destroy` 方法导致的 Promise 不返回的问题。 ## v2.6.2 [#v262] 该版本于 2023 年 8 月 29 日发布。 该版本修复了收不到跨频道媒体流转发 `channel-media-relay-event` 和 `channel-media-relay-state` 事件的问题。 ## v2.6.1 [#v261] 该版本于 2023 年 3 月 2 日发布。 该版本修复了 WebSocket 连接 `onClose` 方法中 `err` 参数未定义错误。 ## v2.6.0 [#v260] 该版本于 2023 年 2 月 8 日发布。 ### 新增特性 [#新增特性-90] #### 支持 Promise 形式调用 [#支持-promise-形式调用] 该版本起，API 支持 Promise 形式的调用，提升异步代码的易用性。同时也支持原先的 callback 形式的调用。 #### 重构日志模块 [#重构日志模块] 该版本重构优化了日志模块，新增了日志上报功能，从此你无需自主保存 SDK 日志文件。详见 [Log API](/zh-CN/api-reference/rtc/mini-program/interfaces/log)。 #### 支持更多 SDK 集成方式 [#支持更多-sdk-集成方式] SDK 新增支持如下集成方式： - 支持以小程序原生 npm 方式集成 SDK。详见[通过 npm 集成](/zh-CN/realtime-media/rtc/get-started/quick-start#集成-sdk)。 - 支持使用第三方小程序框架（如 [Taro](https://taro-docs.jd.com/docs)，[WePY](https://wepyjs.github.io/wepy-docs)）集成小程序 SDK。 ### 改进 [#改进-103] 该版本进行了如下改进： - 默认用户角色改为 `audience`（观众）。如有需要请调用 [`setRole`](/zh-CN/api-reference/rtc/mini-program/classes/client#setrole) 修改。 - 包体积优化，从 190kb 左右降至 160kb 左右。 ## v2.5.7 [#v257] 该版本于 2022 年 12 月 9 日发布。 ### 新增功能 [#新增功能] 新增了事件监听和数据上报功能，加快问题定位和排查，提升了支持效率。 ### 改进 [#改进-104] 完善了重连机制，更好地保障用户成功加入频道。 ## v2.5.6 [#v256] 该版本于 2022 年 9 月 22 日发布。 ### 新增特性 [#新增特性-91] #### 支持 String 型用户 ID [#支持-string-型用户-id] 该版本新增支持 String 型的用户 ID，方便用户使用 App 账号直接加入声网频道。 为保证通信质量，频道内所有用户需使用同一数据类型的用户 ID，即频道内的所有用户 ID 应同为 Int 型或同为 String 型。详见[如何使用 String 型用户 ID](/zh-CN/reference/faq/integration/string_uid)。 #### 支持 G711 编码格式音频 [#支持-g711-编码格式音频] 小程序 SDK 中，默认发送和接收 Opus 音频数据。对于收发 G711 编码格式音频的 IoT 设备（如 IPC、门铃、手表等），该版本支持双向互通。如需发送和接收 G711 音频数据，请联系 sales@shengwang.cn 开通，开通服务的邮件模板请参照[设置 RTC 小程序 SDK](/zh-CN/realtime-media/rtsa/build/rtc-interoperability/interoperate-rtc#设置-rtc-小程序-sdk)。 ### 改进 [#改进-105] 为提升用户体验，该版本增加了 TypeScript 类型声明文件。 ### API 变更 [#api-变更-58] 该版本新增如下 API： - `setAudioCodec` - 枚举类 `AudioCodec` - 枚举类 `StreamType` - 枚举类 `UidType` 如下 API 在该版本进行了变更： - `join` - `rejoin` - `setRemoteVideoStreamType` ## v2.5.5 [#v255] 该版本于 2022 年 7 月 1 日发布。 ### 改进 [#改进-106] 该版本优化了向声网数据中心上报数据的频次和逻辑，减少了上报请求对正常 http 请求通道的占用。 ## v2.5.4 [#v254] 该版本于 2022 年 5 月 19 日发布。 ### 新增特性 [#新增特性-92] 为帮助你在 App 服务端更好地管理频道内的用户，掌握频道内用户状态，该版本新增 `on(event: "client-banned")` 回调。当你在服务端踢除频道内的用户后，SDK 会触发该回调报告该用户被服务器禁止。 ### 改进 [#改进-107] 该版本优化了弱网环境下音视频的卡顿和网络延迟，提升了视频流畅度。 ### 问题修复 [#问题修复-107] 该版本修复了以下问题： - 在纯语音直播场景下，集成了 Web SDK 的远端用户听到的声音出现卡顿且有杂音。 - 在特定机型上，如 iPhone X、iPhone 12、小米 9，使用小程序加入频道后开启本地音频采集并将采集到的音频流发布到频道内，远端用户听到的声音出现卡顿且有电流声。 - 在弱网情况下，偶现接收端看到视频画面出现马赛克方格。 ### API 变更 [#api-变更-59] 该版本新增如下 API： - `on(event: "client-banned")` - `Client.join` 新增 `isAudioOnly` 参数 - `Client.rejoin` 新增 `isAudioOnly` 参数 ## v2.5.3 [#v253] 该版本于 2021 年 12 月 9 日发布。 ### 新增特性 [#新增特性-93] #### 媒体流订阅选项 [#媒体流订阅选项] 该版本在 `Client.subscribe` 方法中新增 `options` 参数，用于设置是否订阅音频流和视频流。 该方法可以根据需要在通话中多次调用，在订阅音频和/或视频之间灵活切换。 #### 设置订阅的视频流类型 [#设置订阅的视频流类型] 该版本新增 `setRemoteVideoStreamType` 方法，用于设置订阅的视频流类型。当远端用户发送视频双流（大流和小流）时，本地用户可以调用该方法选择订阅大流还是小流。如果不设置，则默认订阅大流。 #### Token 过期回调 [#token-过期回调-1] 为方便用户及时了解 Token 的时效，该版本新增如下回调： - `Client.on("token-privilege-will-expire")`：Token 即将过期回调。SDK 会提前 30 秒触发该回调，提醒 App 更新 Token。收到该回调时，你需要重新在服务端生成新的 Token， 然后调用 `renewToken` 将新生成的 Token 传给 SDK。 - `Client.on("token-privilege-did-expire")`：Token 已过期回调。在 Token 过期后，SDK 会触发该回调。收到该回调时，你需要向服务端重新申请 Token，并调用 `join` 方法传入新的 Token 重新加入频道。 #### 推流/拉流数据上报 [#推流拉流数据上报] 为方便向声网数据中心上报 live-pusher 或 live-player 组件报告的网络或推拉流状态，该版本新增如下方法： - `updatePusherNetStatus`：上报推流过程中的网络状态。 - `updatePusherStateChange`：上报推流状态。 - `updatePlayerNetStatus`：上报拉流过程中的网络状态。 - `updatePlayerStateChange`：上报拉流状态。 ### API 变更 [#api-变更-60] 该版本新增如下 API： - `subscribe` 中新增 `options` 参数 - `setRemoteVideoStreamType` - `renewToken` - `Client.on("token-privilege-will-expire")` - `Client.on("token-privilege-did-expire")` - `updatePusherNetStatus` - `updatePusherStateChange` - `updatePlayerNetStatus` - `updatePlayerStateChange` ## v2.4.6 [#v246] 该版本于 2021 年 1 月 20 日发布。修复了 `wx.connectSocket is not a constructor` 报错问题。 ## v2.4.5 [#v245] 该版本于 2020 年 9 月 21 日发布。 ### 新增功能 [#新增功能-1] 为方便本地了解远端用户的媒体状态，该版本新增 `Client.on("mute-video")` 回调。当远端用户停止发送视频流时，SDK 会触发相应的回调。你还可以从该回调中得知停止发送的远端用户的 ID。 ## v2.4.4 [#v244] 该版本于 2020 年 7 月 7 日发布。增加了对 QQ 小程序的兼容。 ## v2.4.3 [#v243] 该版本于 2020 年 5 月 26 日发布。 ### 新增功能 [#新增功能-2] 跨频道媒体流转发，指将主播的媒体流转发至其他频道，实现主播与其他频道的主播实时互动的场景。该版本新增如下方法，通过将源频道中的媒体流转发至目标频道，实现跨直播间连麦功能： - `startChannelMediaRelay` - `updateChannelMediaRelay` - `stopChannelMediaRelay` 在跨频道媒体流转发过程中，SDK 会通过 `Client.on("channel-media-relay-state")` 和 `Client.on("channel-media-relay-event")` 回调报告媒体流转发的状态和事件。 ## v2.4.2 [#v242] 该版本于 2019 年 12 月 31 日发布。 ### 新增功能 [#新增功能-3] 为方便本地了解远端用户的媒体状态，该版本新增 `Client.on("mute-audio")`。当远端用户停止发送音频流时，SDK 会触发相应的回调。你还可以从该回调中得知停止发送的远端用户的 ID。 ## v2.4.1 [#v241] 该版本于 2019 年 9 月 18 日发布。进行了一些内部优化。 ## v2.4.0 [#v240] 该版本于 2019 年 4 月 30 日发布。新增特性和性能改进详见下文。 ### 新增功能 [#新增功能-4] 为方便用户控制本地是否发流，该版本新增 [`Client.muteLocal`](/zh-CN/api-reference/rtc/mini-program/classes/client#mutelocal) 和 [`Client.unmuteLocal`](/zh-CN/api-reference/rtc/mini-program/classes/client#unmutelocal) 方法。用户可以使用该方法在小程序中实现不发送本地音视频流等功能。 ### 改进 [#改进-108] 该版本针对直播下主播切换为观众的场景，对图像和声音的延迟进行了优化。声网实验室测试结果显示，延迟降低为之前的 20%。 ## v2.3.2 [#v232] 该版本于 2019 年 1 月 3 日发布。新增特性及功能改进详见下文。 ### 新增功能 [#新增功能-5] 为方便用户了解是否成功调用 [`Client.leave`](/zh-CN/api-reference/rtc/mini-program/classes/client#leave) 和 [`Client.destroy`](/zh-CN/api-reference/rtc/mini-program/classes/client#destroy) 方法，该版本分别在这两个方法中新增了方法调用成功或失败的回调函数。 ### 改进 [#改进-109] 为提升 `Client.setRole` 方法的易用性，该版本优化了该方法的调用逻辑。用户在调用 [`Client.join`](/zh-CN/api-reference/rtc/mini-program/classes/client#join) 加入频道**前**或**后**均可以调用该方法，设置或改变用户角色。 同时，该版本对 `broadcaster` 和 `audience` 两个角色的行为进行了更为严格的定义： - 用户角色为 `broadcaster` 时，可以调用 [`Client.publish`](/zh-CN/api-reference/rtc/mini-program/classes/client#publish) 和 [`Client.unpublish`](/zh-CN/api-reference/rtc/mini-program/classes/client#unpublish) 方法 - 用户角色为 `audience` 时，不可以调用 `Client.publish` 和 `Client.unpublish` 方法 ## v1.1.3 BETA [#v113-beta] 该版本于 2018 年 11 月 2 日发布。 ### 问题修复 [#问题修复-108] 修复了偶现的反复加入频道失败的问题，提升了服务的稳定性。 ## v1.1.2 Beta [#v112-beta] 该版本于 2018 年 10 月 22 日发布。新增特性与修复问题列表详见下文。 ### 新增功能 [#新增功能-6] 为方便用户在通话或直播过程中，控制是否订阅远端音视频流，该版本新增如下接口： - `Client.mute`：停止接收远端音视频流 - `Client.unmute`：继续接收远端音视频流 通过使用这两个接口，用户可以选择停止或继续接收音频流、视频流还是音视频流。详细用法见[微信小程序 API 参考](/zh-CN/api-reference/rtc/mini-program/overview)。 ### 改进 [#改进-110] 通过添加如下安全域名，实现高可用策略，提升小程序服务的稳定性： ```shell https://miniapp-1.agoraio.cn https://miniapp-2.agoraio.cn https://miniapp-3.agoraio.cn https://miniapp-4.agoraio.cn ``` ## v1.1.1 Beta [#v111-beta] 该版本于 2018 年 8 月 8 日发布。 ### 新增功能 [#新增功能-7] 为提升互通体验，该版本新增了 `setRole` 接口。当使用场景同时满足以下条件时，小程序 SDK 必须调用该接口将用户角色设置为观众： - 小程序 SDK 与 Native SDK 互通 - Native 端的频道场景为直播场景 - 小程序端作为观众加入频道 ## v1.1.0 Beta [#v110-beta] 该版本于 2018 年 7 月 27 日发布。包含如下功能： - 支持音视频通话及互通直播场景 - 支持万人频道，小程序最多支持 7 个视频画面 - 支持小程序 SDK 与 Native SDK、Web SDK 之间的双向互通。**提供业界最优质的小程序和 Web 互通体验。** 由于小程序基于微信平台搭建，很多功能在实现中会有局限。目前已知的问题和局限如下所示： - 推荐 7 人及 7 人以下的音视频通话或直播场景。频道内人数越少，效果越好。 - 推荐 8 人及 8 人以下的纯音频场景，但是功能上支持到 17 人，对网络要求非常高。频道内人数越少，效果越好。 - 通信场景下，小概率出现远端视频窗口画面旋转的问题。 - 纯音频场景下，如果用户一进频道就禁用麦克风，后加入的用户在你打开麦克风说话前可能无法感知频道内你的存在。 经测试，如下为微信小程序的固有问题，有可能会随微信小程序的版本升级而得到解决： - 由于微信小程序使用 RTMP 协议，弱网情况下，可能会出现音视频快放、声音忽大忽小、偶有回声、推流中断、网络错误等现象。 - 部分 iOS 手机会偶现编码失败，导致远端用户看到黑屏现象。 - 部分 iOS 手机多人互通长时间会出现异常退出微信小程序以及微信崩溃问题。 - 通信或直播过程中，个别手机上会出现摄像头画面卡住的问题。目前监测到该问题的手机有小米 5S。 - 切到微信后台一段时间再返回小程序时，小概率出现问题。 - 正常的音视频或纯语音场景下，不影响正常通话，但测试结论不推荐播放背景音乐，可能会出现声音卡顿、忽大忽小等不可控现象。 - iOS 手机系统为最新的 iOS 12.0 的用户使用微信小程序时，对方看到该用户的窗口必现花屏。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="electron" /> Electron Electron for 统信 OS ## v4.6.2 [#v462-5] 该版本于 2026 年 3 月 5 日发布。 ### 升级必看 [#升级必看-62] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的废弃及删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 直推 CDN 相关接口废弃 [#直推-cdn-相关接口废弃-4] 该版本废弃直推 CDN 功能的相关接口，并会在后续版本中删除，请改用[服务端旁路推流](/zh-CN/realtime-media/media-push)。 - `setDirectCdnStreamingAudioConfiguration` - `setDirectCdnStreamingVideoConfiguration` - `startDirectCdnStreaming` - `stopDirectCdnStreaming` - `DirectCdnStreamingMediaOptions` - `DirectCdnStreamingStats` - `DirectCdnStreamingState` - `DirectCdnStreamingReason` #### 虚拟节拍器接口废弃 [#虚拟节拍器接口废弃-4] 该版本废弃虚拟节拍器功能的相关接口，并会在后续版本中删除。 - [`startRhythmPlayer`](/zh-CN/api-reference/rtc/electron/play/rhythmplayer#api_irtcengine_startrhythmplayer) - [`configRhythmPlayer`](/zh-CN/api-reference/rtc/electron/play/rhythmplayer#api_irtcengine_configrhythmplayer) - [`onRhythmPlayerStateChanged`](/zh-CN/api-reference/rtc/electron/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) #### 水印接口废弃 [#水印接口废弃-4] 该版本废弃水印功能的相关接口，推荐使用该版本新增的水印接口。 - [`addVideoWatermark`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2) - [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex) #### 冗余接口删除 [#冗余接口删除-4] 该版本删除了下列冗余接口及参数： - `setLocalPublishFallbackOption` - `onLocalPublishFallbackToAudioOnly` - `onDownlinkNetworkInfoUpdated` - `onWlAccStats` - `enableWirelessAccelerate` #### 美妆功能实现变更 [#美妆功能实现变更-4] 受该版本美颜重构的影响，自 v4.6.2 起，不再支持调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/electron/extension#api_irtcengine_setextensionproperty) 启用美妆功能，改用 `STYLE_MAKEUP` 节点实现。 #### 双流模式行为变更 [#双流模式行为变更-1] - v4.6.2 之前：发送端开启小流自适应模式 (AutoSimulcastStream) 时，不会主动发送小流，仅当主播身份的接收端调用 [`setRemoteVideoStreamType`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setremotevideostreamtype) 发起小流申请后，发送端收到申请才会开始发送小流。 - v4.6.2 及之后版本：发送端开启小流自适应模式 (AutoSimulcastStream) 时，会根据订阅端用户的下行网络质量，自动决定发送或停止发送小流。若将 **mode** 设置为其他发送模式或显式配置了小流的宽、高、码率或帧率，则此自适应功能失效。 #### 新增域名白名单 [#新增域名白名单-4] 如果你由之前的版本升级到 v4.6.2 且使用了域名白名单功能（`RtcEngineConfig` 下的 `domainLimit` 为 `true`），请在白名单中添加以下域名，以确保互通顺畅： - `*.rtnsvc.com` - `*.realtimemesh.com` #### EncodedVideoFrameInfo 结构体删除参数 uid [#encodedvideoframeinfo-结构体删除参数-uid-2] 该版本删除了 [`EncodedVideoFrameInfo`](/zh-CN/api-reference/rtc/electron/class-encodedvideoframeinfo) 结构体中的 `uid` 参数。你可以直接从 [`onEncodedVideoFrameReceived`](/zh-CN/api-reference/rtc/electron/video/video-encoded#callback_ivideoencodedframeobserver_onencodedvideoframereceived) 回调中获取 `uid` 信息。如果你之前集成过相关代码，请相应更新集成逻辑。 ### 新增特性 [#新增特性-94] #### 多路分辨率视频流 [#多路分辨率视频流-4] 该版本新增多路分辨率视频流（Adaptive Bitrate Video Streaming，简称 ABR）功能，支持对同一视频源设置同时发送多路不同分辨率的视频流，并支持多频道场景。接收端通过自动/手动订阅目标分辨率的视频流。 启用 ABR 后，你可以配置不同分辨率的视频流（最多四层分辨率，即一个最高分辨率的主流和三层其他较低分辨率的视频流），并设置视频流的分辨率、码率、是否启用分层推流回退等选项来灵活控制流的发布。启用分层推流回退后，SDK 会在弱网环境下自动回退到低分辨率的视频流，确保流畅的观看体验。订阅端可根据实际需求选择想要接收的视频流。适用于会议场景、大班课、互动直播等多终端、多网络环境，可显著提升弱网下的观看体验。 #### 多路径网络传输 [#多路径网络传输-4] 该版本新增多路径传输功能，适用于终端支持多网卡传输（比如 5G、Wi-Fi、LAN）的设备，可以有效降低甚至消除弱网带来的体验回退，适用于弱网环境、对传输稳定性要求高的实时音视频通信场景，如车载、IoT、火车、高速公路等复杂网络环境。通过在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中设置 `enableMultipath` 为 `true`，可开启多路径传输能力。支持两种传输模式（[`MultipathMode`](/zh-CN/api-reference/rtc/electron/enum-multipathmode)）： - 动态模式：（默认）根据网络状况动态选择最佳路径进行传输，适用于流量敏感、对体验要求比较高的场景，如会议、教育等。动态模式下，你可以通过 `preferMultipathType` 指定首选的网络传输路径（如优先 Wi-Fi 或移动网络）。 - 全冗余模式：数据会在所有可用网络路径上同时传输，适用于流量不敏感，对体验有极致要求的场景，如户外采播、平行操控等。该模式会产生额外费用，如需使用请[联系技术支持](https://ticket.shengwang.cn/)。 上下行还可分别通过 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中的 `uplinkMultipathMode`、`downlinkMultipathMode` 配置。启用后，SDK 会通过回调 [`onMultipathStats`](/zh-CN/api-reference/rtc/electron/network#callback_irtcengineeventhandler_onmultipathstats) 实时上报各路径的传输统计信息，包括每一个传输路径的流量消耗，便于开发者监控和优化网络表现。 #### 视频质量评分 [#视频质量评分-4] 该版本在 [`RemoteVideoStats`](/zh-CN/api-reference/rtc/electron/class-remotevideostats) 中新增 `mosValue` 成员，报告声网实时视频 MOS（平均主观意见分）评估系统对接收到的远端视频流的质量评分。评分共有 5 个档次，5 分表示视频画质优秀，画面清晰无噪点，1 分表示视频画质极差，画面严重模糊。你可以通过该参数实时观测远端视频流的主观画质表现，便于动态调整视频参数、优化用户体验，或用于质量监控和告警等场景。如需启用该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 支持添加多个水印 [#支持添加多个水印-4] 该版本废弃了 [`addVideoWatermark`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2) 和 [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex) 方法，新增 [`addVideoWatermarkWithConfig`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/watermark#api_irtcengine_addvideowatermark3) 和 [`addVideoWatermarkWithConfigEx`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex1) 方法，支持通过水印 ID 来给视频添加多个水印，并可对水印进行排序。如果你需要移除指定水印，可调用 [`removeVideoWatermark`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/watermark#api_irtcengine_removevideowatermark) 方法。 #### Token 更新结果回调 [#token-更新结果回调-4] 该版本新增 [`onRenewTokenResult`](/zh-CN/api-reference/rtc/electron/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调及 [`RenewTokenErrorCode`](/zh-CN/api-reference/rtc/electron/enum-renewtokenerrorcode) 错误码。当调用 `renewToken` 方法更新 Token 后，SDK 会通过 [`onRenewTokenResult`](/zh-CN/api-reference/rtc/electron/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调通知 Token 更新的结果，并通过 [`RenewTokenErrorCode`](/zh-CN/api-reference/rtc/electron/enum-renewtokenerrorcode) 返回详细的错误码，开发者可在回调中根据错误码及时处理 Token 更新失败的场景。 #### Media Player 支持获取音频缓冲延迟 [#media-player-支持获取音频缓冲延迟-4] 为解决 K 歌场景中可能会出现的主唱与伴唱伴奏不同步的问题，该版本在 Media Player 模块中新增 [`getAudioBufferDelay`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-info#api_imediaplayer_getaudiobufferdelay) 方法，用于获取播放媒体文件时毫秒级的音频缓冲延迟。 #### 其他 [#其他-21] - 新增 [`setPlaybackAudioFrameBeforeMixingParameters`](/zh-CN/api-reference/rtc/electron/audio/audio-raw#api_irtcengine_setplaybackaudioframebeforemixingparameters1) 方法用于设置 [`onPlaybackAudioFrameBeforeMixing`](/zh-CN/api-reference/rtc/electron/audio/audio-raw#callback_iaudioframeobserver_onplaybackaudioframebeforemixing) 回调中返回的音频帧格式，包括采样率、声道数以及每次回调的数据采样点数。调用此方法后，SDK 会按照设定的参数返回混音前的原始音频数据，便于开发者进行自定义处理或分析。 - 新增 [`preloadEffectEx`](/zh-CN/api-reference/rtc/electron/play/audio-effect-file#api_irtcengineex_preloadeffectex) 方法，用于将指定音效文件预加载到指定频道，支持本地或在线音效文件，便于后续快速播放，适合多频道场景。 - 新增 [`playEffectEx`](/zh-CN/api-reference/rtc/electron/play/audio-effect-file#api_irtcengineex_playeffectex) 方法，用于在指定频道播放音效文件，支持设置循环次数、音调、空间位置、音量、是否发布到频道及播放起始位置等参数，满足丰富的音效播放需求。 - 本地截图上传功能支持通过 [`ContentInspectModule`](/zh-CN/api-reference/rtc/electron/class-contentinspectmodule) 中新增的 `position` 成员设置截图的视频观测位置，从而实现对原始视频数据或效果处理前后的视频流进行截图并上传。 - 为了提升用户使用绿幕或蓝幕开启虚拟背景功能时，人像分割的准确性和稳定性，该版本在 [`SegmentationProperty`](/zh-CN/api-reference/rtc/electron/class-segmentationproperty) 中新增 `screenColorType` 属性，支持指定背景幕布的颜色为绿色、蓝色或自动识别。 ### 改进 [#改进-111] #### 美颜重构 [#美颜重构-4] 该版本对美颜功能进行了彻底重构和升级，不仅拓展了美颜功能，提升了美颜效果和性能，还解决了美颜参数配置复杂、集成成本高、美颜资源依赖网络易失效等痛点。主要改进包括： - **新增美颜功能**：新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。 - **API 大幅简化**：将过去版本中的基础美颜、美型、美妆、滤镜功能整合为 `BEAUTY`、`STYLE_MAKEUP`、`FILTER` 三个核心节点 (node)，通过 [`IVideoEffectObject`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_ivideoeffectobject) 统一管理生命周期和参数设置，减少频繁 API 调用带来的性能负担。 - **预设模板开箱即用**：提供多套预设风格模板（如"自然美颜"、"学姐妆"、"冷白滤镜"），大幅简化集成流程，无需手动调试数十项参数。 - **美颜参数动态控制**：该版本新增实时获取美颜参数的能力，开发者可通过 key-value 方式动态读取或修改任意细粒度参数（如磨皮强度、口红类型）。同时支持：调用预设模板快速启用风格效果、保存主播自定义参数配置、随时重置参数至默认状态，极大提升了业务层状态同步的灵活性和开发效率。 - **美颜资源外置**：该版本通过美颜资源外置化设计，将所有美颜资源（特效、滤镜、妆容）均打包为本地 bundle 文件，彻底消除因网络下载失败导致美颜失效的风险。 #### playEffect 支持无缝切换 [#playeffect-支持无缝切换-4] 该版本新增支持音效文件的无缝切换。对于同一个音效文件，如果先调用 [`preloadEffect`](/zh-CN/api-reference/rtc/electron/play/audio-effect-file#api_irtcengine_preloadeffect) 再调用 [`playEffect`](/zh-CN/api-reference/rtc/electron/play/audio-effect-file#api_irtcengine_playeffect3)，在播放完成或通过 [`stopEffect`](/zh-CN/api-reference/rtc/electron/play/audio-effect-file#api_irtcengine_stopeffect) 停止播放后，SDK 不会关闭该音效文件。当再次调用 [`playEffect`](/zh-CN/api-reference/rtc/electron/play/audio-effect-file#api_irtcengine_playeffect3) 时，SDK 会直接复用已加载的文件进行播放，从而实现循环播放和无缝切换。该能力同样适用于多频道场景。 #### 屏蔽窗口支持第二屏幕 [#屏蔽窗口支持第二屏幕-1] 在 4.6.2 之前的版本中，通过屏幕 ID（[`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebydisplayid)）进行屏幕共享时，不支持在多屏场景下配置屏蔽窗口（[`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters) 中的 `excludeWindowList`）。为提升屏幕共享体验，该版本新增支持该配置。 同时，为便于识别屏幕共享过程中屏蔽窗口的状态，该版本在 [`LocalVideoStreamReason`](/zh-CN/api-reference/rtc/electron/enum-localvideostreamreason) 中新增 `LocalVideoStreamReasonScreenCaptureExcludeWindowFailed`，用于报告屏幕共享屏蔽窗口失败的情况。 #### onVideoDeviceStateChanged 回调时机优化 [#onvideodevicestatechanged-回调时机优化-1] 该版本优化了 [`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/electron/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) 回调的触发时机。在此前版本中，该回调仅在加入频道后才能触发。从 4.6.2 起，在 [`IRtcEngine`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine) 完成初始化后即可收到一次该回调，加入频道后仍可继续监听该事件。 #### onNetworkQuality 准确性提升 [#onnetworkquality-准确性提升-2] 该版本提升了 [`onNetworkQuality`](/zh-CN/api-reference/rtc/electron/network#callback_irtcengineeventhandler_onnetworkquality) 回调中网络质量评估的准确性，使回调数据更贴近用户的主观体验。 #### onPlaybackAudioFrame 支持 24k 采样率的音频帧 [#onplaybackaudioframe-支持-24k-采样率的音频帧-3] 该版本在 [`onPlaybackAudioFrame`](/zh-CN/api-reference/rtc/electron/audio/audio-raw#callback_iaudioframeobserverbase_onplaybackaudioframe) 中新增支持采样率为 **24000 Hz** 的音频数据。在调用 [`setPlaybackAudioFrameParameters`](/zh-CN/api-reference/rtc/electron/audio/audio-raw#api_irtcengine_setplaybackaudioframeparameters) 设置播放音频数据格式时，可以将 `sampleRate` 设为 `24000`。 #### onEncodedVideoFrameReceived 回调支持获取频道 ID [#onencodedvideoframereceived-回调支持获取频道-id-3] 该版本在 [`onEncodedVideoFrameReceived`](/zh-CN/api-reference/rtc/electron/video/video-encoded#callback_ivideoencodedframeobserver_onencodedvideoframereceived) 回调中新增 `channelId` 参数，方便你在获取编码后视频数据时识别其所属频道。 #### 其他改进 [#其他改进-40] - 优化了在 Windows 11 24H2 及后续版本上的权限请求，避免非必要地获取位置信息。 - 在与 Web 端互通时，新增对 g711 和 g722 音频编解码器的支持，进一步提升了跨平台音频播放的兼容性和清晰度。 - 优化了屏幕共享文档场景下的共享视频清晰度。 - 该版本新增错误码 `ErrPcmSendFormat` (200) 和 `ErrPcmSendBufferOverflow` (201)，用于报告 PCM 数据发送相关错误。 ### 问题修复 [#问题修复-109] 该合并版本修复了以下问题： - 开启导唱功能播放多音轨歌曲时，调用 [`setAudioPitch`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setaudiopitch) 方法调整歌曲音调后出现杂音。 - 主播端调用 [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 创建自定义音频采集轨道并将 `trackType` 设为 `AudioTrackDirect`，调用 [`pushAudioFrame`](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_pushaudioframe) 将自采集音频推送到频道内，然后调用 [`playEffect`](/zh-CN/api-reference/rtc/electron/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效，频道内的观众听主播的音频有杂音。 - 集成了 SDK 的 App 在音视频互动过程中偶现主线程阻塞导致的 UI 卡顿。 - 开启屏幕共享功能并将 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters) 的 `enableHighLight` 设为 `true` 对共享窗口进行描边，将共享窗口置于最上层并最大化后，本地预览的共享画面出现闪烁。 - 应用程序共享外接屏幕的视频流，断开外接屏幕连接后偶现应用程序崩溃。 - 调用 [`openWithMediaSource`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 并通过 `source` 参数将 `isLiveSource` 设为 `true` 并播放纯视频流，播放失败。 - 发送端传输多声道编码音频时，接收端偶现杂音。 - App 集成媒体播放器场景下，先后两次调用 [`open`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-open#api_imediaplayer_open) 打开不同媒体资源，第二次打开时，媒体播放器信息变化回调 [`onPlayerInfoUpdated`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerinfoupdated) 返回第一次媒体资源的信息，不符合预期。 - 调用 [`enableAudioVolumeIndication`](/zh-CN/api-reference/rtc/electron/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 启用用户音量提示本地发流用户和远端用户音量相关信息，用户音量提示回调 `onAudioVolumeIndication` 返回的本地用户音量为 0。 - 使用 21:9 的显示屏（带鱼屏）进行音视频互通和屏幕共享场景下，设置高分辨率，如 3840*2160，屏幕共享画面在本地预览和接收端显示被裁剪。 - App 调用 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 启用垫片推流功能，偶现发送端推流成功但是 [`onVideoPublishStateChanged`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 返回当前的发布状态不是 `PublishStatePublished`，不符合预期。 - 多频道场景下，App 在调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengineex_joinchannelex) 成功前调用 [`setupRemoteVideoEx`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengineex_setupremotevideoex) 初始化远端用户视图，偶现远端用户视图首帧图像显示延时大。 - 调用 [`open`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-open#api_imediaplayer_open) 打开在线音效文件后，调用 [`playEffect`](/zh-CN/api-reference/rtc/electron/play/audio-effect-file#api_irtcengine_playeffect3) 开始播放，当调用 [`seek`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定播放位置后，音效文件会从头开始播放。 - 在媒体音量模式下，主播在频道中发布麦克风采集的音频流，同时调用 [`playEffect`](/zh-CN/api-reference/rtc/electron/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效文件、调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/electron/play/audio-mixing#api_irtcengine_startaudiomixing2) 播放音乐文件，偶现回声。 - 调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengineex_joinchannelex) 加入频道，然后调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 开始跨频道媒体流转发，下麦、退出频道后重新加入频道开始连麦，偶现 [`onChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) 回调报告 `state` 为 `RelayStateFailure`，`code` 为 `RelayErrorServerErrorResponse`。 - 部分机型的笔记本电脑开启节能模式下，发送端共享屏幕和音频，偶现接收端听到回声。 - 在线教育场景下，偶现教师端本地看多个学生端音画不同步。 - 第二次调用 [`enumerateVideoDevices`](/zh-CN/api-reference/rtc/electron/device-management/video-device#api_ivideodevicemanager_enumeratevideodevices) 接口获取设备列表不生效。 - Windows 7 设备上共享 PPT 窗口，当 PPT 以全屏自动播放模式运行且包含大量动画时，远端看到的画面有概率出现闪烁。 ## v4.5.2(对应 Native v4.5.1) [#v452对应-native-v451] 该版本于 2025 年 3 月 13 日发布。 ### 新增特性 [#新增特性-95] #### AI 对话场景 [#ai-对话场景-4] 该版本新增了专为与[声网对话式 AI 引擎](/zh-CN/ai)创建的智能体互动设计的 `AudioScenarioAiClient` 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。 ### 问题修复 [#问题修复-110] 该版本修复了以下问题： - 同时加入两个及以上的频道，连续调用 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。 - 使用媒体播放器时，调用 [`pause`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 定位到指定播放位置、然后调用 [`play`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。 - 使用媒体播放器时，调用 [`switchSrc`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换媒体资源后，调用 [`getPlaySrc`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-info#api_imediaplayer_getplaysrc_imediaplayer) 获取当前正在播放的媒体资源的路径没有变化。 - 在极速直播场景下，观众通过 `string` 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。 - 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。 ## v4.5.0 [#v450-5] 该版本于 2024 年 12 月 10 日发布。 ### 升级必看 [#升级必看-63] 该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 强效视频降噪实现变更 [#强效视频降噪实现变更-4] 该版本调整了强效视频降噪的实现方式，在 [`VideoDenoiserLevel`](/zh-CN/api-reference/rtc/electron/enum-videodenoiserlevel) 中删除了 `VidoDenoiserLevelStrength`，改为调用 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 启用视频降噪后，调用 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)。 此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 [`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)。 #### 摄像头插拔状态变更 (macOS, Windows) [#摄像头插拔状态变更-macos-windows] 在之前版本中，当摄像头拔出并重新插入时，[`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/electron/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) 回调会将设备状态报告为 `MediaDeviceStateActive`(1)（设备正在使用）。该版本起，摄像头重新插入后，设备状态将改为 `MediaDeviceStateIdle`(0)（设备就绪）。 #### 视频编码偏好变更 [#视频编码偏好变更-4] 为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好： - 在 [`CompressionPreference`](/zh-CN/api-reference/rtc/electron/enum-compressionpreference) 枚举类中新增 `PreferCompressionAuto` (-1) 枚举，并替代原有的 `PreferQuality` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `PreferLowLatency` 或 `PreferQuality`，以获得最佳的用户体验。 - 在 [`DegradationPreference`](/zh-CN/api-reference/rtc/electron/enum-degradationpreference) 枚举类中新增 `MaintainAuto` (-1) 枚举，并替代原有的 `MaintainQuality` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `MaintainFramerate`、`MaintainBalanced` 或 `MaintainResolution`，以获得最优的综合质量体验 (QoE)。 ### 新增特性 [#新增特性-96] #### 高级美颜 [#高级美颜-4] 该版本新增以下两种高级美颜功能： - 美型：调用 [`setFaceShapeBeautyOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 [`setFaceShapeAreaOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapeareaoptions) 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。 - 美妆：调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/electron/extension#api_irtcengine_setextensionproperty) 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。 :::info[信息] 目前，高级美颜功能为**限时免费**，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 秀场直播场景 [#秀场直播场景-4] 该版本在 [`VideoApplicationScenarioType`](/zh-CN/api-reference/rtc/electron/enum-videoapplicationscenariotype) 类下新增枚举 `ApplicationScenarioLiveshow`(3)（秀场直播），你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为[秀场直播](/zh-CN/solutions/showroom)。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，重点提升了首帧出图体验和画质表现，同时增强了在弱网环境和低端设备上的画质和流畅度表现。 #### 限制视频渲染帧率 [#限制视频渲染帧率-4] 该版本新增 [`setLocalRenderTargetFps`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_setlocalrendertargetfps) 和 [`setRemoteRenderTargetFps`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_setremoterendertargetfps) 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。 在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。 #### 滤镜效果 [#滤镜效果-4] 该版本新增 [`setFilterEffectOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setfiltereffectoptions) 方法，你可以在 `config` 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 `built_in_whiten_filter.cube` 文件，用于快速实现美白滤镜效果。 #### 本地音频合流 [#本地音频合流-4] 该版本新增本地音频合流功能，你可以调用 [`startLocalAudioMixer`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/audiomixer#api_irtcengine_startlocalaudiomixer) 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 [`stopLocalAudioMixer`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/audiomixer#api_irtcengine_stoplocalaudiomixer) 方法停止本地音频合流；在合流过程中，可以调用 [`updateLocalAudioMixerConfiguration`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/audiomixer#api_irtcengine_updatelocalaudiomixerconfiguration) 方法更新正在合流的音频流配置。 该功能的使用场景示例如下： - 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。 - 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。 - 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。 #### 色彩空间设置 [#色彩空间设置-4] 该版本在 [`VideoFrame`](/zh-CN/api-reference/rtc/electron/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/electron/class-externalvideoframe) 中新增了 `colorSpace`，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。 #### 其他 [#其他-22] - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调新增 `LocalVideoStreamReasonDeviceDisconnected` 枚举，表示当前正在使用的视频采集设备已经断开连接（例如，被拔出）。(Windows) - [`MediaDeviceStateType`](/zh-CN/api-reference/rtc/electron/enum-mediadevicestatetype) 新增 `MediaDeviceStatePluggedIn` 枚举，表示设备已插入。 ### 改进 [#改进-112] #### 虚拟背景算法优化 [#虚拟背景算法优化-8] 该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。 #### 录制本地预览视频 [#录制本地预览视频-4] 该版本在 [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/electron/class-recorderstreaminfo) 中新增 `type` 成员。当调用 [`createMediaRecorder`](/zh-CN/api-reference/rtc/electron/recording#api_irtcengine_createmediarecorder) 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 [`MediaRecorderConfiguration`](/zh-CN/api-reference/rtc/electron/class-mediarecorderconfiguration) 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 [`startRecording`](/zh-CN/api-reference/rtc/electron/recording#api_imediarecorder_startrecording) 即可开始录制本地预览的视频。 #### 指定视频观测位置截图 [#指定视频观测位置截图-4] 该版本新增 [`takeSnapshotWithConfig`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/snapshot#api_irtcengine_takesnapshot2) 和 [`takeSnapshotWithConfigEx`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex2) 方法，你可以在调用该方法时通过 `config` 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。 #### 自定义音频采集改进 [#自定义音频采集改进-4] 该版本在 [`AudioTrackConfig`](/zh-CN/api-reference/rtc/electron/class-audiotrackconfig) 中新增了 `enableAudioProcessing` 成员参数，用于控制是否对 `AudioTrackDirect` 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 `false`，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。 #### 其他改进 [#其他改进-41] - 优化了调用 [`queryDeviceScore`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_querydevicescore) 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。 - 支持使用 YV 12 格式的虚拟摄像头作为视频采集设备。(Windows) - 调用 [`switchSrc`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 [`onPlayerEvent`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent) 回调报告 `PlayerEventSwitchError` 事件，表示媒体资源切换时发生错误。 - 调用 [`setPlaybackSpeed`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，最低支持 0.3 倍速播放。 ### 问题修复 [#问题修复-111] 该版本修复了以下问题： - 调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享屏幕时，通过 `regionRect` 指定的窗口采集区域不准确，导致接收端看到的屏幕共享窗口宽高错误。（Windows） - Windows 7 系统下进行音视频互动，偶现找不到系统文件的报错。(Windows) - 调用 [`followSystemRecordingDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_followsystemrecordingdevice) 或 [`followSystemPlaybackDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_followsystemplaybackdevice) 设置 SDK 使用的音频采集或播放设备不跟随系统默认的音频播放设备，当音频设备被移除时，本地音频状态回调 [`onLocalAudioStateChanged`](/zh-CN/api-reference/rtc/electron/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) 没有被触发，不符合预期。(Windows) - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/electron/play/audio-mixing#api_irtcengine_startaudiomixing2)后，立即调用 [`pauseAudioMixing`](/zh-CN/api-reference/rtc/electron/play/audio-mixing#api_irtcengine_pauseaudiomixing) 暂停播放音乐文件不生效。 ## v4.4.0 [#v440-6] 该版本于 2024 年 8 月 29 日发布。 ### 升级必看 [#升级必看-64] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 1. 为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的 [`ExtensionContext`](/zh-CN/api-reference/rtc/electron/class-extensioncontext) 了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。 | 原有回调 | 现有回调 | | -------- | ------------------------------- | | `onExtensionEvent` | [`onExtensionEventWithContext`](/zh-CN/api-reference/rtc/electron/extension#callback_irtcengineeventhandler_onextensioneventwithcontext) | | `onExtensionStarted` | [`onExtensionStartedWithContext`](/zh-CN/api-reference/rtc/electron/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) | | `onExtensionStopped` | [`onExtensionStoppedWithContext`](/zh-CN/api-reference/rtc/electron/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext) | | `onExtensionError` | [`onExtensionErrorWithContext`](/zh-CN/api-reference/rtc/electron/extension#callback_irtcengineeventhandler_onextensionerrorwithcontext) | 2. 该版本修改了 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/electron/class-externalvideoframe) 中的以下成员名称： - `d3d11_texture_2d` 更名为 `d3d11Texture2d`。 - `texture_slice_index` 更名为 `textureSliceIndex`。 - `metadata_buffer` 更名为 `metadataBuffer`。 - `metadata_size` 更名为 `metadataSize`。 ### 新增特性 [#新增特性-97] #### AI 调音器 [#ai-调音器-4] 该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 [`enableVoiceAITuner`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/audio-effect#api_irtcengine_enablevoiceaituner) 方法并传入 [`VoiceAiTunerType`](/zh-CN/api-reference/rtc/electron/enum-voiceaitunertype) 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。 #### 1v1 视频通话场景 [#1v1-视频通话场景-4] 该版本在 [`VideoApplicationScenarioType`](/zh-CN/api-reference/rtc/electron/enum-videoapplicationscenariotype) 类下新增枚举 `ApplicationScenario1v1`（1v1 视频通话）。你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。 ### 改进 [#改进-113] #### 自适应硬解支持 (Windows) [#自适应硬解支持-windows] 该版本新增自适应硬解支持，改进了低端机的渲染流畅性，有效降低系统负载。 #### 渲染能力提升 (Windows) [#渲染能力提升-windows] Windows 设备上默认启用 DirectX 11 渲染器，可提供高性能、高质量的图形渲染能力。 #### 人脸区域美颜 [#人脸区域美颜-4] 为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。 #### 其他改进 [#其他改进-42] 该版本还进行了如下改进： - 优化了传输策略，调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_enableinstantmediarendering) 不再对传输链路的安全性产生影响。 - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增 `LocalVideoStreamReasonScreenCaptureDisplayDisconnected` 枚举，表示进行屏幕采集的显示器已断开连接。 - 优化了共享窗口的视频链路，降低了 CPU 占用率。(macOS) - 优化了屏幕共享场景下的回声消除。 - 该版本在 [`Metadata`](/zh-CN/api-reference/rtc/electron/class-metadata) 中新增 `channelId` 参数，用于获取发送 Metadata 的源频道名称。 - 废弃了 [`ClientRoleChangeFailedReason`](/zh-CN/api-reference/rtc/electron/enum-clientrolechangefailedreason) 中的冗余枚举值 `ClientRoleChangeFailedRequestTimeOut`、`ClientRoleChangeFailedConnectionFailed`。 ### 问题修复 [#问题修复-112] 该版本修复了用户主动拒绝授权 App 使用音视频设备的权限后进行音视频互动时 App 崩溃的问题。(macOS) ## v4.3.2 [#v432-4] 该版本于 2024 年 6 月 6 日发布。 ### 改进 [#改进-114] 该版本提升了 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_setremotesubscribefallbackoption) 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_setremotesubscribefallbackoption) 动态切换弱网环境下的音视频流回退选项。 ### 问题修复 [#问题修复-113] 该版本修复了以下问题： - 音视频互动过程中偶现视频流畅度不佳。 - 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。 - 远端用户离开频道时偶现崩溃。 - 调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享 PPT 窗口，当 PPT 播放动画画面时，接收端偶现画面闪烁。(Windows) - 在 Windows 7 系统上调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享 WPS PPT 窗口，并设置 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters) 的 `enableHighLight` 为 `true` 开启窗口描边，放映该 PPT 后退出放映，之后选择最大化 PPT 窗口，窗口描边没有保留原始窗口大小，不符合预期。(Windows) - 调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享窗口，并设置 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters) 的 `windowFocus` 和 `enableHighLight` 为 `true` 以前置指定窗口并开启窗口描边，如果当前该窗口被其他窗口覆盖，无法前置该窗口，不符合预期。(Windows) - 在 Windows 7 设备上共享窗口并对窗口描边时，点击桌面控件导致描边部分闪烁。(Windows) - 调用 [`leaveChannelEx`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengineex_leavechannelex2) 离开频道时，偶现不传入 `options` 参数导致的 App 崩溃。 ## v4.3.1 [#v431-4] 该版本于 2024 年 5 月 9 日发布。 ### 新增特性 [#新增特性-98] #### 人像锁定 (macOS) [#人像锁定-macos] 为提升在线会议、秀场、在线教育等场景中的主播演讲效果，该版本新增 [`enableCameraCenterStage`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) 方法开启人像锁定功能。该功能可确保主播无论移动与否，始终位于画面中心，以取得良好的演讲效果。 在开启人像锁定前，建议你先调用 [`isCameraCenterStageSupported`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) 查询当前设备性能是否支持该功能。支持的设备清单可参考 [API 文档](/zh-CN/api-reference/rtc/electron/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage)。 #### 数据流加密 [#数据流加密-5] 该版本在 [`EncryptionConfig`](/zh-CN/api-reference/rtc/electron/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` 成员用于启用数据流加密。你可以在调用 [`enableEncryption`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_enableencryption) 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 `EncryptionErrorDatastreamDecryptionFailure` 和 `EncryptionErrorDatastreamEncryptionFailure` 枚举得知。 #### 视频小流自适应配置 [#视频小流自适应配置-4] 该版本新增视频小流的自适应配置功能，当你调用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setdualstreammode2) 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示： - 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。 - 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。 #### 其他 [#其他-23] - 新增 [`enableEncryptionEx`](/zh-CN/api-reference/rtc/electron/network#api_irtcengineex_enableencryptionex) 方法，用于多频道场景下开启媒体流或数据流加密。 - 新增 [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/electron/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) 方法，用于设置音乐文件的播放速度。 - 新增 [`getCallIdEx`](/zh-CN/api-reference/rtc/electron/network#api_irtcengineex_getcallidex) 方法，用于多频道场景下获取通话 ID。 ### 改进 [#改进-115] #### 屏幕共享游戏场景优化 (Windows) [#屏幕共享游戏场景优化-windows] 该版本对屏幕共享的游戏场景进行了专项优化，在超高清（4K, 60 fps）游戏场景下提升了性能表现，增强了窗口采集的稳定性，为游戏玩家带来更清晰、流畅、稳定的游戏体验。 #### 获取音频设备类型 (macOS) [#获取音频设备类型-macos] 该版本在 [`AudioDeviceInfo`](/zh-CN/api-reference/rtc/electron/class-audiodeviceinfo) 中新增 `deviceTypeName` 成员，用于获取音频设备的类型，如 built-in、USB、HDMI 等。 #### 虚拟背景算法优化 [#虚拟背景算法优化-9] 为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法： - 支持识别任意纯色背景，不再局限于绿幕。 - 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。 - 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。 #### 降低耳返的 CPU 消耗 [#降低耳返的-cpu-消耗-4] 该版本在 [`EarMonitoringFilterType`](/zh-CN/api-reference/rtc/electron/enum-earmonitoringfiltertype) 中新增 `EarMonitoringFilterReusePostProcessingFilter`(`1 << 15`) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。 #### 其他改进 [#其他改进-43] 该版本还进行了如下改进： - 优化了非屏幕共享场景的视频编解码策略，节省系统性能开销。 - 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。 - 在 [`AudioEffectPreset`](/zh-CN/api-reference/rtc/electron/enum-audioeffectpreset) 中新增 `RoomAcousticsChorus`（合唱音效），可使人声在合唱场景下更具空间立体感。 - 在 [`RemoteAudioStats`](/zh-CN/api-reference/rtc/electron/class-remoteaudiostats) 中新增 `e2eDelay`，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。 ### 问题修复 [#问题修复-114] 该版本修复了以下问题： - 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。 - 屏幕共享场景中，App 调用 [`enableLoopbackRecording`](/zh-CN/api-reference/rtc/electron/audio/audio-capture#api_irtcengine_enableloopbackrecording) 开启声卡采集功能采集共享屏幕的音频，本地用户手动禁用本地音频采集设备后，声卡采集的音频发送失败，远端用户听不见共享屏幕的声音。(Windows) - 在音视频互动中，如果用户将耳机插入设备并手动将系统音频输出切换为扬声器，之后 App 调用 [`setPlaybackDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_setplaybackdevice) 方法指定音频播放设备为耳机，用户移除耳机后，音频输出并未按预期行为切换至扬声器。 (macOS) - 在共享 Excel 文档窗口时，偶现远端用户看到的画面出现绿屏。(Windows) - 在使用 Intel 显卡的设备上发布视频小流偶现性能回退。(Windows) - 当发送端用户的网络环境恶化（例如弱网）时，接收端偶现视频流畅度降低、卡顿增加。 ### API 变更 [#api-变更-61] #### 新增 [#新增-55] - [`enableCameraCenterStage`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) (macOS) - [`isCameraCenterStageSupported`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) (macOS) - [`EncryptionConfig`](/zh-CN/api-reference/rtc/electron/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` - [`EncryptionErrorType`](/zh-CN/api-reference/rtc/electron/enum-encryptionerrortype) 中新增如下枚举： - `EncryptionErrorDatastreamDecryptionFailure` - `EncryptionErrorDatastreamEncryptionFailure` - [`AudioDeviceInfo`](/zh-CN/api-reference/rtc/electron/class-audiodeviceinfo) 中新增 `deviceTypeName` (macOS) - [`RemoteAudioStats`](/zh-CN/api-reference/rtc/electron/class-remoteaudiostats) 新增 `e2eDelay` - [`ErrorCodeType`](/zh-CN/api-reference/rtc/electron/enum-errorcodetype) 新增 `ErrDatastreamDecryptionFailed` - [`AudioEffectPreset`](/zh-CN/api-reference/rtc/electron/enum-audioeffectpreset) 新增 `RoomAcousticsChorus` - [`getCallIdEx`](/zh-CN/api-reference/rtc/electron/network#api_irtcengineex_getcallidex) - [`enableEncryptionEx`](/zh-CN/api-reference/rtc/electron/network#api_irtcengineex_enableencryptionex) - [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/electron/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) - [`EarMonitoringFilterType`](/zh-CN/api-reference/rtc/electron/enum-earmonitoringfiltertype) 新增枚举 `EarMonitoringFilterBuiltInAudioFilters`(`1 << 15`) ## v4.3.0 [#v430-5] 该版本于 2024 年 2 月 28 日发布。 ### 升级必看 [#升级必看-65] 该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 回调中的参数改名 [#回调中的参数改名-4] 为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。 | 回调 | 原有参数名 | 现有参数名 | | ---------------------------------- | ---------- | ---------- | | [`onLocalAudioStateChanged`](/zh-CN/api-reference/rtc/electron/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) | `error` | `reason` | | [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) | `error` | `reason` | | `onDirectCdnStreamingStateChanged` | `error` | `reason` | | [`onRtmpStreamingStateChanged`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/media-push#callback_irtcengineeventhandler_onrtmpstreamingstatechanged) | `errCode` | `reason` | | 原有枚举类 | 现有枚举类 | | ---------------------------- | -------------------------- | | `LocalAudioStreamError` | [`LocalAudioStreamReason`](/zh-CN/api-reference/rtc/electron/enum-localaudiostreamreason) | | `LocalVideoStreamError` | [`LocalVideoStreamReason`](/zh-CN/api-reference/rtc/electron/enum-localvideostreamreason) | | `DirectCdnStreamingError` | `DirectCdnStreamingReason` | | `MediaPlayerError` | [`MediaPlayerReason`](/zh-CN/api-reference/rtc/electron/enum-mediaplayerreason) | | `RtmpStreamPublishErrorType` | [`RtmpStreamPublishReason`](/zh-CN/api-reference/rtc/electron/enum-rtmpstreampublishreason) | :::info[信息] 有关具体枚举的改名详见 [API 变更](#430-api-changes)。 ::: #### 跨频道媒体流转发 [#跨频道媒体流转发-8] 为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项： | 已删除的方法和回调 | 替代的方法和回调 | | --- | --- | | [release-notes-electron-html-0-1-0 details](#table-slot-release-notes-electron-html-0-1-0) | [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) | | [release-notes-electron-html-0-2-0 details](#table-slot-release-notes-electron-html-0-2-0) | [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) | | `onChannelMediaRelayEvent` | [`onChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) | **release-notes-electron-html-0-1-0 details** - `startChannelMediaRelay` - `updateChannelMediaRelay` **release-notes-electron-html-0-2-0 details** - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` #### 本地视频状态改变原因 [#本地视频状态改变原因-4] 该版本对 [`LocalVideoStreamReason`](/zh-CN/api-reference/rtc/electron/enum-localvideostreamreason) 枚举类中的枚举进行了如下修改： - `LocalVideoStreamReasonScreenCapturePaused` （原 `LocalVideoStreamErrorScreenCapturePaused`）的值从 23 变更为 28。 (Windows) - `LocalVideoStreamReasonScreenCaptureResumed` （原 `LocalVideoStreamErrorScreenCaptureResumed`）的值从 24 变更为 29。 (Windows) - `LocalVideoStreamErrorCodecNotSupport` 的枚举名变更为 `LocalVideoStreamReasonCodecNotSupport`。 #### 日志加密行为变更 [#日志加密行为变更-4] 出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案： - 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。 - 如有其他特殊需求，请[联系技术支持](https://ticket.shengwang.cn/)并附上对应的加密日志。 #### 声卡采集 [#声卡采集-2] - 在 v4.3.0 之前，当你调用 [`disableAudio`](/zh-CN/api-reference/rtc/electron/audio/audio-basic#api_irtcengine_disableaudio) 关闭整个音频模块后，声卡采集功能不会被关闭。 - 从 v4.3.0 起，当你调用 [`disableAudio`](/zh-CN/api-reference/rtc/electron/audio/audio-basic#api_irtcengine_disableaudio) 关闭音频模块后，声卡采集功能也会被关闭，如果你需要再次启用声卡采集功能，需要在调用 [`enableAudio`](/zh-CN/api-reference/rtc/electron/audio/audio-basic#api_irtcengine_enableaudio) 启用音频模块后再次调用 [`enableLoopbackRecording`](/zh-CN/api-reference/rtc/electron/audio/audio-capture#api_irtcengine_enableloopbackrecording)。 ### 新增特性 [#新增特性-99] #### 多视图本地预览 [#多视图本地预览-4] 该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下： 1. 调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第一个视图：在 [`VideoCanvas`](/zh-CN/api-reference/rtc/electron/class-videocanvas) 中设置 `position` 参数为 `PositionPostCapturerOrigin`（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。 2. 调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第二个视图：在 [`VideoCanvas`](/zh-CN/api-reference/rtc/electron/class-videocanvas) 中设置 `position` 参数为 `PositionPostCapturer`，此处观测到的视频具备视频前处理的效果。 3. 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。 #### 查询设备评分等级 [#查询设备评分等级-4] 该版本新增 [`queryDeviceScore`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_querydevicescore) 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请[联系技术支持](https://ticket.shengwang.cn/)。 #### 本地播放及发布至远端的音轨控制 [#本地播放及发布至远端的音轨控制-4] 该版本新增 [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/electron/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 [`openWithMediaSource`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并通过 [`MediaSource`](/zh-CN/api-reference/rtc/electron/class-mediasource) 中新增的 `enableMultiAudioTrack` 成员来开启音轨控制。 #### 其他 [#其他-24] 该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。 - [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_setremotesubscribefallbackoption)：设置弱网环境下订阅的音视频流回退选项。 - [`onRemoteSubscribeFallbackToAudioOnly`](/zh-CN/api-reference/rtc/electron/network#callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly)：订阅流已回退为音频流或恢复为音视频流回调。 - [`setPlaybackDeviceVolume`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_setplaybackdevicevolume) (Windows)：设置播放设备音量。 - [`getRecordingDeviceVolume`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_getrecordingdevicevolume) (Windows)：获取音频采集设备音量。 - [`setPlayerOptionInInt`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption) 和 [`setPlayerOptionInString`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption2)：设置媒体播放器选项，用于提供技术预览或特别定制功能。 - [`enableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback)：设置是否在本地播放外部音频源。 ### 改进 [#改进-116] #### SDK 任务处理调度优化 [#sdk-任务处理调度优化-4] 该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面： - 远端及本地的首帧出图与出声速度均有明显提升。 - API 的调用耗时和响应耗时缩短 50% 以上。 - SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。 - SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。 #### 耳返音量提升 [#耳返音量提升-4] 该版本为用户提供更灵活的耳返音频调整选项，支持调用 [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/electron/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) 将耳返音量设置为原始音量的 4 倍。 #### 空间音频易用性提升 [#空间音频易用性提升-4] - 该版本优化了 [`setZones`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 方法的设计，支持将 `zones` 参数设置为 `NULL`，表示清除所有隔声区域。 - 自该版本起，在调用 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_ilocalspatialaudioengine) 中的方法之前，无需先取消订阅频道内所有远端用户的音频流。 #### 其他改进 [#其他改进-44] 该版本还进行了如下改进： - 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。 - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增 `LocalVideoStreamReasonScreenCaptureAutoFallback` 枚举，表示屏幕共享过程中发生意外错误（可能由于窗口阻塞失败），导致性能下降，但屏幕共享过程本身没有受到影响。 - 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_setlocalaccesspoint) 解析域名时的稳定性。 - 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。 - [`LocalAudioStats`](/zh-CN/api-reference/rtc/electron/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。 - 新增 [`onPlayerCacheStats`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) 回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。 - 新增 [`onPlayerPlaybackStats`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) 回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过 [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/electron/class-playerplaybackstats) 来获取当前音、视频的码率等信息。 ### 问题修复 [#问题修复-115] 该版本修复了以下问题： - 当同时共享两路屏幕共享视频流时，[`onLocalVideoStats`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onlocalvideostats) 回调上报的 `captureFrameRate` 为 0，不符合预期。 - 在指定屏幕区域共享时，鼠标在共享区域内的坐标不准确。当鼠标位于共享区域的边界附近时，可能导致共享的画面中看不到鼠标。(Windows) - 使用 3.5 mm 耳机多次插拔设备后，SDK 未能检测到音频路由的变化。(Windows) ### API 变更 [#api-变更-62] #### 新增 [#新增-56] - [`VideoCanvas`](/zh-CN/api-reference/rtc/electron/class-videocanvas) 新增 `subviewUid` 和 `uid` 成员 - [`enableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback) - [`queryDeviceScore`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_querydevicescore) - [`MediaSourceType`](/zh-CN/api-reference/rtc/electron/enum-mediasourcetype) 中新增 `CustomVideoSource` 枚举 - [`AudioRoute`](/zh-CN/api-reference/rtc/electron/enum-audioroute) 中新增 `RouteBluetoothDeviceA2DP` 枚举 - [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/electron/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) - [`onPlayerCacheStats`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) - [`onPlayerPlaybackStats`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) - [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/electron/class-playerplaybackstats) #### 修改 [#修改-14] - 以下枚举名中的 `error` 字段全部修改为 `reason`： - `LocalAudioStreamErrorOk` - `LocalAudioStreamErrorFailure` - `LocalAudioStreamErrorDeviceNoPermission` - `LocalAudioStreamErrorDeviceBusy` - `LocalAudioStreamErrorRecordFailure` - `LocalAudioStreamErrorEncodeFailure` - `LocalAudioStreamErrorRecordInvalidId` (Windows) - `LocalAudioStreamErrorPlayoutInvalidId` (Windows) - `LocalVideoStreamErrorOk` - `LocalVideoStreamErrorFailure` - `LocalVideoStreamErrorDeviceNoPermission` - `LocalVideoStreamErrorDeviceBusy` - `LocalVideoStreamErrorCaptureFailure` - `LocalVideoStreamErrorCodecNotSupport` - `LocalVideoStreamErrorDeviceNotFound` - `LocalVideoStreamErrorDeviceDisconnected` - `LocalVideoStreamErrorDeviceInvalidId` - `LocalVideoStreamErrorScreenCaptureWindowMinimized` - `LocalVideoStreamErrorScreenCaptureWindowClosed` - `LocalVideoStreamErrorScreenCaptureWindowOccluded` - `DirectCdnStreamingErrorOk` - `DirectCdnStreamingErrorFailed` - `DirectCdnStreamingErrorAudioPublication` - `DirectCdnStreamingErrorVideoPublication` - `DirectCdnStreamingErrorNetConnect` - `DirectCdnStreamingErrorBadName` - `PlayerErrorNone` - `PlayerErrorInvalidArguments` - `PlayerErrorInternal` - `PlayerErrorNoResource` - `PlayerErrorInvalidMediaSource` - `PlayerErrorUnknownStreamType` - `PlayerErrorObjNotInitialized` - `PlayerErrorCodecNotSupported` - `PlayerErrorVideoRenderFailed` - `PlayerErrorInvalidState` - `PlayerErrorUrlNotFound` - `PlayerErrorInvalidConnectionState` - `PlayerErrorSrcBufferUnderflow` - `PlayerErrorInterrupted` - `PlayerErrorNotSupported` - `PlayerErrorTokenExpired` - `PlayerErrorUnknown` - `RtmpStreamPublishErrorOk` - `RtmpStreamPublishErrorInvalidArgument` - `RtmpStreamPublishErrorEncryptedStreamNotAllowed` - `RtmpStreamPublishErrorConnectionTimeout` - `RtmpStreamPublishErrorInternalServerError` - `RtmpStreamPublishErrorRtmpServerError` - `RtmpStreamPublishErrorTooOften` - `RtmpStreamPublishErrorReachLimit` - `RtmpStreamPublishErrorNotAuthorized` - `RtmpStreamPublishErrorStreamNotFound` - `RtmpStreamPublishErrorFormatNotSupported` - `RtmpStreamPublishErrorNotBroadcaster` - `RtmpStreamPublishErrorTranscodingNoMixStream` - `RtmpStreamPublishErrorNetDown` - `RtmpStreamPublishErrorInvalidPrivilege` - `RtmpStreamUnpublishErrorOk` #### 删除 [#删除-23] - `startChannelMediaRelay` - `updateChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - `onChannelMediaRelayEvent` - `ChannelMediaRelayEvent` ## v4.2.6 [#v426-4] 该版本于 2023 年 11 月 21 日发布。 ### 问题修复 [#问题修复-116] 该版本修复了在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。 ## v4.2.4 [#v424] 该版本于 2023 年 10 月 24 日发布。 ### 问题修复 [#问题修复-117] 该版本修复了如下问题： `AgoraRtcWrapper` 中的 `CFBundleShortVersionString` 版本号错误，导致 App 无法被提交至 App Store。(macOS) ## v4.2.3 [#v423-4] 该版本于 2023 年 10 月 13 日发布。 ### 新增特性 [#新增特性-100] #### 本地截图上传更新 [#本地截图上传更新-4] 为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动： - [`ContentInspectType`](/zh-CN/api-reference/rtc/electron/enum-contentinspecttype) 中新增 `contentInspectImageModeration` 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。 - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/electron/class-contentinspectconfig) 中新增的 `serverConfig` 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请[联系技术支持](https://ticket.shengwang.cn/)。 此外，该版本还新增了 [`enableContentInspectEx`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) 方法，支持同时对多条视频流截图并上传。 #### 支持 ID3D11Texture2D 渲染 [#支持-id3d11texture2d-渲染-1] 自该版本起，SDK 支持 ID3D11Texture2D 类型的视频格式，提升了游戏场景中视频帧的渲染效果。你可以在调用 [`pushVideoFrame`](/zh-CN/api-reference/rtc/electron/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe) 方法将外部原始视频帧推送到 SDK 时，设置 **format** 为 `VideoTextureId3d11texture2d`；并通过设置 **d3d11_texture_2d** 和 **texture_slice_index** 属性，来确定要使用的 ID3D11Texture2D 纹理对象。 #### 本地视频状态错误码更新 [#本地视频状态错误码更新-1] 为了帮助用户在屏幕共享场景下了解本地视频出错的准确原因，[`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增了如下几组枚举： - `LocalVideoStreamErrorScreenCapturePaused`(23)：屏幕采集已暂停。当前屏幕可能已切换到安全桌面，例如 UAC 对话框或者 Winlogon 桌面。 - `LocalVideoStreamErrorScreenCaptureResumed`(24)：屏幕采集已从暂停状态中恢复。 - `LocalVideoStreamErrorScreenCaptureWindowHidden`(25)：当前屏幕采集的窗口处于隐藏状态，并且在当前屏幕上不可见。 - `LocalVideoStreamErrorScreenCaptureWindowRecoverFromHidden`(26)：进行屏幕采集的窗口已经从隐藏状态中恢复。 - `LocalVideoStreamErrorScreenCaptureWindowRecoverFromMinimized`(27)：进行屏幕采集的窗口已经从最小化状态中恢复。 #### 进阶功能查询 [#进阶功能查询-4] 该版本新增了 [`isFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_isfeatureavailableondevice) 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。 在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。 此外，自该版本起，调用 [`enableVirtualBackground`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 和 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 `-4: ErrNotSupported` 表示该设备不支持开启该功能。 ### 改进 [#改进-117] #### 优化虚拟背景内存占用 [#优化虚拟背景内存占用-4] 该版本升级了虚拟背景算法，降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。 #### 屏幕共享场景优化 [#屏幕共享场景优化-2] 该版本优化了在超高清（4K，60 fps）游戏共享场景下的性能和编码效率，有效降低了屏幕共享时系统资源占用率。 #### 其他改进 [#其他改进-45] 该版本还进行了如下改进： - 当调用 [`setPlaybackSpeed`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，传入非法参数后会返回错误码 `-2`，表示方法中设置了无效的参数，需要重新设置参数。 - 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。 ### 问题修复 [#问题修复-118] 该版本修复了以下问题： - 加入频道偶现的崩溃。(macOS) - 在屏幕共享场景下偶现崩溃、掉帧。(Windows) - 调用一次 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 获取视频截图会收到多次 [`onSnapshotTaken`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 视频截图结果回调。 - 调用 [`playEffect`](/zh-CN/api-reference/rtc/electron/play/audio-effect-file#api_irtcengine_playeffect3) 使用相同的 `soundId` 播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 ### API 变更 [#api-变更-63] #### 新增 [#新增-57] - [`enableContentInspectEx`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) - [`ContentInspectType`](/zh-CN/api-reference/rtc/electron/enum-contentinspecttype) 新增 `contentInspectImageModeration` - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/electron/class-contentinspectconfig) 中新增 `serverConfig` 可选参数 - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 中新增如下枚举： - `LocalVideoStreamErrorScreenCapturePaused` - `LocalVideoStreamErrorScreenCaptureResumed` - `LocalVideoStreamErrorScreenCaptureWindowHidden` - `LocalVideoStreamErrorScreenCaptureWindowRecoverFromHidden` - `LocalVideoStreamErrorScreenCaptureWindowRecoverFromMinimized` - [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/electron/class-externalvideoframe) 中新增 `d3d11_texture_2d` 和 `texture_slice_index` 成员 - [`VideoPixelFormat`](/zh-CN/api-reference/rtc/electron/enum-videopixelformat) 中新增 `VideoTextureId3d11texture2d` 枚举 - [`isFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_isfeatureavailableondevice) - [`FeatureType`](/zh-CN/api-reference/rtc/electron/enum-featuretype) ## v4.2.2 [#v422-4] 该版本于 2023 年 8 月 1 日发布。 ### 新增特性 [#新增特性-101] #### 通配 Token [#通配-token-4] 该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 :::info[信息] 声网 4.x RTC SDK 均支持使用通配 Token。 ::: #### 预加载频道 [#预加载频道-5] 该版本新增 [`preloadChannel`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_preloadchannel) 和 [`preloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_preloadchannelwithuseraccount) 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。 在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 #### 自定义视频画布背景颜色 [#自定义视频画布背景颜色-4] 该版本在 [`VideoCanvas`](/zh-CN/api-reference/rtc/electron/class-videocanvas) 中增加了 `backgroundColor` 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。 #### 发布多源采集的视频流 [#发布多源采集的视频流-2] 该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中新增下列成员，支持你发布第三个、第四个摄像头和屏幕采集到的视频流： - `publishThirdCameraTrack`：发布第三个摄像头采集的视频。 - `publishFourthCameraTrack`：发布第四个摄像头采集的视频。 - `publishThirdScreenTrack`：发布第三个屏幕采集的视频。 - `publishFourthScreenTrack`：发布第四个屏幕采集的视频。 :::info[信息] 目前 SDK 支持在同一时间、同一 `RtcConnection` 中发布多路音频流、一路视频流。 ::: ### 改进 [#改进-118] #### 虚拟背景算法升级 [#虚拟背景算法升级-4] 该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。 #### 跨频道连麦优化 [#跨频道连麦优化-4] 该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 时，你可以指定最多 6 个目标频道。 #### 视频编解码查询能力增强 [#视频编解码查询能力增强-4] 为提升设备编解码能力查询功能，该版本在 [`CodecCapInfo`](/zh-CN/api-reference/rtc/electron/class-codeccapinfo) 中新增 `codecLevels` 成员。当成功调用 [`queryCodecCapability`](/zh-CN/api-reference/rtc/electron/device-management/video-device#api_irtcengine_querycodeccapability) 后，可通过 `codecLevels` 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。 #### 其他改进 [#其他改进-46] - 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。 - 为帮助用户了解更多类型的远端视频状态改变的原因，[`onRemoteVideoStateChanged`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调中新增了 `RemoteVideoStateReasonCodecNotSupport` 枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。 ### 问题修复 [#问题修复-119] 该版本修复了以下问题： - 加入频道后，偶现本地用户听自己及远端的声音时出现杂音。 (macOS) - 网络异常导致频道连接断开后，频道连接恢复较慢。 - 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。 - 自采集场景下，[`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions)、[`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)、[`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 和 [`setColorEnhanceOptions`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions) 无法自动加载插件。 - 多设备音频录制场景下，反复插拔或开启/禁用音频录制设备后，偶现调用 [`startRecordingDeviceTest`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_startrecordingdevicetest) 进行音频采集设备测试时听不到声音。 (Windows) ### API 变更 [#api-变更-64] #### 新增 [#新增-58] - [`preloadChannel`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_preloadchannel) - [`preloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_preloadchannelwithuseraccount) - [`updatePreloadChannelToken`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_updatepreloadchanneltoken) - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中增加下列成员： - `publishThirdCameraTrack` - `publishFourthCameraTrack` - `publishThirdScreenTrack` - `publishFourthScreenTrack` - [`CodecCapLevels`](/zh-CN/api-reference/rtc/electron/class-codeccaplevels) - [`VIDEO_CODEC_CAPABILITY_LEVEL`](/zh-CN/api-reference/rtc/electron/enum-videocodeccapabilitylevel) - [`VideoCanvas`](/zh-CN/api-reference/rtc/electron/class-videocanvas) 中增加 `backgroundColor` 成员 - [`CodecCapInfo`](/zh-CN/api-reference/rtc/electron/class-codeccapinfo) 中增加 `codecLevels` 成员 - [`RemoteVideoStateReason`](/zh-CN/api-reference/rtc/electron/enum-remotevideostatereason) 中增加 `RemoteVideoStateReasonCodecNotSupport` 枚举 ## v4.2.1 [#v421-6] 该版本于 2023 年 6 月 21 日发布。 ### 改进 [#改进-119] 该版本改进了网络传输策略，提升了音视频交互的流畅度。 ### 问题修复 [#问题修复-120] 该版本修复了以下问题： - SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。 - 发送端调用 [`setAINSMode`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。 - 发送端启用屏幕共享功能后，偶现接收端看到共享画面的延迟较高。 (macOS) - 发送端将两路摄像头采集的视频进行本地合图并发布后，接收端偶现第二路摄像头画面缺失。 (Windows) ## v4.2.0 [#v420-6] 该版本于 2023 年 5 月 26 日发布。 ### 升级必看 [#升级必看-66] 该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。 #### 视频采集 (Windows) [#视频采集-windows] 原有用于摄像头和屏幕采集的方法已删除，请改用下表中列出的替代方法，并通过设置 `sourceType` 来指定视频源。 | 已删除方法 | 替代方法 | | --- | --- | | [release-notes-electron-markdown-1-1-0 details](#table-slot-release-notes-electron-markdown-1-1-0) | [`startCameraCapture`](/zh-CN/api-reference/rtc/electron/video/camera-capture#api_irtcengine_startcameracapture) | | [release-notes-electron-markdown-1-2-0 details](#table-slot-release-notes-electron-markdown-1-2-0) | [`stopCameraCapture`](/zh-CN/api-reference/rtc/electron/video/camera-capture#api_irtcengine_stopcameracapture) | | [release-notes-electron-markdown-1-3-0 details](#table-slot-release-notes-electron-markdown-1-3-0) | [`startScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapture2) | | [release-notes-electron-markdown-1-4-0 details](#table-slot-release-notes-electron-markdown-1-4-0) | [`stopScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_stopscreencapture2) | **release-notes-electron-markdown-1-1-0 details** - `startPrimaryCameraCapture` - `startSecondaryCameraCapture` **release-notes-electron-markdown-1-2-0 details** - `stopPrimaryCameraCapture` - `stopSecondaryCameraCapture` **release-notes-electron-markdown-1-3-0 details** - `startPrimaryScreenCapture` - `startSecondaryScreenCapture` **release-notes-electron-markdown-1-4-0 details** - `stopPrimaryScreenCapture` - `stopSecondaryScreenCapture` #### 视频数据获取 [#视频数据获取-4] - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/electron/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/electron/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调中新增了 `sourceType` 参数，用于表示具体的视频源类型。 - 以下回调已删除，请通过 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/electron/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 和 [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/electron/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 中的 `sourceType`参数得知视频源类型。(Windows) - `onSecondaryPreEncodeCameraVideoFrame` (Windows) - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` - `onSecondaryPreEncodeScreenVideoFrame` (Windows) #### 媒体发布选项 [#媒体发布选项-4] - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` 已删除，请改用 `publishCustomAudioTrack`。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中的成员 `publishTrancodedVideoTrack` 变更为 `publishTranscodedVideoTrack。` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中的成员 `publishCustomAudioSourceId` 变更为 `publishCustomAudioTrackId`。 #### 音视频录制 [#音视频录制-4] - 删除 ` InterfaceIdType` 中的 `AgoraIidMediaRecorder`。在创建录制对象前无需再获取 `AgoraIidMediaRecorder` 接口类指针，你可以直接调用该版本新增的 [`createMediaRecorder`](/zh-CN/api-reference/rtc/electron/recording#api_irtcengine_createmediarecorder) 方法创建录制对象。 (Windows) - 删除 `getMediaRecorder` 方法，可通过该版本新增的 [`createMediaRecorder`](/zh-CN/api-reference/rtc/electron/recording#api_irtcengine_createmediarecorder) 方法来创建录制对象。(macOS) - 删除 [`startRecording`](/zh-CN/api-reference/rtc/electron/recording#api_imediarecorder_startrecording) 、[`stopRecording`](/zh-CN/api-reference/rtc/electron/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/electron/recording#api_imediarecorder_setmediarecorderobserver) 中的 `connection` 参数。 - 删除 [`IMediaRecorder`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediarecorder) 类中的 `release` 方法，你可直接调用该版本新增的 [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/electron/recording#api_irtcengine_destroymediarecorder) 方法来销毁录制对象以释放资源。 #### 本地合图 [#本地合图-6] - [`LocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/electron/class-localtranscoderconfiguration) 中的 `VideoInputStreams` 变更为 `videoInputStreams`。 - [`TranscodingVideoStream`](/zh-CN/api-reference/rtc/electron/class-transcodingvideostream) 中的枚举类 [`MediaSourceType`](/zh-CN/api-reference/rtc/electron/enum-mediasourcetype) 变更为 [`VideoSourceType`](/zh-CN/api-reference/rtc/electron/enum-videosourcetype)。 #### 虚拟声卡 (macOS) [#虚拟声卡-macos] 自该版本起，SDK 新增对第三方虚拟声卡的支持，你可以将第三方虚拟声卡作为 SDK 的音频输入或输出设备。你可以通过 `stateChanged` 回调来了解当前 SDK 选择的输入输出设备是否为虚拟声卡。 :::warning[注意] 加频道时如果设置 AgoraALD、Soundflower 作为系统的默认输入或输出设备，会造成无声。 ::: #### 默认分辨率提升 [#默认分辨率提升] 自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。 如果你想自定义视频编码分辨率，可调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法，重新设置视频编码参数配置中的视频编码分辨率。 :::note 由于默认分辨率的提升，会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 其他兼容性变更 [#其他兼容性变更-4] - `onApiCallExecuted` 已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。 - [`IAudioFrameObserver`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_iaudioframeobserver) 类名变更为 [`IAudioPcmFrameSink`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_iaudiopcmframesink)，因此下列方法原型也有相应更新：(Windows) - `onFrame` - [`IMediaPlayer`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediaplayer) 下的 `registerAudioFrameObserver` 和 `unregisterAudioFrameObserver`。 - `startChannelMediaRelay`、`updateChannelMediaRelay`、`startChannelMediaRelayEx` 和 `updateChannelMediaRelayEx` 已废弃，请改用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex)。 ### 新增特性 [#新增特性-102] #### AI 降噪 [#ai-降噪-4] 该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 [`setAINSMode`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。 #### 增强虚拟背景 [#增强虚拟背景-4] 为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 [`enableVirtualBackground`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 方法时，将自定义背景设置为更多类型： - 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。 - 将背景替换为多种格式的本地视频。 #### 视频场景化设置 [#视频场景化设置-4] 该版本新增 [`setVideoScenario`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoscenario) 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化： - 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。 - 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。 #### 本地录制远端音视频 (Beta) [#本地录制远端音视频-beta-4] 该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 [`onRecorderStateChanged`](/zh-CN/api-reference/rtc/electron/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`onRecorderInfoUpdated`](/zh-CN/api-reference/rtc/electron/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数，用于表示录制的音视频流的具体信息，并新增 [`createMediaRecorder`](/zh-CN/api-reference/rtc/electron/recording#api_irtcengine_createmediarecorder) 方法，用于创建本地或远端的录制对象。 你可以通过如下方法体验本地录制远端音视频功能： - [`createMediaRecorder`](/zh-CN/api-reference/rtc/electron/recording#api_irtcengine_createmediarecorder)：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。 - [`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/electron/recording#api_imediarecorder_setmediarecorderobserver)：设置录制回调对象。 - [`startRecording`](/zh-CN/api-reference/rtc/electron/recording#api_imediarecorder_startrecording)：开始录制。 - [`stopRecording`](/zh-CN/api-reference/rtc/electron/recording#api_imediarecorder_stoprecording)：停止录制。 - [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/electron/recording#api_irtcengine_destroymediarecorder)：销毁录制对象。 #### 本地合图 [#本地合图-7] 自该版本起，本地合图功能支持 macOS。此外，该版本新增了 [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调，当你在开启本地合图或者更新本地合图配置失败时，SDK 会触发该回调并报告合图失败的原因。 #### 多端同步 [#多端同步-4] 在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_getntpwalltimeinms) 方法获取当前的 NTP (网络时间协议) 时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。 #### 快速出图出声 [#快速出图出声-4] 该版本新增 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_enableinstantmediarendering) 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。 #### 视频渲染数据打点 [#视频渲染数据打点-4] 该版本新增 [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_startmediarenderingtracing) 和 [`startMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/electron/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告相关事件的信息。 声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/electron/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。 ### 改进 [#改进-120] #### 优化变声 [#优化变声-4] 该版本新增了 [`setLocalVoiceFormant`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceformant) 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 [`setLocalVoicePitch`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch) 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。 #### 提升渲染兼容性 (Windows) [#提升渲染兼容性-windows] 提升了渲染的兼容性，解决了部分设备渲染失败而导致的黑屏问题。 #### 提升音视频同步能力 [#提升音视频同步能力-4] 针对自定义视频和音频采集场景，该版本新增 [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_getcurrentmonotonictimeinms) 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。 #### 优化多路摄像头及屏幕采集 [#优化多路摄像头及屏幕采集-2] 该版本新增 [`startCameraCapture`](/zh-CN/api-reference/rtc/electron/video/camera-capture#api_irtcengine_startcameracapture) 和 [`startScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapture2) 方法，通过多次调用并指定 `sourceType` 参数可以开启多路摄像头采集的视频流和多路屏幕采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头和显示器的场景。 #### 优化跨频道连麦 [#优化跨频道连麦-4] 该版本新增 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。 #### 多路音频自采集 [#多路音频自采集-4] 为更好地满足音频自采集的场景需求，该版本新增了 [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 和 [`destroyCustomAudioTrack`](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_destroycustomaudiotrack) 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性： - 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。 - 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。 #### 视频观测器 [#视频观测器-4] 自该版本起，SDK 对 [`onRenderVideoFrame`](/zh-CN/api-reference/rtc/electron/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 回调进行了优化，在不同的视频处理模式下返回值的意义不同： - 当视频处理模式为 `ProcessModeReadOnly` 时，返回值无实际含义。 - 当视频处理模式为 `ProcessModeReadWrite` 时，返回 `true` 代表设置 SDK 接收视频帧；返回 `false` 代表设置 SDK 丢弃视频帧。 ### 问题修复 [#问题修复-121] 该版本修复了以下问题： - 当快速切换身份角色时，观众端听不到声音。 - 接收端默认接收小流几秒后自动变为大流。(macOS)。 - 屏幕共享偶现共享画面抖动。(macOS) - 使用媒体播放器播放网络摄像头的 RTSP 码流时，偶现花屏。 (Windows) - 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。 - 把播放器的渲染视图设为 UIViewController 的视图后，使用播放器播放视频，视频窗口切到全屏时视频画面会从左下角开始逐渐放大。 (macOS) - 在本地合图场景下，不支持对 PNG 和 GIF 图片的 Alpha 通道渲染，导致透明底色的图片显示为非透明底色。 - 加入频道后添加水印然后删除，远端仍能看到水印。 (Windows) - 开始屏幕共享后添加水印，远端接收的屏幕共享画面没有水印。 (Windows) - 加入频道后接入外接摄像头，调用 [`setDevice`](/zh-CN/api-reference/rtc/electron/device-management/video-device#api_ivideodevicemanager_setdevice_ivideodevicemanager) 指定视频采集设备为该外接摄像头，方法未生效。 - 在屏幕共享场景下，如果将一个窗口设置为前置和描边，则必现窗口前置失败。(Windows) - 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。 - 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。 ### API 变更 [#api-变更-65] #### 新增 [#新增-59] - [`startCameraCapture`](/zh-CN/api-reference/rtc/electron/video/camera-capture#api_irtcengine_startcameracapture) - [`stopCameraCapture`](/zh-CN/api-reference/rtc/electron/video/camera-capture#api_irtcengine_stopcameracapture) - [`startScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapture2) - [`stopScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_stopscreencapture2) - [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) - [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) - [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_getntpwalltimeinms) - [`setVideoScenario`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoscenario) - [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_getcurrentmonotonictimeinms) - [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) - [`startLocalVideoTranscoder`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) (Mac) - [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) (Mac) - [`setAINSMode`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) - [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) - [`destroyCustomAudioTrack`](/zh-CN/api-reference/rtc/electron/audio/audio-custom-capturenrendering#api_imediaengine_destroycustomaudiotrack) - [`createMediaRecorder`](/zh-CN/api-reference/rtc/electron/recording#api_irtcengine_createmediarecorder) - [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/electron/recording#api_irtcengine_destroymediarecorder) - [`AudioTrackConfig`](/zh-CN/api-reference/rtc/electron/class-audiotrackconfig) - [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/electron/class-recorderstreaminfo) - [`AudioAinsMode`](/zh-CN/api-reference/rtc/electron/enum-audioainsmode) - [`AudioTrackType`](/zh-CN/api-reference/rtc/electron/enum-audiotracktype) - [`VideoApplicationScenarioType`](/zh-CN/api-reference/rtc/electron/enum-videoapplicationscenariotype) - `ScreenCaptureFramerateCapability` - [`RtcEngineContext`](/zh-CN/api-reference/rtc/electron/class-rtcengineconfig) 中新增 `domainLimit` 和 `autoRegisterAgoraExtensions` 属性 - [`onRecorderStateChanged`](/zh-CN/api-reference/rtc/electron/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`onRecorderInfoUpdated`](/zh-CN/api-reference/rtc/electron/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数 - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/electron/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/electron/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 中增加 `sourceType` 参数 - [`BackgroundSourceType`](/zh-CN/api-reference/rtc/electron/enum-backgroundsourcetype) 中新增 `BackgourndNone` 和 `BackgroundVideo` - [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_enableinstantmediarendering) - [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_startmediarenderingtracing) - [`startMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) - [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/electron/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) - [`MediaTraceEvent`](/zh-CN/api-reference/rtc/electron/enum-mediatraceevent) - [`VideoRenderingTracingInfo`](/zh-CN/api-reference/rtc/electron/class-videorenderingtracinginfo) #### 废弃 [#废弃-20] - `startChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelay` - `updateChannelMediaRelayEx` - `onChannelMediaRelayEvent` - `ChannelMediaRelayEvent` #### 删除 [#删除-24] - `startPrimaryScreenCapture ` - `startSecondaryScreenCapture` - `stopPrimaryScreenCapture` - `stopSecondaryScreenCapture` - `startPrimaryCameraCapture` - `startSecondaryCameraCapture` - `stopPrimaryCameraCapture` - `stopSecondaryCameraCapture` - `onSecondaryPreEncodeCameraVideoFrame` (Windows) - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` - `onSecondaryPreEncodeScreenVideoFrame` (Windows) - `onApiCallExecuted` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` - `getMediaRecorder` - [`IMediaRecorder`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediarecorder) 类中的 `release` - `AgoraIidMediaRecorder` (Windows) - [`startRecording`](/zh-CN/api-reference/rtc/electron/recording#api_imediarecorder_startrecording)、[`stopRecording`](/zh-CN/api-reference/rtc/electron/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/electron/recording#api_imediarecorder_setmediarecorderobserver) 中删除 `connection` 参数 ## v4.1.0 [#v410-5] 该版本于 2022 年 12 月 20 日发布。 ### 升级必看 [#升级必看-67] 如果你已经使用了以下类或方法，请在升级到该版本后重新调用方法并更新参数设置： 删除了 [`enableDualStreamMode`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_enabledualstreammode3) 中的 `sourceType` 参数，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。 ### 新增特性 [#新增特性-103] #### 耳返 [#耳返-4] 该本版新增耳返功能。你可以调用 [`enableInEarMonitoring`](/zh-CN/api-reference/rtc/electron/audio/audio-capture#api_irtcengine_enableinearmonitoring2) 开启耳返功能。 如需调节耳返音量，你可以调用 [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/electron/audio/audio-capture#api_irtcengine_setinearmonitoringvolume)。 #### 本地网络连接类型 [#本地网络连接类型-4] 为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 [`getNetworkType`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_getnetworktype) 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 [`onNetworkTypeChanged`](/zh-CN/api-reference/rtc/electron/network#callback_irtcengineeventhandler_onnetworktypechanged) 回调，报告当前的网络连接类型。 #### 音强选流 [#音强选流-4] 声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请联系技术支持。 同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗，详见[音强选流](/zh-CN/realtime-media/rtc/build/audio/audio-stream-filter)。 :::info[信息] 该版本新增音强选流功能，如需开启该功能，请联系[技术支持](https://ticket.shengwang.cn/)。 ::: #### 双流模式 [#双流模式-5] 该版本对双流模式做了优化，在加入频道前后均可调用 [`enableDualStreamMode`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_enabledualstreammode3) 和 [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_enabledualstreammodeex)。 扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式（即：默认不主动发送小流），可通过以下步骤开启发送小流： 1. 接收端主播调用 [`setRemoteVideoStreamType`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setremotevideostreamtype) 或 [`setRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 发起接收小流申请。 2. 发送端收到申请后自动切换为发送小流模式。 如果你想修改上述发送端的默认行为，可以调用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setdualstreammode2) 方法，将 `mode` 参数设置为 `disableSimulcastStream` (始终不发送小流) 或 `enableSimulcastStream` (始终发送小流)。 #### 声卡采集设备 (Windows) [#声卡采集设备-windows] SDK 默认使用播放设备为声卡采集设备，自该版本起，你可以另外指定声卡采集设备并将其采集到的音频发布到远端。 - [`setLoopbackDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_setloopbackdevice)：用于指定声卡采集设备，当你不希望当前的播放设备为声卡采集设备时，可以调用该方法另外指定别的设备作为声卡采集设备。 - [`getLoopbackDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_getloopbackdevice)：用于获取当前的声卡采集设备。 - [`followSystemLoopbackDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_followsystemloopbackdevice)：用于设置声卡采集设备是否跟随系统默认的播放设备。 #### 空间音频 [#空间音频-8] 该版本新增了如下适用于空间音频场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。 - 隔声区域：你可以通过调用 [`setZones`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 设置隔声区域和声音衰减系数。当音源 (可以为用户或媒体播放器) 跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用 [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 和 [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) 方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖 [`setZones`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 中的声音衰减系数。 - 多普勒音效：你可以通过设置 [`SpatialAudioParams`](/zh-CN/api-reference/rtc/electron/class-spatialaudioparams) 中的 `enable_doppler` 参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下（比如赛车游戏场景），接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用 [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 方法使用预设的耳机均衡效果，以改善耳机的听感。如果在调用 [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。 #### 已编码视频帧观测器 [#已编码视频帧观测器-3] 该版本新增 [`setRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) 和 [`setRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) 方法，当你调用 [`registerVideoEncodedFrameObserver`](/zh-CN/api-reference/rtc/electron/video/video-encoded#api_imediaengine_registervideoencodedframeobserver) 方法为编码后的视频注册视频帧观测器时，SDK 默认订阅编码后的视频帧。如果你想要修改订阅选项，可以调用新增的方法进行设置。 有关更多注册视频观测器和订阅选项的介绍，详见 [API 参考](/zh-CN/api-reference/rtc/electron/video/video-encoded#api_imediaengine_registervideoencodedframeobserver)。 #### MPUDP (MultiPath UDP) [#mpudp-multipath-udp-4] 自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在不同终端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。 :::info[信息] 如果你希望体验该功能，请联系 sales@shengwang.cn。 ::: #### 注册插件 (Windows) [#注册插件-windows] 该版本新增 [`registerExtension`](/zh-CN/api-reference/rtc/electron/extension#api_irtcengine_registerextension) 方法，用于注册插件。当使用第三方插件时，你需要按照以下顺序调用插件相关的 API： 调用 [`loadExtensionProvider`](/zh-CN/api-reference/rtc/electron/extension#api_irtcengine_loadextensionprovider) -> [`registerExtension`](/zh-CN/api-reference/rtc/electron/extension#api_irtcengine_registerextension) -> [`setExtensionProviderProperty`](/zh-CN/api-reference/rtc/electron/extension#api_irtcengine_setextensionproviderproperty) -> [`enableExtension`](/zh-CN/api-reference/rtc/electron/extension#api_irtcengine_enableextension)。 #### 设备管理 [#设备管理-2] 该版本新增了一系列回调，帮助你更好地了解音视频设备的状态。 - [`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/electron/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged)：当视频设备的状态发生改变时上报。 - [`onAudioDeviceStateChanged`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicestatechanged)：当音频设备的状态发生改变时上报。 - [`onAudioDeviceVolumeChanged`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicevolumechanged)：当音频设备或 App 的音量发生改变时上报。 #### 摄像头采集选项 [#摄像头采集选项-4] 该版本在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/electron/class-cameracapturerconfiguration) 中增加了 `followEncodeDimensionRatio` 成员参数，你可以在使用摄像头采集视频时，通过该成员参数设置是否跟随 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中已经设置的视频宽高比。 #### 多频道管理 [#多频道管理-4] 该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。 - 新增 [`muteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) 和 [`muteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) 方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增 [`muteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) 和 [`muteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) 方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增 [`startRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex)、[`startRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex)、[`updateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) 和 [`stopRtmpStreamEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) 方法，用于实现多频道场景下的旁路推流。 - 新增 `startChannelMediaRelayEx`、`updateChannelMediaRelayEx`、[`pauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex)、[`resumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) 和 [`stopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) 方法，用于实现多频道场景下的跨频道媒体流转发。 - [`leaveChannelEx`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengineex_leavechannelex2) 方法新增 `options` 参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。 #### 视频编码偏好 [#视频编码偏好-4] 一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/electron/class-videoencoderconfiguration) 中新增 `advanceOptions` 成员参数，用于视频编码属性的进阶设置： - `compressionPreference`：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。 - `encodingPreference`：视频编码器偏好设置，用于进阶设置视频编码属性，视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。 #### 日志上传 [#日志上传-4] 使用声网私有媒体服务器的场景下，为支持用户在调用 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_setlocalaccesspoint) 方法时的进阶设置，该版本在 [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/electron/class-localaccesspointconfiguration)中新增 `advancedConfig` 成员参数，该参数支持如下设置： - `logUploadServer`：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。 #### 用户角色切换 [#用户角色切换-4] 为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 [`onClientRoleChanged`](/zh-CN/api-reference/rtc/electron/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调中新增 `newRoleOptions` 参数，该参数取值如下： - `AudienceLatencyLevelLowLatency`(1): 低延时，属于极速直播。 - `AudienceLatencyLevelUltraLowLatency`(2): 超低延时，属于互动直播。 ### 改进 [#改进-121] #### 视频信息发生改变回调 [#视频信息发生改变回调-4] 该版本优化了 [`onVideoSizeChanged`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged) 的触发逻辑，当单独调用 [`startPreview`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_startpreview2) 时，也可触发该回调并上报本地视频大小发生改变。 #### 首帧出图 (Windows) [#首帧出图-windows] 该版本缩短了首帧出图时间，以提升用户视频体验。 #### 屏幕共享 [#屏幕共享-7] 该版本对屏幕共享功能做了一系列优化，除以下列出的功能性改进之外，还有一部分可用性提升，详见[问题修复](#问题修复-121)。 All Windows macOS - 支持超高清视频 (分辨率为 4K，帧率为 60 fps)，你可以在满足要求的设备上使用该功能。声网推荐的最低设备规格为：intel(R) Core(TM) i7-9750H CPU @ 2.60GHZ。 - 在 [`ScreenCaptureSourceInfo`](/zh-CN/api-reference/rtc/electron/class-screencapturesourceinfo) 中增加了 `minimizeWindow` 成员，用于表示目标窗口是否已最小化。 - 在 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters) 中增加了 `enableHighLight`、`highLightColor` 和 `highLightWidth` 成员，支持你在屏幕共享时对目标窗口或屏幕进行描边。 - 兼容更多主流 App，包括但不限于：WPS Office，Microsoft Office PowerPoint，Visual Studio Code，Adobe Photoshop，Windows Media Player，Scratch。 - 兼容更多设备和操作系统，包括但不限于：Windows 8 系统，无独立显卡的设备，双显卡设备。 - 兼容更多设备和场景，包括但不限于：双显卡设备，使用外接屏幕进行屏幕共享。 #### CDN 推流 [#cdn-推流-4] 为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 `onDirectCdnStreamingStats` 回调报告推送的视频流的实际分辨率。 #### 跨频道媒体流转发 [#跨频道媒体流转发-9] 该版本对 `updateChannelMediaRelay` 方法做了如下优化： - 4.1.0 版本前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码 `RelayEventPacketUpdateDestChannelRefused `(8)，你需要重新调用 `updateChannelMediaRelay` 方法。 - 4.1.0 版本及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。 #### AIAEC [#aiaec-4] 该版本基于 AI 方法重构了 AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。 #### 虚拟背景 [#虚拟背景-4] 该版本对虚拟背景算法做了如下优化： - 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。 - 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。 - 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。 - 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。 #### 其他改进 [#其他改进-47] - 降低了推送外部音频源时的上行延迟。 - 提升了会议场景 (`audioScenarioMeeting`) 默认参数配置下的回声消除性能。 - 提升了 SDK 视频渲染的流畅度。 - 降低了当主播调用 [`muteLocalVideoStream`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_mutelocalvideostream) 方法时本地设备的 CPU 占用率和耗电量。 - 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。 ### 问题修复 [#问题修复-122] 该版本修复了以下问题： All Windows macOS - 在频道内调用 [`setVideoEncoderConfigurationEx`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengineex_setvideoencoderconfigurationex) 将视频的分辨率调高时，偶现失效。 - 使用媒体播放器播放视频，先调用 [`play`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 再调用 [`pause`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用 [`resume`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_resume) 恢复播放后，偶现视频画面出现快进。 - 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。 - 调用 [`getExtensionProperty`](/zh-CN/api-reference/rtc/electron/extension#api_irtcengine_getextensionproperty2) 失败，返回空字符串。 - 当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。 - 通过摄像头采集视频时，如果在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/electron/class-cameracapturerconfiguration) 中设置的视频宽高比例和在 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中设置的不一致，导致本地视频预览的画面比例未按照后者的设置呈现。 - 在屏幕共享场景下，偶现系统声音音量变小。 - 在屏幕共享场景下，远端用户看到的画面偶现黑屏、卡顿、崩溃。 - 在屏幕共享场景下，偶现 [`onNetworkQuality`](/zh-CN/api-reference/rtc/electron/network#callback_irtcengineeventhandler_onnetworkquality) 回调报告频道内指定用户的上下行网络状态不准确。 - 调用 [`stopPreview`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_stoppreview2) 关闭本地视频预览时，导致已设置的虚拟背景一定概率失效。 - 开启虚拟背景并设置为背景虚化效果时，多次退出频道再加入频道时偶现崩溃。 - 本地端使用 1920 x 1080 的摄像头作为视频采集源，偶现远端视频的分辨率与本地端不一致。 - 在屏幕共享场景下，将共享的窗口最小化时，偶现远端用户出现黑屏或远端画面切换为视频小流。 - 在直播场景下，主播开启屏幕共享时，偶现观众听主播说话有回声。 - 在屏幕共享场景下，在横屏显示器与竖屏显示器之间共享屏幕时出现黑屏。 - 调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 进行屏幕共享时无法屏蔽窗口。 - 在屏幕共享场景下，在共享窗口中看到的鼠标位置与实际位置有偏差。 - 从普通场景切换屏幕共享场景后，由于两种场景下设置的分辨率不同导致偶现崩溃。 - 在屏幕共享场景下，将共享的窗口最小化或关闭共享窗口时，共享窗口自动切换为该 App 的其他窗口。 - 在屏幕共享场景下，当共享的窗口为半屏模式时，对窗口的描边不正确。 - 启动并停止音频采集设备测试后，启动音频播放设备测试时必现无声。 - [`onVideoPublishStateChanged`](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 回调报告的视频源类型不准确。 ### API 变更 [#api-变更-66] #### 新增 [#新增-60] - [`getNativeHandle`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_getnativehandle) - [`getPlaybackDefaultDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_getplaybackdefaultdevice) - [`getRecordingDefaultDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_getrecordingdefaultdevice) - [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_enabledualstreammodeex) - [`setDualStreamMode`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setdualstreammode2) - [`setDualStreamModeEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_setdualstreammodeex) - [`SimulcastStreamMode`](/zh-CN/api-reference/rtc/electron/enum-simulcaststreammode) - [`getNetworkType`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_getnetworktype) - [`setLoopbackDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_setloopbackdevice) (Windows) - [`getLoopbackDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_getloopbackdevice) (Windows) - [`followSystemLoopbackDevice`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#api_iaudiodevicemanager_followsystemloopbackdevice) (Windows) - [`setZones`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) - [`HeadphoneEqualizerPreset`](/zh-CN/api-reference/rtc/electron/enum-headphoneequalizerpreset) - [`setRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) - [`setRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) - [`VideoSubscriptionOptions`](/zh-CN/api-reference/rtc/electron/class-videosubscriptionoptions) - `AdvancedOptions` - [`EncodingPreference`](/zh-CN/api-reference/rtc/electron/enum-encodingpreference) - [`CompressionPreference`](/zh-CN/api-reference/rtc/electron/enum-compressionpreference) - [`adjustUserPlaybackSignalVolumeEx`](/zh-CN/api-reference/rtc/electron/audio/audio-basic#api_irtcengineex_adjustuserplaybacksignalvolumeex) - [`RhythmPlayerStateType`](/zh-CN/api-reference/rtc/electron/enum-rhythmplayerstatetype) - `RhythmPlayerErrorType` - [`enableAudioVolumeIndicationEx`](/zh-CN/api-reference/rtc/electron/audio/audio-basic#api_irtcengineex_enableaudiovolumeindicationex) - [`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/electron/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) - [`onAudioDeviceStateChanged`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicestatechanged) - [`onAudioDeviceVolumeChanged`](/zh-CN/api-reference/rtc/electron/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicevolumechanged) - [`registerExtension`](/zh-CN/api-reference/rtc/electron/extension#api_irtcengine_registerextension) (Windows) - [`muteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) - [`muteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) - [`muteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) - [`muteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) - [`startRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex) - [`startRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex) - [`updateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) - [`stopRtmpStreamEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - [`pauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex) - [`resumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) - [`stopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/electron/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) - [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/electron/class-localaccesspointconfiguration) - [`AdvancedConfigInfo`](/zh-CN/api-reference/rtc/electron/class-advancedconfiginfo) - [`LogUploadServerInfo`](/zh-CN/api-reference/rtc/electron/class-loguploadserverinfo) #### 修改 [#修改-15] - [`enableDualStreamMode`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_enabledualstreammode3)：删除 `sourceType` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions)：新增 `isAudioFilterable` - [`enableInEarMonitoring`](/zh-CN/api-reference/rtc/electron/audio/audio-capture#api_irtcengine_enableinearmonitoring2)：支持 PC 端 - [`setEarMonitoringAudioFrameParameters`](/zh-CN/api-reference/rtc/electron/audio/audio-raw#api_irtcengine_setearmonitoringaudioframeparameters)：支持 PC 端 - [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/electron/audio/audio-capture#api_irtcengine_setinearmonitoringvolume)：支持 PC 端 - [`onEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/electron/audio/audio-raw#callback_iaudioframeobserverbase_onearmonitoringaudioframe)：支持 PC 端 - [`SpatialAudioParams`](/zh-CN/api-reference/rtc/electron/class-spatialaudioparams)：新增 `enable_doppler` - [`ScreenCaptureSourceInfo`](/zh-CN/api-reference/rtc/electron/class-screencapturesourceinfo)：新增 `minimizeWindow` - [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/electron/class-screencaptureparameters)：支持 Windows 平台 - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/electron/class-cameracapturerconfiguration)：新增 `followEncodeDimensionRatio` - [`leaveChannelEx`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengineex_leavechannelex2)：新增 `options` - [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/electron/class-videoencoderconfiguration)：新增 `advanceOptions` - [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/electron/class-localaccesspointconfiguration)：新增 `advancedConfig` - [`onClientRoleChanged`](/zh-CN/api-reference/rtc/electron/channel#callback_irtcengineeventhandler_onclientrolechanged)：新增 `newRoleOptions` - [`VideoCanvas`](/zh-CN/api-reference/rtc/electron/class-videocanvas)：新增 `setupMode`、`mediaPlayerId` 和 `cropArea` - [`LocalVideoStats`](/zh-CN/api-reference/rtc/electron/class-localvideostats)：新增 `hwEncoderAccelerating` #### 废弃 [#废弃-21] - `onApiCallExecuted` - `ChannelMediaRelayEvent`：废弃 `RelayEventPacketUpdateDestChannelRefused `(8) ## v4.0.0 [#v400-5] 该版本于 2022 年 9 月 29 日发布。 ### 升级必看 [#升级必看-68] #### 兼容性变更 [#兼容性变更-3] v4.0.0 SDK 包名由 `electron-agora-rtc-ng` 变更为 `agora-electron-sdk`，且对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。如下为存在兼容性变更的主要功能： - 多频道 - 媒体流发布控制 - 警告码 升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见[迁移指南](/zh-CN/realtime-media/rtc/reference/migration-guide)。 ### 新增特性 [#新增特性-104] #### 多路媒体流 [#多路媒体流-4] 该版本支持通过设置 [`IRtcEngineEx`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengineex) 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions)，实现一个 [`IRtcEngine`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine) 实例同时采集多路音视频源并发布到远端，适应各种业务场景。例如： - 调用 [`joinChannel`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 加入首个频道后，多次调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengineex_joinchannelex) 加入多个频道，通过不同的用户 ID 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 设置发布指定的流到不同的频道。 - 支持通过设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中的 `publishSecondaryCameraTrack` 和 `publishSecondaryScreenTrack` 同时发布多路摄像头采集或者屏幕共享的视频流。 同时，该版本支持通过 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/electron/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流： 1. 创建自采集视频轨道：调用 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/electron/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法创建一个自定义视频轨道，并获得视频轨道 ID。 2. 设置频道中待发布的自采集视频轨道：在每个频道的 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中，将 `customVideoTrackId` 参数设置为你想要发布的视频轨道 ID，并将 `publishCustomVideoTrack` 设置为 `true`。 3. 推送外部视频源：调用 [`pushVideoFrame`](/zh-CN/api-reference/rtc/electron/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe)，并将 `videoTrackId` 指定为你想要发布的自定义视频轨道 ID，即可根据步骤 2 的设置，实现在多个频道中发布对应的自定义视频源。 结合多频道能力，你还可以体验如下功能： - 将多组音视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路音频流混音后通过一个用户 ID (`uid`) 发布到远端。 - 将多组视频频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路视频流合图后通过一个用户 ID (`uid`) 发布到远端。 #### 超高清分辨率 (Beta) [#超高清分辨率-beta-2] 为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持 4K 分辨率。优化了 FEC（Forward Error Correction）算法，可根据视频帧包数与帧率进行自适应切换，降低 4K 场景下的视频卡顿率。 你可以在调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 时，设置编码分辨率为 4K (3840 × 2160)、帧率为 60 fps。当你的设备不支持 4K 时，SDK 支持自动回退到适合的分辨率和帧率。 该功能对设备性能和网络带宽有一定要求，在不同的平台上支持的上下行帧率也不同，如需体验该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 :::info[信息] 高分辨率可能会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 内置媒体播放器 [#内置媒体播放器-4] 为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 [`createMediaPlayer`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer) 创建媒体播放器后，你可以通过 [`IMediaPlayer`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediaplayer) 类的一系列方法体验内置媒体播放器的各类功能： - 自动播放本地、在线、自定义的媒体资源。 - 预先加载待播放的媒体资源。 - 根据网络情况切换媒体资源的播放线路。 - 将媒体播放器的音视频流推送到任意频道、分享给远端用户。 - 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。 #### 新版 AI 降噪 [#新版-ai-降噪-4] 自该版本起，SDK 支持新版 AI 降噪（相对于 v3.7.0 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。 如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。 #### 超高音质 [#超高音质-4] 为还原音频的细节、提升音频的清晰度，该版本新增 `UltraHighQualityVoice`。在语聊、歌唱等以人声为主的场景中，你可以调用 [`setVoiceBeautifierPreset`](/zh-CN/api-reference/rtc/electron/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) 并使用该枚举体验超高音质。 #### 实时合唱 [#实时合唱-4] 该版本为实时合唱赋予了如下能力： - 支持两人及两人以上合唱。 - 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。 - 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。 该版本新增 `AudioScenarioChorus` 枚举来设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。 #### 增强的频道管理 [#增强的频道管理-4] 为满足各类业务场景对频道管理的需求，该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 结构体中新增了如下功能： - 设置或切换多种音视频源的发布 - 设置或切换频道场景、用户角色 - 设置或切换订阅视频的大小流类型 - 控制音频发布时延 在调用 [`joinChannel`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 或 [`joinChannelEx`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengineex_joinchannelex) 时设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions)，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_updatechannelmediaoptions) 随时更新 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/class-channelmediaoptions) 中的设置，例如，切换发布的音视频源。 #### 屏幕共享 [#屏幕共享-8] 该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享： - 在加入频道前调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebydisplayid)，然后调用 `joinChannel`[2/2] 加入频道并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `true`，即可开始屏幕共享。 - 在加入频道后调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/electron/video/screencapture#api_irtcengine_startscreencapturebydisplayid)，然后调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_updatechannelmediaoptions) 设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `true`，即可开始屏幕共享。 #### 设置音视频流订阅黑/白名单 [#设置音视频流订阅黑白名单-4] 该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通 [`IRtcEngineEx`](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengineex) 类下的同名方法来实现该功能。 - [`setSubscribeAudioBlocklist`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setsubscribeaudioblocklist)：设置音频订阅黑名单。 - [`setSubscribeAudioAllowlist`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setsubscribeaudioallowlist)：设置音频订阅白名单。 - [`setSubscribeVideoBlocklist`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setsubscribevideoblocklist)：设置视频订阅黑名单。 - [`setSubscribeVideoAllowlist`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setsubscribevideoallowlist)：设置视频订阅白名单。 如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。 #### 设置音频场景 [#设置音频场景-4] 为方便用户灵活修改音频场景，该版本新增 [`setAudioScenario`](/zh-CN/api-reference/rtc/electron/audio/audio-basic#api_irtcengine_setaudioscenario) 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (`AudioScenarioDefault`) 切换为高音质场景 (`AudioScenarioGameStreaming`)，你可以调用该方法。 #### 设置本地代理 [#设置本地代理-4] 该本版新增 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/electron/network#api_irtcengine_setlocalaccesspoint) 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。 #### 垫片推流 [#垫片推流-5] 该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 来开启该功能，并通过 `options` 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。 #### 本地合图 [#本地合图-8] 该版本新增本地合图功能，可支持在本地将多路视频流合并为一路视频流。常见场景如下： 在直播场景或使用旁路推流功能时，可以在本地将多个主播的画面合并为一个画面。 将本地采集的多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）合并为一路视频流，然后在频道内发布已合图的视频流。 你可以调用 [`startLocalVideoTranscoder`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) 方法开启本地合图、调用 [`stopLocalVideoTranscoder`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/local-transcoder#api_irtcengine_stoplocalvideotranscoder) 方法停止本地合图；在开启本地合图后，可以调用 [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/electron/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 进行本地合图的配置更新。 #### 视频设备管理 [#视频设备管理-1] 视频采集设备可能支持多种视频格式，每一种格式都支持不同的视频帧宽度、视频帧高度、帧率组合。 该版本新增 [`numberOfCapabilities`](/zh-CN/api-reference/rtc/electron/device-management/video-device#api_ivideodevicemanager_numberofcapabilities) 和 [`getCapability`](/zh-CN/api-reference/rtc/electron/device-management/video-device#api_ivideodevicemanager_getcapability) 方法，用于获取视频采集设备支持的视频格式数量以及指定视频格式下的视频帧详细信息。在调用 `startPrimaryCameraCapture` 或 `startSecondaryCameraCapture` 方法使用摄像头采集视频时，你可以使用指定的视频格式进行采集。 SDK 会根据你在 [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/electron/class-videoencoderconfiguration) 中的设置，自动选择选择视频采集设备的最佳视频格式进行采集。一般情况下，你不需要用到该组新增方法。 ### 改进 [#改进-122] #### 快速切换频道 [#快速切换频道-4] 该版本通过 [`leaveChannel`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_leavechannel2) 和 [`joinChannel`](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 切换频道即可实现和 v3.7.0 中 `switchChannel` 一样的切换速度，无需额外调用 `switchChannel` 方法。 #### 推送外部视频帧 [#推送外部视频帧-4] 该版本新增支持推送 I422 格式的外部视频帧，你可以通过 `pushVideoFrame`[1/2] 方法将 I422 格式的外部视频帧推送至 SDK。 #### 本地人声音调 [#本地人声音调-4] 该版本在 `onAudioVolumeIndication` 的 [`AudioVolumeInfo`](/zh-CN/api-reference/rtc/electron/class-audiovolumeinfo) 中新增 `voicePitch` 参数。你可以通过 `voicePitch` 获取本地用户的人声音调，从而实现唱歌评分等业务功能。 #### 本地视频预览 [#本地视频预览-4] 该版本优化了 [`startPreview`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_startpreview2) 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 [`startPreview`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_startpreview2) 方法来开启视频预览，无调用时序要求。 #### 订阅视频流 [#订阅视频流-4] 你可以通过 [`setRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/electron/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。 ### 已知问题和局限性 [#已知问题和局限性-1] **系统兼容性说明** 统信 OS 版本基于标准 Electron SDK 进行适配和优化，专门针对国产操作系统和芯片架构进行了兼容性验证。 ## v4.5.40-rc.2 [#v4540-rc2] 该版本于 2025 年 9 月 29 日发布，基于 RTC Native v4.5.1 开发。 ### 系统兼容性 [#系统兼容性] - 支持的芯片架构：**海光 C86**，兼容 x86-64 架构，支持海光系列处理器 - 支持的操作系统：**统信 OS**，统信桌面操作系统 V20 及以上版本 ### 功能特性 [#功能特性] #### 音视频通话 [#音视频通话] - 支持一对一音视频通话（1v1） - 支持一对多音视频通话（1vN） - 支持多人音视频会议（NvN） #### 视频能力 [#视频能力] - **屏幕共享**：支持全屏共享、窗口共享、区域共享 - **基础美颜**：支持磨皮、美白等基础美颜功能 #### 音频能力 [#音频能力] - **基础降噪**：支持环境噪音抑制 - **回声消除**：支持声学回声消除 (AEC) #### 基础能力 [#基础能力] - **网络检测**：支持网络质量检测和上报 - **设备检测**：支持音视频设备枚举和状态检测 ### SDK 下载 [#sdk-下载] 前往[下载页](/zh-CN/realtime-media/rtc/reference/downloads)获取 SDK。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="unity" /> ### 已知问题和局限性 [#已知问题和局限性-2] **AirPods Pro 蓝牙连接问题 (iOS)** 由于 AirPods Pro 不支持在通话音量模式下使用 A2DP 协议，可能会导致该设备在该模式下无法成功连接。 ## v4.6.2 [#v462-6] 该版本于 2026 年 3 月 5 日发布。 ### 升级必看 [#升级必看-69] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的废弃及删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 直推 CDN 相关接口废弃 [#直推-cdn-相关接口废弃-5] 该版本废弃直推 CDN 功能的相关接口，并会在后续版本中删除，请改用[服务端旁路推流](/zh-CN/realtime-media/media-push)。 - `SetDirectCdnStreamingAudioConfiguration` - `SetDirectCdnStreamingVideoConfiguration` - `StartDirectCdnStreaming` - `StopDirectCdnStreaming` - `DirectCdnStreamingMediaOptions` - `DirectCdnStreamingStats` - `DIRECT_CDN_STREAMING_STATE` - `DIRECT_CDN_STREAMING_REASON` #### 虚拟节拍器接口废弃 [#虚拟节拍器接口废弃-5] 该版本废弃虚拟节拍器功能的相关接口，并会在后续版本中删除。 - [`StartRhythmPlayer`](/zh-CN/api-reference/rtc/unity/play/rhythmplayer#api_irtcengine_startrhythmplayer) - [`ConfigRhythmPlayer`](/zh-CN/api-reference/rtc/unity/play/rhythmplayer#api_irtcengine_configrhythmplayer) - [`OnRhythmPlayerStateChanged`](/zh-CN/api-reference/rtc/unity/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) #### 水印接口废弃 [#水印接口废弃-5] 该版本废弃水印功能的相关接口，推荐使用该版本新增的水印接口。 - [`AddVideoWatermark`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2)[2/3] - [`AddVideoWatermarkEx`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex)[1/2] #### 冗余接口删除 [#冗余接口删除-5] 该版本删除了下列冗余接口及参数： - `SetLocalPublishFallbackOption` - `OnLocalPublishFallbackToAudioOnly` - `OnDownlinkNetworkInfoUpdated` - `OnWlAccStats` - `EnableWirelessAccelerate` #### 美妆功能实现变更 [#美妆功能实现变更-5] 受该版本美颜重构的影响，自 v4.6.2 起，不再支持调用 [`SetExtensionProperty`](/zh-CN/api-reference/rtc/unity/extension#api_irtcengine_setextensionproperty) 启用美妆功能，改用 `STYLE_MAKEUP` 节点实现。 #### 双流模式行为变更 [#双流模式行为变更-2] - v4.6.2 之前：发送端开启小流自适应模式 (AUTO_SIMULCAST_STREAM) 时，不会主动发送小流，仅当主播身份的接收端调用 [`SetRemoteVideoStreamType`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setremotevideostreamtype) 发起小流申请后，发送端收到申请才会开始发送小流。 - v4.6.2 及之后版本：发送端开启小流自适应模式 (AUTO_SIMULCAST_STREAM) 时，会根据订阅端用户的下行网络质量，自动决定发送或停止发送小流。若将 **mode** 设置为其他发送模式或显式配置了小流的宽、高、码率或帧率，则此自适应功能失效。 #### 新增域名白名单 [#新增域名白名单-5] 如果你由之前的版本升级到 v4.6.2 且使用了域名白名单功能（`RtcEngineConfig` 下的 `domainLimit` 为 `true`），请在白名单中添加以下域名，以确保互通顺畅： - `*.rtnsvc.com` - `*.realtimemesh.com` #### EncodedVideoFrameInfo 结构体删除参数 uid [#encodedvideoframeinfo-结构体删除参数-uid-3] 该版本删除了 [`EncodedVideoFrameInfo`](/zh-CN/api-reference/rtc/unity/class-encodedvideoframeinfo) 结构体中的 `uid` 参数。你可以直接从 [`OnEncodedVideoFrameReceived`](/zh-CN/api-reference/rtc/unity/video/video-encoded#callback_ivideoencodedframeobserver_onencodedvideoframereceived) 回调中获取 `uid` 信息。如果你之前集成过相关代码，请相应更新集成逻辑。 ### 新增特性 [#新增特性-105] #### 多路分辨率视频流 [#多路分辨率视频流-5] 该版本新增多路分辨率视频流（Adaptive Bitrate Video Streaming，简称 ABR）功能，支持对同一视频源设置同时发送多路不同分辨率的视频流，并支持多频道场景。接收端通过自动/手动订阅目标分辨率的视频流。 启用 ABR 后，你可以配置不同分辨率的视频流，（最多四层分辨率，一个最高分辨率的主流和三层其他较低分辨率的视频流），并设置视频流的分辨率、码率、是否启用分层推流回退等选项来灵活控制流的发布。启用分层推流回退后，SDK 会在弱网环境下自动回退到低分辨率的视频流，确保流畅的观看体验。订阅端可根据实际需求选择想要接收的视频流。适用于会议场景、大班课、互动直播等多终端、多网络环境，可显著提升弱网下的观看体验。 #### 多路径网络传输 [#多路径网络传输-5] 该版本新增多路径传输功能，适用于终端支持多网卡传输(比如 5G， Wi-Fi，LAN)的设备，可以有效降低甚至消除弱网带来的体验回退，适用于弱网环境、对传输稳定性要求高的实时音视频通信场景，如车载、IoT、火车、高速公路等复杂网络环境。通过在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中设置 `enableMultipath` 为 `true`，可开启多路径传输能力。支持两种传输模式（[`MultipathMode`](/zh-CN/api-reference/rtc/unity/enum-multipathmode)）： - 动态模式：（默认）根据网络状况动态选择最佳路径进行传输，适用于流量敏感、对体验要求比较高的场景，如会议、教育等。动态模式下，你可以通过 `preferMultipathType` 指定首选的网络传输路径（如优先 Wi-Fi 或移动网络）。 - 全冗余模式：数据会在所有可用网络路径上同时传输，适用于流量不敏感，对体验有极致要求的场景，如户外采播、平行操控等。该模式会产生额外费用，如需使用请[联系技术支持](https://ticket.shengwang.cn/)。 上下行还可分别通过 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中的 `uplinkMultipathMode`、`downlinkMultipathMode` 配置。启用后，SDK 会通过回调 `onMultipathStats` 实时上报各路径的传输统计信息，包括每一个传输路径的流量消耗，便于开发者监控和优化网络表现。 #### 视频质量评分 [#视频质量评分-5] 该版本在 [`RemoteVideoStats`](/zh-CN/api-reference/rtc/unity/class-remotevideostats) 中新增 `mosValue` 成员，报告声网实时视频 MOS（平均主观意见分）评估系统对接收到的远端视频流的质量评分。评分共有 5 个档次，5 分表示视频画质优秀，画面清晰无噪点，1 分表示视频画质极差，画面严重模糊。你可以通过该参数实时观测远端视频流的主观画质表现，便于动态调整视频参数、优化用户体验，或用于质量监控和告警等场景。如需启用该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 支持添加多个水印 [#支持添加多个水印-5] 该版本废弃了 [`AddVideoWatermark`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2)[2/3] 和 [`AddVideoWatermarkEx`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex)[1/2] 方法，新增 `AddVideoWatermarkWithConfig` [3/3] 和 `AddVideoWatermarkWithConfigEx` [2/2] 方法，支持通过水印 ID 来给视频添加多个水印，并可对水印进行排序。如果你需要移除指定水印，可调用 [`RemoveVideoWatermark`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/watermark#api_irtcengine_removevideowatermark) 方法。 #### Token 更新结果回调 [#token-更新结果回调-5] 该版本新增 `onRenewTokenResult` 回调及 [`RENEW_TOKEN_ERROR_CODE`](/zh-CN/api-reference/rtc/unity/enum-renewtokenerrorcode) 错误码。当调用 `renewToken` 方法更新 Token 后，SDK 会通过 `onRenewTokenResult` 回调通知 Token 更新的结果，并通过 [`RENEW_TOKEN_ERROR_CODE`](/zh-CN/api-reference/rtc/unity/enum-renewtokenerrorcode) 返回详细的错误码，开发者可在回调中根据错误码及时处理 Token 更新失败的场景。 #### Android 新增支持共享单个 App [#android-新增支持共享单个-app-1] 从 Android 14 开始，系统支持用户在屏幕共享时选择共享整个屏幕或共享单个 App，以提升隐私保护和多任务处理能力。 该版本适配了该系统能力，在支持共享整个屏幕的基础上，新增支持共享单个 App。同时，为便于管理相关事件，新增 [`OnLocalVideoEvent`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onlocalvideoevent) 回调，用于报告本地视频，尤其是屏幕共享相关的事件。 #### Android 新增权限被授予回调 [#android-新增权限被授予回调-1] 为便于确认屏幕共享场景下的权限授权情况，该版本新增 [`OnPermissionGranted`](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onpermissiongranted) 回调。你可以通过该回调判断当前用户授予的是相机（Camera）权限还是屏幕（Screen）权限。 #### Media Player 支持获取音频缓冲延迟 [#media-player-支持获取音频缓冲延迟-5] 为解决 K 歌场景中可能会出现的主唱与伴唱伴奏不同步的问题，该版本在 Media Player 模块中新增 [`GetAudioBufferDelay`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-info#api_imediaplayer_getaudiobufferdelay) 方法，用于获取播放媒体文件时毫秒级的音频缓冲延迟。 #### 其他 [#其他-25] - 新增 `SetPlaybackAudioFrameBeforeMixingParameters` 方法用于设置 [`OnPlaybackAudioFrameBeforeMixing`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#callback_iaudioframeobserver_onplaybackaudioframebeforemixing) 回调中返回的音频帧格式，包括采样率、声道数以及每次回调的数据采样点数。调用此方法后，SDK 会按照设定的参数返回混音前的原始音频数据，便于开发者进行自定义处理或分析。 - 新增 [`PreloadEffectEx`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengineex_preloadeffectex) 方法，用于将指定音效文件预加载到指定频道，支持本地或在线音效文件，便于后续快速播放，适合多频道场景。 - 新增 [`PlayEffectEx`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengineex_playeffectex) 方法，用于在指定频道播放音效文件，支持设置循环次数、音调、空间位置、音量、是否发布到频道及播放起始位置等参数，满足丰富的音效播放需求。 - 本地截图上传功能支持通过 [`ContentInspectModule`](/zh-CN/api-reference/rtc/unity/class-contentinspectmodule) 中新增的 `position` 成员设置截图的视频观测位置，从而实现对原始视频数据或效果处理前后的视频流进行截图并上传。 - 为了提升用户使用绿幕或蓝幕开启虚拟背景功能时，人像分割的准确性和稳定性，该版本在 [`SegmentationProperty`](/zh-CN/api-reference/rtc/unity/class-segmentationproperty) 中新增 `screenColorType` 属性，支持指定背景幕布的颜色为绿色、蓝色或自动识别。 ### 改进 [#改进-123] #### 美颜重构 [#美颜重构-5] 该版本对美颜功能进行了彻底重构和升级，不仅拓展了美颜功能，提升了美颜效果和性能，还解决了美颜参数配置复杂、集成成本高、美颜资源依赖网络易失效等痛点。主要改进包括： - **新增美颜功能**：新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。 - **API 大幅简化**：将过去版本中的基础美颜、美型、美妆、滤镜功能整合为 `BEAUTY`、`STYLE_MAKEUP`、`FILTER` 三个核心节点 (node)，通过 [`IVideoEffectObject`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ivideoeffectobject) 统一管理生命周期和参数设置，减少频繁 API 调用带来的性能负担。 - **预设模板开箱即用**：提供多套预设风格模板（如"自然美颜"、"学姐妆"、"冷白滤镜"），大幅简化集成流程，无需手动调试数十项参数。 - **美颜参数动态控制**：该版本新增实时获取美颜参数的能力，开发者可通过 key-value 方式动态读取或修改任意细粒度参数（如磨皮强度、口红类型）。同时支持：调用预设模板快速启用风格效果、保存主播自定义参数配置、随时重置参数至默认状态，极大提升了业务层状态同步的灵活性和开发效率。 - **美颜资源外置**：该版本通过美颜资源外置化设计，将所有美颜资源（特效、滤镜、妆容）均打包为本地 bundle 文件，彻底消除因网络下载失败导致美颜失效的风险。 #### playEffect 支持无缝切换 [#playeffect-支持无缝切换-5] 该版本新增支持音效文件的无缝切换。对于同一个音效文件，如果先调用 [`PreloadEffectEx`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengineex_preloadeffectex) 再调用 [`PlayEffectEx`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengineex_playeffectex)，在播放完成或通过 [`StopEffect`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengine_stopeffect) 停止播放后，SDK 不会关闭该音效文件。当再次调用 [`PlayEffectEx`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengineex_playeffectex) 时，SDK 会直接复用已加载的文件进行播放，从而实现循环播放和无缝切换。该能力同样适用于多频道场景。 #### 屏蔽窗口支持第二屏幕 [#屏蔽窗口支持第二屏幕-2] 在 4.6.2 之前的版本中，通过屏幕 ID（`startScreenCaptureByDisplayId`）进行屏幕共享时，不支持在多屏场景下配置屏蔽窗口（[`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/unity/class-screencaptureparameters) 中的 `excludeWindowList`）。为提升屏幕共享体验，该版本新增支持该配置。 同时，为便于识别屏幕共享过程中屏蔽窗口的状态，该版本在 [`LOCAL_VIDEO_STREAM_REASON`](/zh-CN/api-reference/rtc/unity/enum-localvideostreamreason) 中新增枚举值 `LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_EXCLUDE_WINDOW_FAILED (34)`，用于报告屏幕共享屏蔽窗口失败的情况。 #### onVideoDeviceStateChanged 回调时机优化 [#onvideodevicestatechanged-回调时机优化-2] 该版本优化了 [`OnVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/unity/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) 回调的触发时机。在此前版本中，该回调仅在加入频道后才能触发。从 4.6.2 起，在 [`IRtcEngine`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 完成初始化后即可收到一次该回调，加入频道后仍可继续监听该事件。 #### onNetworkQuality 准确性提升 [#onnetworkquality-准确性提升-3] 该版本提升了 [`OnNetworkQuality`](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onnetworkquality) 回调中网络质量评估的准确性，使回调数据更贴近用户的主观体验。 #### onPlaybackAudioFrame 支持 24k 采样率的音频帧 [#onplaybackaudioframe-支持-24k-采样率的音频帧-4] 该版本在 [`OnPlaybackAudioFrame`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#callback_iaudioframeobserverbase_onplaybackaudioframe) 中新增支持采样率为 **24000 Hz** 的音频数据。在调用 [`SetPlaybackAudioFrameParameters`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#api_irtcengine_setplaybackaudioframeparameters) 设置播放音频数据格式时，可以将 `sampleRate` 设为 `24000`。 #### onEncodedVideoFrameReceived 回调支持获取频道 ID [#onencodedvideoframereceived-回调支持获取频道-id-4] 该版本在 [`OnEncodedVideoFrameReceived`](/zh-CN/api-reference/rtc/unity/video/video-encoded#callback_ivideoencodedframeobserver_onencodedvideoframereceived) 回调中新增 `channelId` 参数，方便你在获取编码后视频数据时识别其所属频道。 #### 其他改进 [#其他改进-48] - 优化了在 Windows 11 24H2 及后续版本上的权限请求，避免非必要地获取位置信息。 - 在与 Web 端互通时，新增对 g711 和 g722 音频编解码器的支持，进一步提升了跨平台音频播放的兼容性和清晰度。 - 优化了屏幕共享文档场景下的共享视频清晰度。 - 该版本新增错误码 `ERR_PCMSEND_FORMAT (200)` 和 `ERR_PCMSEND_BUFFEROVERFLOW (201)`，用于报告 PCM 数据发送相关错误。 ### 问题修复 [#问题修复-123] 该合并版本修复了以下问题： - 开启导唱功能播放多音轨歌曲时，调用 [`SetAudioPitch`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setaudiopitch) 方法调整歌曲音调后出现杂音。 - 主播端调用 [`CreateCustomAudioTrack`](/zh-CN/api-reference/rtc/unity/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 创建自定义音频采集轨道并将 `trackType` 设为 `AUDIO_TRACK_DIRECT`，调用 [`PushAudioFrame`](/zh-CN/api-reference/rtc/unity/audio/audio-custom-capturenrendering#api_imediaengine_pushaudioframe) 将自采集音频推送到频道内，然后调用 [`PlayEffectEx`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengineex_playeffectex) 播放音效，频道内的观众听主播的音频有杂音。 - 集成了 SDK 的 App 在音视频互动过程中偶现主线程阻塞导致的 UI 卡顿。 - 开启屏幕共享功能并将 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/unity/class-screencaptureparameters) 的 `enableHighLight` 设为 `true` 对共享窗口进行描边，将共享窗口置于最上层并最大化后，本地预览的共享画面出现闪烁。 - 调用 [`StartScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 共享指定屏幕的视频流，通过 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/unity/class-screencaptureparameters) 的 `excludeWindowList` 来指定屏蔽的窗口，偶现部分窗口屏蔽失败。 - 应用程序共享外接屏幕的视频流，断开外接屏幕连接后偶现应用程序崩溃。 - 调用 [`OpenWithMediaSource`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 并通过 `source` 参数将 `isLiveSource` 设为 `true` 并播放纯视频流，播放失败。 - 发送端传输多声道编码音频时，接收端偶现杂音。 - App 集成媒体播放器场景下，先后两次调用 `Open` 打开不同媒体资源，第二次打开时，媒体播放器信息变化回调 [`OnPlayerInfoUpdated`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerinfoupdated) 返回第一次媒体资源的信息，不符合预期。 - 调用 [`EnableAudioVolumeIndication`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 启用用户音量提示本地发流用户和远端用户音量相关信息，用户音量提示回调 [`OnAudioVolumeIndication`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 返回的本地用户音量为 0。 - 使用 21:9 的显示屏（带鱼屏）进行音视频互通和屏幕共享场景下，设置高分辨率，如 3840*2160，屏幕共享画面在本地预览和接收端显示被裁剪。 - App 调用 [`EnableVideoImageSource`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 启用垫片推流功能，偶现发送端推流成功但是 [`OnVideoPublishStateChanged`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 返回当前的发布状态不是 PUB_STATE_PUBLISHED，不符合预期。 - 多频道场景下，App 在调用 `joinChannelEx` 成功前调用 `setupRemoteVideoEx` 初始化远端用户视图，偶现远端用户视图首帧图像显示延时大。 - 调用 `Open` 打开在线音效文件后，调用 [`PlayEffectEx`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengineex_playeffectex) 开始播放，当调用 [`Seek`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定播放位置后，音效文件会从头开始播放。 - 在媒体音量模式下，主播在频道中发布麦克风采集的音频流，同时调用 [`PlayEffectEx`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengineex_playeffectex) 播放音效文件、调用 [`StartAudioMixing`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_startaudiomixing2)[2/2] 播放音乐文件，偶现回声。 - 调用 [`JoinChannelEx`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 加入频道，然后调用 [`StartOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 开始跨频道媒体流转发，下麦、退出频道后重新加入频道开始连麦，偶现 [`OnChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) 回调报告 `state` 为 `RELAY_STATE_FAILURE`，`code` 为 `RELAY_ERROR_SERVER_ERROR_RESPONSE`。 - 部分机型的笔记本电脑开启节能模式下，发送端共享屏幕和音频，偶现接收端听到回声。 - 在线教育场景下，偶现教师端本地看多个学生端音画不同步。 - 第二次调用 [`EnumerateVideoDevices`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_ivideodevicemanager_enumeratevideodevices) 接口获取设备列表不生效。 - Windows 7 设备上共享 PPT 窗口，当 PPT 以全屏自动播放模式运行且包含大量动画时，远端看到的画面有概率出现闪烁。 ## v4.5.1 [#v451-4] 该版本于 2025 年 3 月 13 日发布。 ### 新增特性 [#新增特性-106] #### AI 对话场景 [#ai-对话场景-5] 该版本新增了专为与[声网对话式 AI 引擎](/zh-CN/ai)创建的智能体互动设计的 `AUDIO_SCENARIO_AI_CLIENT` 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。 ### 改进 [#改进-124] 优化了特定机型上 SDK 初始化的耗时。(iOS) ### 问题修复 [#问题修复-124] 该版本修复了以下问题： - 集成 SDK 的 App 设置 `targetSdkVersion` 为 34，在 Android 14 系统上首次开启屏幕共享进行授权时出现崩溃。(Android) - 同时加入两个及以上的频道，连续调用 [`TakeSnapshotEx`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex)[1/2] 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。 - 使用媒体播放器时，调用 [`Pause`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`Seek`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 定位到指定播放位置、然后调用 [`Play`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。 - 使用媒体播放器时，调用 [`SwitchSrc`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换媒体资源后，调用 [`GetPlaySrc`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-info#api_imediaplayer_getplaysrc_imediaplayer) 获取当前正在播放的媒体资源的路径没有变化。 - 用户在特定机型上进行音视频互动并使用蓝牙耳机，偶现调整手机音量后改变的是媒体音量而非蓝牙音量。(Android) - 音视频互动时，偶现接收端观看发送端画面出现黑屏。(Android) - 在特定机型上，调用 [`SetCameraExposureFactor`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_setcameraexposurefactor) 在设备的某个特定角度设置当前摄像头的曝光系数后，当设备移动到另一个角度时，偶现视频画面变暗。(Android) - 播放 CDN 直播流时，直播流短暂中断后恢复，偶现播放画面长时间卡住。(Android) - 在推送 i420 格式的视频帧到频道内时，使用 CVPixelBuffer 会导致崩溃。(iOS) - 调用 [`SetupLocalVideo`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_setuplocalvideo) 设置两个视图（view），然后调用 [`EnableFaceDetection`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/face-detection#api_irtcengine_enablefacedetection) 开启人脸检测，后传入的视图中无法检测到人脸信息。(iOS) - 屏幕共享场景下，接收端用户看到的共享图像出现绿线。(iOS) - 在极速直播场景下，观众通过 `string` 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。 - 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。 ## v4.5.0 [#v450-6] 该版本于 2024 年 12 月 10 日发布。 ### 升级必看 [#升级必看-70] 该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 成员参数类型变更 [#成员参数类型变更-1] 该版本对一些 API 中的成员或参数做了如下修改： | API | 成员/参数 | 变更 | | --- | --- | --- | | [`StartScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapturebywindowid) | **windowId** | 由 view_t 型变更为 long 型 | | [`ScreenCaptureConfiguration`](/zh-CN/api-reference/rtc/unity/class-screencaptureconfiguration) | [release-notes-unity-html-0-2-1 details](#table-slot-release-notes-unity-html-0-2-1) | 由 unit 型变更为 long 型 | | [`ScreenCaptureSourceInfo`](/zh-CN/api-reference/rtc/unity/class-screencapturesourceinfo) | [release-notes-unity-html-0-3-1 details](#table-slot-release-notes-unity-html-0-3-1) | 由 view_t 型变更为 long 型 | **release-notes-unity-html-0-2-1 details** - **displayId** - **windowId** **release-notes-unity-html-0-3-1 details** - **sourceDisplayId** - **sourceId** #### 强效视频降噪实现变更 [#强效视频降噪实现变更-5] 该版本调整了强效视频降噪的实现方式，在 [`VIDEO_DENOISER_LEVEL`](/zh-CN/api-reference/rtc/unity/enum-videodenoiserlevel) 中删除了 `VIDEO_DENOISER_LEVEL_STRENGTH`，改为调用 [`SetVideoDenoiserOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 启用视频降噪后，调用 [`SetBeautyEffectOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 [`SetVideoDenoiserOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)。 此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 [`SetLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)。 #### 摄像头插拔状态变更 (macOS, Windows) [#摄像头插拔状态变更-macos-windows-1] 在之前版本中，当摄像头拔出并重新插入时，[`OnVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/unity/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) 回调会将设备状态报告为 `MEDIA_DEVICE_STATE_ACTIVE`(1)（设备正在使用）。该版本起，摄像头重新插入后，设备状态将改为 `MEDIA_DEVICE_STATE_IDLE`(0)（设备就绪）。 #### 视频编码偏好变更 [#视频编码偏好变更-5] 为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好： - 在 [`COMPRESSION_PREFERENCE`](/zh-CN/api-reference/rtc/unity/enum-compressionpreference) 枚举类中新增 `PREFER_COMPRESSION_AUTO` (-1) 枚举，并替代原有的 `PREFER_QUALITY` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `PREFER_LOW_LATENCY` 或 `PREFER_QUALITY`，以获得最佳的用户体验。 - 在 [`DEGRADATION_PREFERENCE`](/zh-CN/api-reference/rtc/unity/enum-degradationpreference) 枚举类中新增 `MAINTAIN_AUTO` (-1) 枚举，并替代原有的 `MAINTAIN_QUALITY` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `MAINTAIN_FRAMERATE`、`MAINTAIN_BALANCED` 或 `MAINTAIN_RESOLUTION`，以获得最优的综合质量体验 (QoE)。 #### 16 KB 内存页大小（Android） [#16-kb-内存页大小android] 自 Android 15 起，系统新增了对 16 KB 内存页大小的支持，详见 [Support 16 KB page sizes](https://developer.android.com/guide/practices/page-sizes?hl=zh-cn) 。为了保证 App 的稳定性和性能表现，自该版本起，SDK 支持 16 KB 内存页大小，确保可以在使用 4 KB 和 16 KB 内存页大小的设备上无缝运行，提升兼容性并避免崩溃。 ### 新增特性 [#新增特性-107] #### 高级美颜 [#高级美颜-5] 该版本新增以下两种高级美颜功能： - 美型：调用 [`SetFaceShapeBeautyOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 [`SetFaceShapeAreaOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapeareaoptions) 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。 - 美妆：调用 [`SetExtensionProperty`](/zh-CN/api-reference/rtc/unity/extension#api_irtcengine_setextensionproperty) 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。 :::info[信息] 目前，高级美颜功能为**限时免费**，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 秀场直播场景 [#秀场直播场景-5] 该版本在 [`VIDEO_APPLICATION_SCENARIO_TYPE`](/zh-CN/api-reference/rtc/unity/enum-videoapplicationscenariotype) 类下新增枚举 `APPLICATION_SCENARIO_LIVESHOW`(3)（秀场直播），你可以调用 [`SetVideoScenario`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为[秀场直播](/zh-CN/solutions/showroom)。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，重点提升了首帧出图体验和画质表现，同时增强了在弱网环境和低端设备上的画质和流畅度表现。 #### 限制视频渲染帧率 [#限制视频渲染帧率-5] 该版本新增 [`SetLocalRenderTargetFps`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_setlocalrendertargetfps) 和 [`SetRemoteRenderTargetFps`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_setremoterendertargetfps) 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。 在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。 #### 滤镜效果 [#滤镜效果-5] 该版本新增 [`SetFilterEffectOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setfiltereffectoptions) 方法，你可以在 `config` 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 `built_in_whiten_filter.cube` 文件，用于快速实现美白滤镜效果。 #### 本地音频合流 [#本地音频合流-5] 该版本新增本地音频合流功能，你可以调用 [`StartLocalAudioMixer`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/audiomixer#api_irtcengine_startlocalaudiomixer) 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 [`StopLocalAudioMixer`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/audiomixer#api_irtcengine_stoplocalaudiomixer) 方法停止本地音频合流；在合流过程中，可以调用 [`UpdateLocalAudioMixerConfiguration`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/audiomixer#api_irtcengine_updatelocalaudiomixerconfiguration) 方法更新正在合流的音频流配置。 该功能的使用场景示例如下： - 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。 - 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。 - 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。 #### 外部 MediaProjection (Android) [#外部-mediaprojection-android] 该版本新增 [`SetExternalMediaProjection`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_setexternalmediaprojection) 方法，该方法支持你自行设置外部 `MediaProjection`，并取代 SDK 申请的 `MediaProjection`。 如果你具备自行申请 `MediaProjection` 的开发能力，可通过该功能实现更加灵活的屏幕采集。 #### EGL 环境上下文 (Android) [#egl-环境上下文-android] 该版本新增了 [`SetExternalRemoteEglContext`](/zh-CN/api-reference/rtc/unity/video/video-custom-capturenrendering#api_irtcengine_setexternalremoteeglcontext) 方法，用于设置远端视频流渲染的 EGL 环境上下文。使用 Texture 格式的视频数据进行远端视频自渲染时，你可以通过该方法替换 SDK 默认的远端 EGL 环境上下文，实现统一的 EGL 上下文管理。 #### 色彩空间设置 [#色彩空间设置-5] 该版本在 [`VideoFrame`](/zh-CN/api-reference/rtc/unity/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/unity/class-externalvideoframe) 中新增了 **colorSpace**，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。 #### 其他 [#其他-26] - [`OnLocalVideoStateChanged`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调新增 `LOCAL_VIDEO_STREAM_REASON_DEVICE_DISCONNECTED` 枚举，表示当前正在使用的视频采集设备已经断开连接（例如，被拔出）。(Windows) - [`MEDIA_DEVICE_STATE_TYPE`](/zh-CN/api-reference/rtc/unity/enum-mediadevicestatetype) 新增 `MEDIA_DEVICE_STATE_PLUGGED_IN` 枚举，表示设备已插入。 ### 改进 [#改进-125] #### 虚拟背景算法优化 [#虚拟背景算法优化-10] 该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。 #### 录制本地预览视频 [#录制本地预览视频-5] 该版本在 [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/unity/class-recorderstreaminfo) 中新增 **type** 成员。当调用 [`CreateMediaRecorder`](/zh-CN/api-reference/rtc/unity/recording#api_irtcengine_createmediarecorder) 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 [`MediaRecorderConfiguration`](/zh-CN/api-reference/rtc/unity/class-mediarecorderconfiguration) 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 [`StartRecording`](/zh-CN/api-reference/rtc/unity/recording#api_imediarecorder_startrecording) 即可开始录制本地预览的视频。 #### 指定视频观测位置截图 [#指定视频观测位置截图-5] 该版本新增 [`TakeSnapshot`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/snapshot#api_irtcengine_takesnapshot2)[2/2] 和 [`TakeSnapshotEx`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex2)[2/2] 方法，你可以在调用该方法时通过 `config` 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。 #### 自定义音频采集改进 [#自定义音频采集改进-5] 该版本在 [`AudioTrackConfig`](/zh-CN/api-reference/rtc/unity/class-audiotrackconfig) 中新增了 `enableAudioProcessing` 成员参数，用于控制是否对 `AUDIO_TRACK_DIRECT` 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 `false`，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。 #### 其他改进 [#其他改进-49] - 通过拼接视频帧和 Alpha 数据实现 Alpha 透明特效的应用场景下，提升了接收端的渲染性能，有效减少卡顿和延迟。（Android, iOS） - 优化了调用 [`QueryDeviceScore`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_querydevicescore) 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。 - 支持使用 YV 12 格式的虚拟摄像头作为视频采集设备。(Windows) - 调用 [`SwitchSrc`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 [`OnPlayerEvent`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent) 回调报告 `PLAYER_EVENT_SWITCH_ERROR` 事件，表示媒体资源切换时发生错误。 - 调用 [`SetPlaybackSpeed`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，最低支持 0.3 倍速播放。 ### 问题修复 [#问题修复-125] 该版本修复了以下问题： - 调用 [`StartScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享屏幕时，通过 **regionRect** 指定的窗口采集区域不准确，导致接收端看到的屏幕共享窗口宽高错误。（Windows） - 当发送端视频源类型为 JPEG 格式时，偶现接收端帧率低于预期。(Android、iOS) - 在播放音乐内容中心的音乐资源时，偶现杂音和卡顿。(Android) - 在 App 没有获取麦克风权限时，通过 [`IMusicPlayer`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imusicplayer) 播放伴奏音乐偶现卡顿。(Android) - 音视频互动过程中被系统来电打断后，通过 [`OnAudioVolumeIndication`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 回调上报的用户音量错误。(Android) - 在接收端默认订阅视频小流、加入频道时不自动订阅任何视频流的前提下，加入频道后调用 [`MuteRemoteVideoStream`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_muteremotevideostream)`(uid,false)` 恢复接收视频流，但接收到的视频流为视频大流，不符合预期。(Android) - Windows 7 系统下进行音视频互动，偶现找不到系统文件的报错。(Windows) - 调用 [`FollowSystemRecordingDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_followsystemrecordingdevice) 或 [`FollowSystemPlaybackDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_followsystemplaybackdevice) 设置 SDK 使用的音频采集或播放设备不跟随系统默认的音频播放设备，当音频设备被移除时，本地音频状态回调 [`OnLocalAudioStateChanged`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) 没有被触发，不符合预期。(Windows) - 音视频互动过程中，偶现接收端听发送端没有声音。(iOS) - 音视频互动过程中，如果发送端设备的系统版本为 iOS 17，偶现接收端听不到来自发送端的声音。(iOS) - 直播场景下，观众端因切换网络导致断开连接，重新连接直播间花费的时间长于预期。(iOS) - App 启动后使用媒体播放器播放在线媒体资源，播放无声。(iOS) - 音视频互动过程中被系统其他 App 打断后恢复，偶现音频采集无声。(iOS) - 调用 [`StartAudioMixing`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_startaudiomixing)[1/2] 后，立即调用 [`PauseAudioMixing`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_pauseaudiomixing) 暂停播放音乐文件不生效。 - 音视频互动过程中偶现崩溃。(Android) ## v4.4.0 [#v440-7] 该版本于 2024 年 8 月 29 日发布。 ### 升级必看 [#升级必看-71] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 1. 为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的 [`ExtensionContext`](/zh-CN/api-reference/rtc/unity/class-extensioncontext) 了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。 | 原有回调 | 现有回调 | | --- | --- | | `OnExtensionEvent` | [`OnExtensionEventWithContext`](/zh-CN/api-reference/rtc/unity/extension#callback_irtcengineeventhandler_onextensioneventwithcontext) | | `OnExtensionStarted` | [`OnExtensionStartedWithContext`](/zh-CN/api-reference/rtc/unity/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) | | `OnExtensionStopped` | [`OnExtensionStoppedWithContext`](/zh-CN/api-reference/rtc/unity/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext) | | `OnExtensionError` | [`OnExtensionErrorWithContext`](/zh-CN/api-reference/rtc/unity/extension#callback_irtcengineeventhandler_onextensionerrorwithcontext) | 2. 该版本修改了 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/unity/class-externalvideoframe) 中的以下成员名称： - `d3d11_texture_2d` 更名为 `d3d11Texture2d`。 - `texture_slice_index` 更名为 `textureSliceIndex`。 - `metadata_buffer` 更名为 `metadataBuffer`。 - `metadata_size` 更名为 `metadataSize`。 ### 新增特性 [#新增特性-108] #### Alpha 透明特效 [#alpha-透明特效-4] 该版本新增 Alpha 透明特效功能，支持在 SDK 采集和自定义采集视频的场景下，在发送端发布视频帧的 Alpha 通道、在接收端对 Alpha 通道进行渲染处理，实现透明礼物特效、接收端自定义主播背景等： - [`VideoFrame`](/zh-CN/api-reference/rtc/unity/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/unity/class-externalvideoframe) 中新增 `alphaBuffer`：设置 Alpha 通道数据。 - [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/unity/class-externalvideoframe) 中新增 `fillAlphaBuffer`：对于 BGRA 或 RGBA 格式的视频数据，设置是否自动提取 Alpha 通道数据并填入到 `alphaBuffer` 中。 - [`VideoFrame`](/zh-CN/api-reference/rtc/unity/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/unity/class-externalvideoframe) 中新增 `alphaStitchMode`：设置 `alphaBuffer` 和视频帧拼接的相对位置。 另外，[`AdvanceOptions`](/zh-CN/api-reference/rtc/unity/class-advanceoptions) 中新增成员 `encodeAlpha`，用于设置是否将 Alpha 信息编码并发送到远端。SDK 默认不对 Alpha 信息进行编码发送；如果需要对 Alpha 信息编码发送至远端（例如开启了虚拟背景功能），请显式调用 [`SetVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 设置视频编码属性，并将 `encodeAlpha` 设置为 `true`。 #### AI 调音器 [#ai-调音器-5] 该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 [`EnableVoiceAITuner`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/audio-effect#api_irtcengine_enablevoiceaituner) 方法并传入 [`VOICE_AI_TUNER_TYPE`](/zh-CN/api-reference/rtc/unity/enum-voiceaitunertype) 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。 #### 版权音乐优化 (Android, iOS) [#版权音乐优化-android-ios] - 该版本新增 [`SetPlayMode`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusicplayer_setplaymode)方法，用于设置音乐资源的播放模式。在在线 K 歌房等场景下，你可以根据需求启用伴唱、原唱或导唱模式。 - 该版本新增 [`DestroyMusicPlayer`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_destroymusicplayer) 方法，用于销毁音乐播放器并释放相应的资源。 #### 1v1 视频通话场景 [#1v1-视频通话场景-5] 该版本在 [`VIDEO_APPLICATION_SCENARIO_TYPE`](/zh-CN/api-reference/rtc/unity/enum-videoapplicationscenariotype) 类下新增枚举 `APPLICATION_SCENARIO_1V1`（1v1 视频通话）。你可以调用 [`SetVideoScenario`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。 ### 改进 [#改进-126] #### 自适应硬解支持 (Android, Windows) [#自适应硬解支持-android-windows] 该版本新增自适应硬解支持，改进了低端机的渲染流畅性，有效降低系统负载。 #### 渲染能力提升 (Windows) [#渲染能力提升-windows-1] Windows 设备上默认启用 DirectX 11 渲染器，可提供高性能、高质量的图形渲染能力。 #### 人脸区域美颜 [#人脸区域美颜-5] 为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。 #### 其他改进 [#其他改进-50] 该版本还进行了如下改进： - 优化了传输策略，调用 [`EnableInstantMediaRendering`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_enableinstantmediarendering) 不再对传输链路的安全性产生影响。 - [`OnLocalVideoStateChanged`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增 `LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_DISPLAY_DISCONNECTED` 枚举，表示进行屏幕采集的显示器已断开连接。(Windows, macOS) - 优化了共享窗口的视频链路，降低了 CPU 占用率。(macOS) - 优化了屏幕共享场景下的回声消除。 - 该版本在 [`Metadata`](/zh-CN/api-reference/rtc/unity/class-metadata) 中新增 `channelId` 参数，用于获取发送 Metadata 的源频道名称。 - 废弃了 [`CLIENT_ROLE_CHANGE_FAILED_REASON`](/zh-CN/api-reference/rtc/unity/enum-clientrolechangefailedreason) 中的冗余枚举值 `CLIENT_ROLE_CHANGE_FAILED_REQUEST_TIME_OUT`、`CLIENT_ROLE_CHANGE_FAILED_CONNECTION_FAILED`。 ### 问题修复 [#问题修复-126] 该版本修复了以下问题： - 在实时互动过程中，当多个远端同时加入频道时 App 偶现崩溃。(iOS) - App 切后台一段时间、然后返回前台时，远端视频画面偶现卡住或花屏。(iOS) - 发送端调用 `StartDirectCdnStreaming` 开始直接向 CDN 推流后，频繁开关或切换网络，偶现接收端黑屏但发送端未收到推流失败回调。(iOS) - 调用 [`PushAudioFrame`](/zh-CN/api-reference/rtc/unity/audio/audio-custom-capturenrendering#api_imediaengine_pushaudioframe) 推送外部音频数据，外部音频渲染的采样率如果不是 SDK 推荐的值时，比如 22050 Hz 和 11025 Hz，声音播放失败。 ## v4.3.2 [#v432-5] 该版本于 2024 年 6 月 6 日发布。 ### 升级必看 [#升级必看-72] 该版本修改了播放版权音乐的行为，当调用 [`IMusicPlayer`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imusicplayer) 中的 [`Play`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 方法播放版权音乐媒体文件时，存在以下行为变更 (Android, iOS)： - v4.3.2 以前版本：SDK 默认播放当前音频文件的第一个音轨。 - v4.3.2：SDK 默认播放伴奏。 ### 改进 [#改进-127] 提升了 [`SetRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_setremotesubscribefallbackoption) 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 [`SetRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_setremotesubscribefallbackoption) 动态切换弱网环境下的音视频流回退选项。 ### 问题修复 [#问题修复-127] 该版本修复了以下问题： - App 长时间切后台再返回前台时，远端视频画面卡住或花屏。(iOS) - 部分 iPad 设备上的本地预览画面旋转 90°，不符合预期。(iOS) - 音视频互动过程中偶现视频流畅度不佳。 - 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。 - 首次安装 App 或重启系统后，打开 App 并开启屏幕共享时出现崩溃。(Android) - 接听系统电话时加入频道，挂断电话后，本地音频采集失败，远端用户听不到声音。(Android) - 在部分机型（例如：红米 Note8）上进行互动的过程中接听系统来电并挂断后，本地播放媒体文件无声、听远端无声。(Android) - 远端用户离开频道时偶现崩溃。 - 调用 [`StartScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享 PPT 窗口，当 PPT 播放动画画面时，接收端偶现画面闪烁。(Windows) - 在 Windows 7 系统上调用 [`StartScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享 WPS PPT 窗口，并设置 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/unity/class-screencaptureparameters) 的 `enableHighLight` 为 `true` 开启窗口描边，放映该 PPT 后退出放映，之后选择最大化 PPT 窗口，窗口描边没有保留原始窗口大小，不符合预期。(Windows) - 调用 [`StartScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享窗口，并设置 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/unity/class-screencaptureparameters) 的 `windowFocus` 和 `enableHighLight` 为 `true` 以前置指定窗口并开启窗口描边，如果当前该窗口被其他窗口覆盖，无法前置该窗口，不符合预期。(Windows) - 在 Windows 7 设备上共享窗口并对窗口描边时，点击桌面控件导致描边部分闪烁。(Windows) - 调用 [`StartAudioMixing`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_startaudiomixing)[1/2] 播放音乐文件，音乐文件播放结束后偶现无法触发 [`OnAudioMixingStateChanged`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)(AUDIO_MIXING_STATE_STOPPED,AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED) 回调报告音乐文件播放完毕。(iOS) - 调用 [`PlayEffect`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengine_playeffect3) 播放时长不足 1 秒的音效文件并设置不循环播放（ `loopCount` 为 0 ）时，出现无声。(iOS) - 使用媒体播放器播放视频，暂停播放后恢复播放，偶现短暂无声。(iOS) ## v4.3.1 [#v431-5] 该版本于 2024 年 5 月 9 日发布。 ### 新增特性 [#新增特性-109] #### 隐私清单文件 (iOS) [#隐私清单文件-ios] 为满足 Apple 对于 App 发布的安全合规要求，SDK 自该版本起新增隐私清单文件 `PrivacyInfo.xcprivacy`，其中包含 SDK 中需要访问或使用用户数据的 API 调用说明和 SDK 采集的数据类型说明。 **注：** 如果你需要将集成 v4.3.1 之前的 SDK 版本的 App 发布到苹果应用商店，则需要在 Xcode 工程中手动添加 `PrivacyInfo.xcprivacy` 文件。详见[如何在 App 中增加隐私清单？](/zh-CN/reference/faq/other/ios_privacy_manifest) #### 人像锁定 (iOS, macOS) [#人像锁定-ios-macos] 为提升在线会议、秀场、在线教育等场景中的主播演讲效果，该版本新增 [`EnableCameraCenterStage`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) 方法开启人像锁定功能。该功能可确保主播无论移动与否，始终位于画面中心，以取得良好的演讲效果。 在开启人像锁定前，建议你先调用 [`IsCameraCenterStageSupported`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) 查询当前设备性能是否支持该功能。支持的设备清单可参考 [`API 文档`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage)。 #### 摄像头防抖 (iOS) [#摄像头防抖-ios] 为改善在移动拍摄、暗光环境拍摄、手持拍摄等场景下的视频画面稳定性，该版本新增摄像头防抖功能。你可以调用 [`SetCameraStabilizationMode`](/zh-CN/api-reference/rtc/unity/video/camera-capture#api_irtcengine_setcamerastabilizationmode) 开启该功能并设置适合的防抖模式，以获得更加稳定、清晰的视频画面。 #### 摄像头广角和超广角 (Android, iOS) [#摄像头广角和超广角-android-ios] 为了让用户捕捉到更宽阔的视野和更完整的画面内容，该版本新增了对广角和超广角摄像头的支持。你可以先调用 [`QueryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 查询设备支持的焦距能力，然后调用 [`SetCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 并将 `cameraFocalLengthType` 设置为支持的焦距类型，包括广角、超广角等。 #### 摄像头多路采集 (Android) [#摄像头多路采集-android] 该版本针对 Android 摄像头采集新增以下功能： 1. 支持第三个和第四个摄像头视频流的采集和发布。 - [`VIDEO_SOURCE_TYPE`](/zh-CN/api-reference/rtc/unity/enum-videosourcetype) 中的 `VIDEO_SOURCE_CAMERA_THIRD`(11) 和 `VIDEO_SOURCE_CAMERA_FOURTH`(12) 枚举新增对 Android 的支持，分别用于指定视频源为第三个和第四个摄像头。此项改动允许你在调用 [`StartCameraCapture`](/zh-CN/api-reference/rtc/unity/video/camera-capture#api_irtcengine_startcameracapture) 开启摄像头采集时，指定最多 4 路摄像头采集的视频流。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中的 `publishThirdCameraTrack` 和 `publishFourthCameraTrack` 成员新增对 Android 的支持。调用 [`JoinChannel`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2)[2/2] 加入频道时，将这两个成员参数设置为 `true` 即可在频道内发布第三个和第四个摄像头采集的视频流。 2. 支持通过摄像头 ID 指定摄像头。 在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/unity/class-cameracapturerconfiguration) 中新增 `cameraId` 成员。对于多摄像头的设备，`cameraDirection` 无法识别或访问全部可用摄像头。这种情况下，你通过系统 API 获取摄像头 ID，再调用 [`StartCameraCapture`](/zh-CN/api-reference/rtc/unity/video/camera-capture#api_irtcengine_startcameracapture) 并传入 `cameraId` 指定摄像头。 #### 数据流加密 [#数据流加密-6] 该版本在 [`EncryptionConfig`](/zh-CN/api-reference/rtc/unity/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` 成员用于启用数据流加密。你可以在调用 [`EnableEncryption`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_enableencryption) 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` 和 `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` 枚举得知。 #### 视频小流自适应配置 [#视频小流自适应配置-5] 该版本新增视频小流的自适应配置功能，当你调用 [`SetDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2] 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示： - 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。 - 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。 #### 其他 [#其他-27] - 新增 [`EnableEncryptionEx`](/zh-CN/api-reference/rtc/unity/network#api_irtcengineex_enableencryptionex) 方法，用于多频道场景下开启媒体流或数据流加密。 - 新增 [`SetAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) 方法，用于设置音乐文件的播放速度。 - 新增 [`GetCallIdEx`](/zh-CN/api-reference/rtc/unity/network#api_irtcengineex_getcallidex) 方法，用于多频道场景下获取通话 ID。 ### 改进 [#改进-128] #### 屏幕共享游戏场景优化 (Windows) [#屏幕共享游戏场景优化-windows-1] 该版本对屏幕共享的游戏场景进行了专项优化，在超高清（4K, 60 fps）游戏场景下提升了性能表现，增强了窗口采集的稳定性，为游戏玩家带来更清晰、流畅、稳定的游戏体验。 #### 获取音频设备类型 (macOS) [#获取音频设备类型-macos-1] 该版本新增 [`GetPlaybackDefaultDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getplaybackdefaultdevice2)[2/2]、[`GetRecordingDefaultDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getrecordingdefaultdevice2)[2/2]、[`GetPlaybackDeviceInfo`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getplaybackdeviceinfo2)[2/2]、[`GetRecordingDeviceInfo`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getrecordingdeviceinfo2)[2/2] 方法，分别用于获取音频播放、采集设备的设备信息及类型。 #### 虚拟背景算法优化 [#虚拟背景算法优化-11] 为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法： - 支持识别任意纯色背景，不再局限于绿幕。 - 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。 - 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。 #### 降低耳返的 CPU 消耗 [#降低耳返的-cpu-消耗-5] 该版本在 [`EAR_MONITORING_FILTER_TYPE`](/zh-CN/api-reference/rtc/unity/enum-earmonitoringfiltertype) 中新增 `EAR_MONITORING_FILTER_REUSE_POST_PROCESSING_FILTER`(`1 << 15`) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。 #### 其他改进 [#其他改进-51] 该版本还进行了如下改进： - 优化了非屏幕共享场景的视频编解码策略，节省系统性能开销。(iOS, macOS, Windows) - 提升了本地合图功能的性能和稳定性，并降低了该功能对 CPU 的占用率。(Android) - 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。 - 在 [`AUDIO_EFFECT_PRESET`](/zh-CN/api-reference/rtc/unity/enum-audioeffectpreset) 中新增 `ROOM_ACOUSTICS_CHORUS`（合唱音效），可使人声在合唱场景下更具空间立体感。 - 在 [`RemoteAudioStats`](/zh-CN/api-reference/rtc/unity/class-remoteaudiostats) 中新增 `e2eDelay`，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。 ### 问题修复 [#问题修复-128] 该版本修复了以下问题： - 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。 - 屏幕共享场景中，App 调用 [`EnableLoopbackRecording`](/zh-CN/api-reference/rtc/unity/audio/audio-capture#api_irtcengine_enableloopbackrecording) 开启声卡采集功能采集共享屏幕的音频，本地用户手动禁用本地音频采集设备后，声卡采集的音频发送失败，远端用户听不见共享屏幕的声音。(Windows) - 主播使用部分型号设备在扬声器下进行音视频互动，之后切换 App 进程到后台再切回前台，偶现本地音频采集失败，远端用户听不到主播的声音。(Android) - 播放指定用户混音前的音频流时偶现回声。(macOS、Windows) - 在音视频互动过程中，本地用户调用 设置系统默认播放设备为扬声器后，听远端无声。(Windows) - 在 Android 8.0 系统的设备上，启用屏幕共享功能时 App 偶现崩溃。(Android) - 在共享 Excel 文档窗口时，偶现远端用户看到的画面出现绿屏。(Windows) - 使用摄像头采集本地视频场景下，在 App 切后台时已调用 [`DisableVideo`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_disablevideo) 或 [`StopPreview`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_stoppreview)[1/2] 关闭视频采集，但将 App 再切回前台时，摄像头采集被打开，不符合预期。(Android) ### API 变更 [#api-变更-67] #### 新增 [#新增-61] - [`EnableCameraCenterStage`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) (iOS, macOS) - [`IsCameraCenterStageSupported`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) (iOS, macOS) - [`SetCameraStabilizationMode`](/zh-CN/api-reference/rtc/unity/video/camera-capture#api_irtcengine_setcamerastabilizationmode) (iOS) - [`CAMERA_STABILIZATION_MODE`](/zh-CN/api-reference/rtc/unity/enum-camerastabilizationmode) (iOS) - [`EncryptionConfig`](/zh-CN/api-reference/rtc/unity/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` - [`ENCRYPTION_ERROR_TYPE`](/zh-CN/api-reference/rtc/unity/enum-encryptionerrortype) 中新增如下枚举： - `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` - `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` - [`GetPlaybackDefaultDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getplaybackdefaultdevice2)[2/2] (macOS) - [`GetRecordingDefaultDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getrecordingdefaultdevice2)[2/2] (macOS) - [`GetPlaybackDeviceInfo`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getplaybackdeviceinfo2)[2/2] (macOS) - [`GetRecordingDeviceInfo`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getrecordingdeviceinfo2)[2/2] (macOS) - [`RemoteAudioStats`](/zh-CN/api-reference/rtc/unity/class-remoteaudiostats) 新增 `e2eDelay` - [`ERROR_CODE_TYPE`](/zh-CN/api-reference/rtc/unity/enum-errorcodetype) 新增 `ERR_DATASTREAM_DECRYPTION_FAILED` - [`AUDIO_EFFECT_PRESET`](/zh-CN/api-reference/rtc/unity/enum-audioeffectpreset) 新增 `ROOM_ACOUSTICS_CHORUS` - [`GetCallIdEx`](/zh-CN/api-reference/rtc/unity/network#api_irtcengineex_getcallidex) - [`EnableEncryptionEx`](/zh-CN/api-reference/rtc/unity/network#api_irtcengineex_enableencryptionex) - [`SetAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) - [`QueryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) (Android, iOS) - [`FocalLengthInfo`](/zh-CN/api-reference/rtc/unity/class-focallengthinfo) (Android, iOS) - [`CAMERA_FOCAL_LENGTH_TYPE`](/zh-CN/api-reference/rtc/unity/enum-camerafocallengthtype) (Android, iOS) - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/unity/class-cameracapturerconfiguration) 新增成员 `cameraFocalLengthType` (Android, iOS) - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/unity/class-cameracapturerconfiguration) 新增成员 `cameraId` (Android) - [`EAR_MONITORING_FILTER_TYPE`](/zh-CN/api-reference/rtc/unity/enum-earmonitoringfiltertype) 新增枚举 `EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS`(`1 << 15`) ## v4.3.0 [#v430-6] 该版本于 2024 年 2 月 28 日发布。 ### 升级必看 [#升级必看-73] 该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 回调中的参数改名 [#回调中的参数改名-5] 为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。 | 回调 | 原有参数名 | 现有参数名 | | --- | --- | --- | | [`OnLocalAudioStateChanged`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) | `error` | `reason` | | [`OnLocalAudioStateChanged`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) | `error` | `reason` | | `OnDirectCdnStreamingStateChanged` | `error` | `reason` | | [`OnMusicChartsResult`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) | `errorCode` | `reason` | | [`OnPreLoadEvent`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) | [release-notes-slot-32-6-1 details](#table-slot-release-notes-slot-32-6-1) | [release-notes-slot-32-6-2 details](#table-slot-release-notes-slot-32-6-2) | | [`OnMusicCollectionResult`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) | `errorCode` | `reason` | | [`OnLyricResult`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) | `errorCode` | `reason` | | [`OnSongSimpleInfoResult`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) | `errorCode` | `reason` | | [`OnRtmpStreamingStateChanged`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/media-push#callback_irtcengineeventhandler_onrtmpstreamingstatechanged) | `errCode` | `reason` | **release-notes-slot-32-6-1 details** - `status` - `errorCode` **release-notes-slot-32-6-2 details** - `state` - `reason` | 原有枚举类 | 现有枚举类 | | --- | --- | | `LOCAL_AUDIO_STREAM_ERROR` | [`LOCAL_AUDIO_STREAM_REASON`](/zh-CN/api-reference/rtc/unity/enum-localaudiostreamreason) | | `LOCAL_VIDEO_STREAM_ERROR` | [`LOCAL_VIDEO_STREAM_REASON`](/zh-CN/api-reference/rtc/unity/enum-localvideostreamreason) | | `DIRECT_CDN_STREAMING_ERROR` | `DIRECT_CDN_STREAMING_REASON` | | `MEDIA_PLAYER_ERROR` | [`MEDIA_PLAYER_REASON`](/zh-CN/api-reference/rtc/unity/enum-mediaplayerreason) | | `RTMP_STREAM_PUBLISH_ERROR` | [`RTMP_STREAM_PUBLISH_REASON`](/zh-CN/api-reference/rtc/unity/enum-rtmpstreampublishreason) | | `MusicContentCenterStatusCode` | [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/unity/enum-musiccontentcenterstatereason) | **注：** 有关具体枚举的改名详见 [API 变更](#apichange)。 #### 跨频道媒体流转发 [#跨频道媒体流转发-10] 为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项： | 已删除的方法和回调 | 替代的方法和回调 | | --- | --- | | [release-notes-slot-34-2-0 details](#table-slot-release-notes-slot-34-2-0) | [`StartOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) | | [release-notes-slot-34-3-0 details](#table-slot-release-notes-slot-34-3-0) | [`StartOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) | | `OnChannelMediaRelayEvent` | [`OnChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) | **release-notes-slot-34-2-0 details** - `StartChannelMediaRelay` - `UpdateChannelMediaRelay` **release-notes-slot-34-3-0 details** - `StartChannelMediaRelayEx` - `UpdateChannelMediaRelayEx` #### 音频路由 [#音频路由-2] 该版本起，[`AudioRoute`](/zh-CN/api-reference/rtc/unity/enum-audioroute) 中的 `ROUTE_BLUETOOTH` 更名为 `ROUTE_BLUETOOTH_DEVICE_HFP`，表示音频路由为使用 HFP 协议的蓝牙设备，新增 `ROUTE_BLUETOOTH_DEVICE_A2DP`(10) 表示音频路由为使用 A2DP 协议的蓝牙设备。 #### 本地视频状态改变原因 [#本地视频状态改变原因-5] 该版本对 [`LOCAL_VIDEO_STREAM_REASON`](/zh-CN/api-reference/rtc/unity/enum-localvideostreamreason) 枚举类中的枚举进行了如下修改： - `LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_PAUSED` （原 `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_PAUSED`）的值从 23 变更为 28。 - `LOCAL_VIDEO_STREAM_REASON_SCREEN_CAPTURE_RESUMED` （原 `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_RESUMED`）的值从 24 变更为 29。 - `LOCAL_VIDEO_STREAM_ERROR_CODEC_NOT_SUPPORT` 的枚举名变更为 `LOCAL_VIDEO_STREAM_REASON_CODEC_NOT_SUPPORT`。 #### 声卡采集 [#声卡采集-3] - 在 v4.3.0 之前，当你调用 [`DisableAudio`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#api_irtcengine_disableaudio) 关闭整个音频模块后，声卡采集功能不会被关闭。 - 从 v4.3.0 起，当你调用 [`DisableAudio`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#api_irtcengine_disableaudio) 关闭音频模块后，声卡采集功能也会被关闭，如果你需要再次启用声卡采集功能，需要在调用 [`EnableAudio`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#api_irtcengine_enableaudio) 启用音频模块后再次调用 [`EnableLoopbackRecording`](/zh-CN/api-reference/rtc/unity/audio/audio-capture#api_irtcengine_enableloopbackrecording)。 #### 日志加密行为变更 [#日志加密行为变更-5] 出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案： - 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。 - 如有其他特殊需求，请[联系技术支持](https://ticket.shengwang.cn/)并附上对应的加密日志。 ### 新增特性 [#新增特性-110] #### 接收端自定义合图布局 (Android, iOS) [#接收端自定义合图布局-android-ios] 为支持接收端自定义多路合图流的布局，该版本新增了 [`OnTranscodedStreamLayoutInfo`](/zh-CN/api-reference/rtc/unity/video/video-rendering#callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo) 回调。当接收端收到合图服务器发送的频道内合图视频流时，该回调会被触发，上报合图视频流的布局信息、以及合图流中每一路子视频流的布局信息。接收端可以在调用 [`SetupRemoteVideo`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_setupremotevideo) 方法时，为合图视频流中的子视频流（通过 `subviewUid` 区分）设置单独的 `view` 进行渲染，从而达到自定义视频布局的效果。 当合图视频流中的子视频流布局发生变化时，该回调也会被触发，实时上报最新的布局信息。 通过该特性，接收端可以灵活调整本地的视图布局。当在多人视频场景下应用时，接收端只需接收并解码一路合图视频流，可以有效降低接收端解码多路视频时的 CPU 占用率和网络带宽。 **注：** 关于该特性在多主播场景下的最佳实践，详见[多主播场景下的视频体验优化](/zh-CN/realtime-media/rtc/build/video/custom-layout)。 #### 多视图本地预览 [#多视图本地预览-5] 该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下： 1. 调用 [`SetupLocalVideo`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第一个视图：在 [`VideoCanvas`](/zh-CN/api-reference/rtc/unity/class-videocanvas) 中设置 `position` 参数为 `POSITION_POST_CAPTURER_ORIGIN`（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。 2. 调用 [`SetupLocalVideo`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第二个视图：在 [`VideoCanvas`](/zh-CN/api-reference/rtc/unity/class-videocanvas) 中设置 `position` 参数为 `POSITION_POST_CAPTURER`，此处观测到的视频具备视频前处理的效果。 3. 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。 #### 查询设备评分等级 [#查询设备评分等级-5] 该版本新增 [`QueryDeviceScore`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_querydevicescore) 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请[联系技术支持](https://ticket.shengwang.cn/)。 #### 本地播放及发布至远端的音轨控制 [#本地播放及发布至远端的音轨控制-5] 该版本新增 [`SelectMultiAudioTrack`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 [`OpenWithMediaSource`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并通过 [`MediaSource`](/zh-CN/api-reference/rtc/unity/class-mediasource) 中新增的 `enableMultiAudioTrack` 成员来开启音轨控制。 #### 其他 [#其他-28] 该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。 - [`SetRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_setremotesubscribefallbackoption)：设置弱网环境下订阅的音视频流回退选项。 - [`OnRemoteSubscribeFallbackToAudioOnly`](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly)：订阅流已回退为音频流或恢复为音视频流回调。 - [`SetPlaybackDeviceVolume`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_setplaybackdevicevolume)：设置播放设备音量。 - [`GetRecordingDeviceVolume`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getrecordingdevicevolume)：获取音频采集设备音量。 - [`SetPlayerOption`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption)[1/2] 和 `SetPlayerOption`[2/2]：设置媒体播放器选项，用于提供技术预览或特别定制功能。 - [`EnableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/unity/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback)：设置是否在本地播放外部音频源。 ### 改进 [#改进-129] #### SDK 任务处理调度优化 [#sdk-任务处理调度优化-5] 该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面： - 远端及本地的首帧出图与出声速度提升了 10% 到 20%。 - API 的调用耗时和响应耗时缩短了 5% 到 50%。 - SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。 - SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。 #### 耳返音量提升 [#耳返音量提升-5] 该版本为用户提供更灵活的耳返音频调整选项，支持调用 [`SetInEarMonitoringVolume`](/zh-CN/api-reference/rtc/unity/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) 将耳返音量设置为原始音量的 4 倍。 #### 空间音频易用性提升 [#空间音频易用性提升-5] - 该版本优化了 [`SetZones`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 方法的设计，支持将 `zones` 参数设置为 `NULL`，表示清除所有隔声区域。 - 自该版本起，在调用 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) 中的方法之前，无需先取消订阅频道内所有远端用户的音频流。 #### 其他改进 [#其他改进-52] 该版本还进行了如下改进： - 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。 - [`OnLocalVideoStateChanged`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增 `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_AUTO_FALLBACK` 枚举，表示屏幕共享过程中发生意外错误（可能由于窗口阻塞失败），导致性能下降，但屏幕共享过程本身没有受到影响。(Windows) - 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用 [`SetLocalAccessPoint`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_setlocalaccesspoint) 解析域名时的稳定性。 - 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。 - [`LocalAudioStats`](/zh-CN/api-reference/rtc/unity/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。 - 新增 [`OnPlayerCacheStats`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) 回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。 - 新增 [`OnPlayerPlaybackStats`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) 回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过 [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/unity/class-playerplaybackstats) 来获取当前音、视频的码率等信息。 - [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/unity/enum-musiccontentcenterstatereason) 中新增状态码 `kMusicContentCenterReasonHttpInternalError` 表示 HTTP 内部发生错误，请稍后重试。(Android, iOS) ### 问题修复 [#问题修复-129] 该版本修复了以下问题： - 当同时共享两路屏幕共享视频流时，[`OnLocalVideoStats`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onlocalvideostats) 回调上报的 `captureFrameRate` 为 0，不符合预期。 ### API 变更 [#api-变更-68] #### 新增 [#新增-62] - [`OnTranscodedStreamLayoutInfo`](/zh-CN/api-reference/rtc/unity/video/video-rendering#callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo) (Android, iOS) - [`VideoLayout`](/zh-CN/api-reference/rtc/unity/class-videolayout) (Android, iOS) - [`VideoCanvas`](/zh-CN/api-reference/rtc/unity/class-videocanvas) 新增 `subviewUid` 和 `uid` 成员 - [`EnableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/unity/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback) - [`QueryDeviceScore`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_querydevicescore) - [`MEDIA_SOURCE_TYPE`](/zh-CN/api-reference/rtc/unity/enum-mediasourcetype) 中新增 `CUSTOM_VIDEO_SOURCE` 枚举 - [`AudioRoute`](/zh-CN/api-reference/rtc/unity/enum-audioroute) 中新增 `ROUTE_BLUETOOTH_DEVICE_A2DP` 枚举 - [`LocalAudioStats`](/zh-CN/api-reference/rtc/unity/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员 - [`SelectMultiAudioTrack`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) - [`OnPlayerCacheStats`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) - [`OnPlayerPlaybackStats`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) - [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/unity/class-playerplaybackstats) - [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/unity/enum-musiccontentcenterstatereason) 中新增 `kMusicContentCenterReasonHttpInternalError` (Android, iOS) #### 修改 [#修改-16] - `ROUTE_BLUETOOTH` 枚举名变更为 `ROUTE_BLUETOOTH_DEVICE_HFP` - 以下枚举名中的 `ERROR` 字段全部修改为 `REASON`： - `LOCAL_AUDIO_STREAM_ERROR_OK` - `LOCAL_AUDIO_STREAM_ERROR_FAILURE` - `LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION` - `LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY` - `LOCAL_AUDIO_STREAM_ERROR_RECORD_FAILURE` - `LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE` - `LOCAL_AUDIO_STREAM_ERROR_RECORD_INVALID_ID` (Windows) - `LOCAL_AUDIO_STREAM_ERROR_PLAYOUT_INVALID_ID` (Windows) - `LOCAL_VIDEO_STREAM_ERROR_OK` - `LOCAL_VIDEO_STREAM_ERROR_FAILURE` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY` - `LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE` - `LOCAL_VIDEO_STREAM_ERROR_CODEC_NOT_SUPPORT` - `LOCAL_VIDEO_STREAM_ERROR_CAPTURE_INBACKGROUND` (iOS) - `LOCAL_VIDEO_STREAM_ERROR_CAPTURE_MULTIPLE_FOREGROUND_APPS` (iOS) - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_DISCONNECTED` - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_INVALID_ID` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_CLOSED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_OCCLUDED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_NO_PERMISSION` (Windows) - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_PAUSED` (Windows) - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_RESUMED` (Windows) - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_HIDDEN` (Windows) - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_HIDDEN` (Windows) - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_MINIMIZED` (Windows) - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_FAILURE` (Windows) - `LOCAL_VIDEO_STREAM_ERROR_DEVICE_SYSTEM_PRESSURE` (Windows) - `DIRECT_CDN_STREAMING_ERROR_OK` - `DIRECT_CDN_STREAMING_ERROR_FAILED` - `DIRECT_CDN_STREAMING_ERROR_AUDIO_PUBLICATION` - `DIRECT_CDN_STREAMING_ERROR_VIDEO_PUBLICATION` - `DIRECT_CDN_STREAMING_ERROR_NET_CONNECT` - `DIRECT_CDN_STREAMING_ERROR_BAD_NAME` - `PLAYER_ERROR_NONE` - `PLAYER_ERROR_INVALID_ARGUMENTS` - `PLAYER_ERROR_INTERNAL` - `PLAYER_ERROR_NO_RESOURCE` - `PLAYER_ERROR_INVALID_MEDIA_SOURCE` - `PLAYER_ERROR_UNKNOWN_STREAM_TYPE` - `PLAYER_ERROR_OBJ_NOT_INITIALIZED` - `PLAYER_ERROR_CODEC_NOT_SUPPORTED` - `PLAYER_ERROR_VIDEO_RENDER_FAILED` - `PLAYER_ERROR_INVALID_STATE` - `PLAYER_ERROR_URL_NOT_FOUND` - `PLAYER_ERROR_INVALID_CONNECTION_STATE` - `PLAYER_ERROR_SRC_BUFFER_UNDERFLOW` - `PLAYER_ERROR_INTERRUPTED` - `PLAYER_ERROR_NOT_SUPPORTED` - `PLAYER_ERROR_TOKEN_EXPIRED` - `PLAYER_ERROR_UNKNOWN` - `RTMP_STREAM_PUBLISH_ERROR_OK` - `RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT` - `RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED` - `RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT` - `RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR` - `RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR` - `RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN` - `RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT` - `RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED` - `RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND` - `RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED` - `RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER` - `RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM` - `RTMP_STREAM_PUBLISH_ERROR_NET_DOWN` - `RTMP_STREAM_PUBLISH_ERROR_INVALID_PRIVILEGE` - `RTMP_STREAM_UNPUBLISH_ERROR_OK` - `MusicContentCenterStatusCode` 修改为 [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/unity/enum-musiccontentcenterstatereason)，其枚举名中的 `StatusErr` 字段全部修改为 `Reason`：(Android, iOS) - `kMusicContentCenterStatusErrGateway` - `kMusicContentCenterStatusErrPermissionAndResource` - `kMusicContentCenterStatusErrInternalDataParse` - `kMusicContentCenterStatusErrMusicLoading` - `kMusicContentCenterStatusErrMusicDecryption` - `kMusicContentCenterStatusErrHttpInternalError` - `kMusicContentCenterStatusErr` 修改为 `kMusicContentCenterReasonError` #### 删除 [#删除-25] - `StartChannelMediaRelay` - `UpdateChannelMediaRelay` - `StartChannelMediaRelayEx` - `UpdateChannelMediaRelayEx` - `OnChannelMediaRelayEvent` - `CHANNEL_MEDIA_RELAY_EVENT` ## v4.2.6 [#v426-5] 该版本于 2023 年 11 月 21 日发布。 ### 问题修复 [#问题修复-130] 该版本修复了在使用 Android 14 系统版本时可能出现的问题： - 在屏幕共享过程中切换横竖屏模式导致当前屏幕共享进程中断，需要在弹出窗口中点击确认录制屏幕才可重新开始屏幕共享。(Android) - 在集成 SDK 时，如果将 Android `targetSdkVersion` 设置为 34，导致屏幕共享不可用甚至 App 崩溃。(Android) - 先调用 [`StartScreenCapture`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapture)[1/2] 但不共享视频（设置 `captureVideo` 为 `false`）、后调用 [`UpdateScreenCaptureParameters`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_updatescreencaptureparameters) 共享视频（设置 `captureVideo` 为 `true`）时，接收端看到的屏幕共享画面冻结。(Android) - 采用横屏模式进行屏幕共享时，观众端看到的共享画面被拆分成两部分：一侧的画面被压缩；另一侧为黑屏。(Android) 该版本还修复了以下问题： - 使用 iOS 16 版本或以上设备在加入频道前连接了蓝牙耳机，在加入频道后的音频路由不符合预期：音频从扬声器播放、而非蓝牙耳机。(iOS) - 在直播场景下，观众端看到的画面偶现变形。(Android) - 在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。 ## v4.2.4 [#v424-1] 该版本于 2023 年 10 月 24 日发布。 ### 问题修复 [#问题修复-131] 该版本修复了如下问题： `AgoraRtcWrapper` 中的 `CFBundleShortVersionString` 版本号错误，导致 App 无法被提交至 App Store。(iOS, macOS) ## v4.2.3 [#v423-5] 该版本于 2023 年 10 月 13 日发布。 ### 升级必看 [#升级必看-74] #### 兼容性变更（Android） [#兼容性变更android] 该版本优化了 SDK 采集和自定义视频采集场景下 Texture Buffer 的管理方式，有效消除丢帧和崩溃隐患。自该版本起，TextureBuffer 类型的纹理格式不再包括 OES 格式，仅为 RGB 格式。你需要在处理视频数据时增加对 I420、RGB 纹理格式的适配。 ### 新增特性 [#新增特性-111] #### 本地截图上传更新 [#本地截图上传更新-5] 为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动： - [`CONTENT_INSPECT_TYPE`](/zh-CN/api-reference/rtc/unity/enum-contentinspecttype) 中新增 `CONTENT_INSPECT_IMAGE_MODERATION` 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。 - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/unity/class-contentinspectconfig) 中新增的 `serverConfig` 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请[联系技术支持](https://ticket.shengwang.cn/)。 此外，该版本还新增了 [`EnableContentInspectEx`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) 方法，支持同时对多条视频流截图并上传。 #### 支持 ID3D11Texture2D 渲染 (Windows) [#支持-id3d11texture2d-渲染-windows] 自该版本起，SDK 支持 ID3D11Texture2D 类型的视频格式，提升了游戏场景中视频帧的渲染效果。你可以在调用 [`PushVideoFrame`](/zh-CN/api-reference/rtc/unity/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe) 方法将外部原始视频帧推送到 SDK 时，设置 `format` 为 `VIDEO_TEXTURE_ID3D11TEXTURE2D`；并通过设置 `d3d11_texture_2d` 和 `texture_slice_index` 属性，来确定要使用的 ID3D11Texture2D 纹理对象。 #### 本地视频状态错误码更新 (Windows, macOS) [#本地视频状态错误码更新-windows-macos] 为了帮助用户在屏幕共享场景下了解本地视频出错的准确原因，[`OnLocalVideoStateChanged`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增了如下几组枚举： - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_PAUSED`(23)：屏幕采集已暂停。当前屏幕可能已切换到安全桌面，例如 UAC 对话框或者 Winlogon 桌面。 - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_RESUMED`(24)：屏幕采集已从暂停状态中恢复。 - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_HIDDEN`(25)：当前屏幕采集的窗口处于隐藏状态，并且在当前屏幕上不可见。 - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_HIDDEN`(26)：进行屏幕采集的窗口已经从隐藏状态中恢复。 - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_MINIMIZED`(27)：进行屏幕采集的窗口已经从最小化状态中恢复。 #### 进阶功能查询 [#进阶功能查询-5] 该版本新增了 [`IsFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_isfeatureavailableondevice) 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。 在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。 此外，自该版本起，调用 [`EnableVirtualBackground`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 和 [`SetBeautyEffectOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 `-4: ERR_NOT_SUPPORTED` 表示该设备不支持开启该功能。 ### 改进 [#改进-130] #### 优化虚拟背景内存占用 [#优化虚拟背景内存占用-5] 该版本升级了虚拟背景算法，降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。 #### 屏幕共享场景优化 [#屏幕共享场景优化-3] 该版本优化了在超高清（4K，60 fps）游戏共享场景下的性能和编码效率，有效降低了屏幕共享时系统资源占用率。 #### 其他改进 [#其他改进-53] 该版本还进行了如下改进： - 当调用 [`SetPlaybackSpeed`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，传入非法参数后会返回错误码 `-2`，表示方法中设置了无效的参数，需要重新设置参数。 - 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。 ### 问题修复 [#问题修复-132] 该版本修复了以下问题： - 在屏幕共享场景下偶现崩溃、掉帧。(Windows) - 加入频道偶现的崩溃。(macOS) - 本地系统时间不正确时，偶现加入频道失败。 - 调用 [`PlayEffect`](/zh-CN/api-reference/rtc/unity/play/audio-effect-file#api_irtcengine_playeffect3) 使用相同的 `soundId` 播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 - 主播调用 [`StartAudioMixing`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_startaudiomixing2)[2/2] 播放音乐文件时，偶现主播本地无法听见音乐，远端用户可以正常听见。(Android) - 合唱场景下，调用 [`Preload`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_preload)[1/2] 加载音乐，偶现加载失败。(Android, iOS) - 在特定机型上开启 AI 降噪偶现崩溃。(Android) - 当本地系统时间不准确时，歌曲榜单加载失败。(Android, iOS) - 调用一次 `TakeSnapshotEx` 获取视频截图会收到多次 [`OnSnapshotTaken`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 视频截图结果回调。 - 在仅调用 [`JoinChannelEx`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 加入的频道中，调用 [`SetEnableSpeakerphone`](/zh-CN/api-reference/rtc/unity/device-management/audio-route#api_irtcengine_setenablespeakerphone) 无法将音频路由从扬声器切换至听筒。(Android) ### API 变更 [#api-变更-69] #### 新增 [#新增-63] - [`OnLocalVideoStateChanged`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 中新增如下枚举：(Windows, macOS) - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_PAUSED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_RESUMED` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_HIDDEN` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_HIDDEN` - `LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_RECOVER_FROM_MINIMIZED` - [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/unity/class-externalvideoframe) 中新增 `d3d11_texture_2d` 和 `texture_slice_index` 成员 (Windows) - [`VIDEO_PIXEL_FORMAT`](/zh-CN/api-reference/rtc/unity/enum-videopixelformat) 中新增 `VIDEO_TEXTURE_ID3D11TEXTURE2D` 枚举 (Windows) - [`EnableContentInspectEx`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) - [`CONTENT_INSPECT_TYPE`](/zh-CN/api-reference/rtc/unity/enum-contentinspecttype) 新增 `CONTENT_INSPECT_IMAGE_MODERATION` - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/unity/class-contentinspectconfig) 中新增 `serverConfig` 可选参数 - [`IsFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_isfeatureavailableondevice) - [`FeatureType`](/zh-CN/api-reference/rtc/unity/enum-featuretype) ## v4.2.2 [#v422-5] 该版本于 2023 年 8 月 1 日发布。 ### 升级必看 [#升级必看-75] 该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。 #### 音频观测器 [#音频观测器] [`IAudioFrameObserver`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_iaudioframeobserver) 类中删除了下列方法： - `GetObservedAudioFramePosition`：请改用 [`RegisterAudioFrameObserver`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#api_imediaengine_registeraudioframeobserver) 中新增的 `position` 参数。 - `GetPlaybackAudioParams`：请改用 [`SetPlaybackAudioFrameParameters`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#api_irtcengine_setplaybackaudioframeparameters)。 - `GetRecordAudioParams`：请改用 [`SetRecordingAudioFrameParameters`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#api_irtcengine_setrecordingaudioframeparameters) - `GetMixedAudioParams`：请改用 [`SetMixedAudioFrameParameters`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#api_irtcengine_setmixedaudioframeparameters)。 - `GetEarMonitoringAudioParams`：请改用 [`SetEarMonitoringAudioFrameParameters`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#api_irtcengine_setearmonitoringaudioframeparameters)。 #### 视频观测器 [#视频观测器-5] [`IVideoFrameObserver`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ivideoframeobserver) 类中删除了下列方法： - `GetVideoFormatPreference`：请改用 [`RegisterVideoFrameObserver`](/zh-CN/api-reference/rtc/unity/video/video-raw#api_imediaengine_registervideoframeobserver) 新增的 `formatPreference` 参数。 - `GetObservedFramePosition`：请改用 [`RegisterVideoFrameObserver`](/zh-CN/api-reference/rtc/unity/video/video-raw#api_imediaengine_registervideoframeobserver) 新增的 `position` 参数。 #### 媒体附属信息 [#媒体附属信息] 该版本删除了 [`IMetadataObserver`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imetadataobserver) 类下的 `GetMaxMetadataSize` 和 [`OnReadyToSendMetadata`](/zh-CN/api-reference/rtc/unity/metadata/metadata-observer#callback_imetadataobserver_onreadytosendmetadata) ，请改用该版本新增的 [`SetMaxMetadataSize`](/zh-CN/api-reference/rtc/unity/metadata/metadata-observer#api_irtcengine_setmaxmetadatasize) 和 [`SendMetadata`](/zh-CN/api-reference/rtc/unity/metadata/metadata-observer#api_irtcengine_sendmetadata)。 #### 版权音乐 (Android, iOS) [#版权音乐-android-ios] 该版本废弃了 [`IMusicContentCenter`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imusiccontentcenter) 类下的 [`Preload`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_preload)[1/2] 方法并新增 [`Preload`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_preload2)[2/2] 方法。 ### 新增特性 [#新增特性-112] #### 通配 Token [#通配-token-5] 该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 :::info[信息] 声网 4.x RTC SDK 均支持使用通配 Token。 ::: #### 预加载频道 [#预加载频道-6] 该版本新增 [`PreloadChannel`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_preloadchannel) 和 [`PreloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_preloadchannelwithuseraccount) 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频提升观众端的音频体验。 在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 #### 自定义视频画布背景颜色 [#自定义视频画布背景颜色-5] 该版本在 [`VideoCanvas`](/zh-CN/api-reference/rtc/unity/class-videocanvas) 中增加了 `backgroundColor` 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。 #### 发布多源采集的视频流 (Windows, macOS) [#发布多源采集的视频流-windows-macos] 该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中新增下列成员，支持你发布第三个、第四个摄像头和屏幕采集到的视频流： - `publishThirdCameraTrack`：发布第三个摄像头采集的视频。 - `publishFourthCameraTrack`：发布第四个摄像头采集的视频。 - `publishThirdScreenTrack`：发布第三个屏幕采集的视频。 - `publishFourthScreenTrack`：发布第四个屏幕采集的视频。 :::info[信息] 目前 SDK 支持在同一时间、同一 `RtcConnection` 中发布多路音频流、一路视频流。 ::: #### 支持仅播放副歌片段 (Android, iOS) [#支持仅播放副歌片段-android-ios] 该版本新增 [`GetInternalSongCode`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_getinternalsongcode) 方法，如果你仅需要播放某一音乐资源的副歌片段，在播放前你需要调用该方法来为该副歌片段创建一个内部歌曲编号，作为该资源的唯一标识。你可以查看[在线 K 歌房文档](/zh-CN/solutions/online-ktv)了解更多 K 歌场景方案。 ### 改进 [#改进-131] #### 摄像头采集效果提升 (Android, iOS) [#摄像头采集效果提升-android-ios] 该版本从以下几个方面提升了摄像头采集效果： 1. 支持摄像头采集曝光调节 新增 [`IsCameraExposureSupported`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_iscameraexposuresupported) 和 [`SetCameraExposureFactor`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_setcameraexposurefactor) 方法，用于查询当前设备是否支持曝光调节和设置摄像头的曝光增益。 2. 优化默认摄像头选择 (iOS) 自该版本起，SDK 的默认摄像头选择对齐 iOS 系统相机行为。如果设备拥有多个后置摄像头，则在视频采集时可以获得更好的拍摄视野、变焦能力、低光性能和深度感应，从而提高视频采集的质量。 #### 虚拟背景算法升级 [#虚拟背景算法升级-5] 该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。 #### 跨频道连麦优化 [#跨频道连麦优化-5] 该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 [`StartOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`StartOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 时，你可以指定最多 6 个目标频道。 #### 视频编解码查询能力增强 [#视频编解码查询能力增强-5] 为提升设备编解码能力查询功能，该版本在 [`CodecCapInfo`](/zh-CN/api-reference/rtc/unity/class-codeccapinfo) 中新增 `codecLevels` 成员。当成功调用 [`QueryCodecCapability`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_querycodeccapability) 后，可通过 `codecLevels` 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。 #### 其他改进 [#其他改进-54] - 为了提升多种音频路由之间的切换体验，该版本新增了 [`SetRouteInCommunicationMode`](/zh-CN/api-reference/rtc/unity/device-management/audio-route#api_irtcengine_setrouteincommunicationmode) 方法，用于在通话音量模式 ([`MODE_IN_COMMUNICATION`](https://developer.android.google.cn/reference/kotlin/android/media/AudioManager?hl=en#mode_in_communication)) 下，将音频路由从蓝牙耳机切换为听筒、有线耳机或扬声器。 (Android) - 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。 - 为帮助用户了解更多类型的远端视频状态改变的原因，[`OnRemoteVideoStateChanged`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调中新增了 `REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT` 枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。 - 版权音乐新增 [`GetSongSimpleInfo`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_getsongsimpleinfo) 方法，可用于获取某一指定歌曲的详细信息，你可以通过触发的 [`OnSongSimpleInfoResult`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) 回调来获取歌曲信息。 (Android, iOS) ### 问题修复 [#问题修复-133] 该版本修复了以下问题： - 加入频道后，偶现本地用户听自己及远端的声音时出现杂音。 (macOS) - 网络异常导致频道连接断开后，频道连接恢复较慢。 - 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。 - 自采集场景下，[`SetBeautyEffectOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions)、[`SetLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)、[`SetVideoDenoiserOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 和 [`SetColorEnhanceOptions`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions) 无法自动加载插件。 - 多设备音频录制场景下，反复插拔或开启/禁用音频录制设备后，偶现调用 [`StartRecordingDeviceTest`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_startrecordingdevicetest) 进行音频采集设备测试时听不到声音。 (Windows) ### API 变更 [#api-变更-70] #### 新增 [#新增-64] - [`SetCameraExposureFactor`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_setcameraexposurefactor) (Android, iOS) - [`IsCameraExposureSupported`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_iscameraexposuresupported) (Android, iOS) - [`PreloadChannel`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_preloadchannel) - [`PreloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_preloadchannelwithuseraccount) - [`UpdatePreloadChannelToken`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_updatepreloadchanneltoken) - [`GetSongSimpleInfo`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_getsongsimpleinfo) (Android, iOS) - [`OnSongSimpleInfoResult`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) (Android, iOS) - [`GetInternalSongCode`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_getinternalsongcode) (Android, iOS) - [`Preload`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_preload2)[2/2] (Android, iOS) - [`OnLyricResult`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 中增加 `songCode` (Android, iOS) - [`OnPreLoadEvent`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 中增加 `requestId` (Android, iOS) - [`SetRouteInCommunicationMode`](/zh-CN/api-reference/rtc/unity/device-management/audio-route#api_irtcengine_setrouteincommunicationmode) (Android) - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中增加下列成员 (Windows, macOS)： - `publishThirdCameraTrack` - `publishFourthCameraTrack` - `publishThirdScreenTrack` - `publishFourthScreenTrack` - [`CodecCapLevels`](/zh-CN/api-reference/rtc/unity/class-codeccaplevels) - [`VIDEO_CODEC_CAPABILITY_LEVEL`](/zh-CN/api-reference/rtc/unity/enum-videocodeccapabilitylevel) - [`VideoCanvas`](/zh-CN/api-reference/rtc/unity/class-videocanvas) 中增加 `backgroundColor` 成员 - [`CodecCapInfo`](/zh-CN/api-reference/rtc/unity/class-codeccapinfo) 中增加 `codecLevels` 成员 - [`REMOTE_VIDEO_STATE_REASON`](/zh-CN/api-reference/rtc/unity/enum-remotevideostatereason) 中增加 `REMOTE_VIDEO_STATE_REASON_CODEC_NOT_SUPPORT` 枚举 - [`SetMaxMetadataSize`](/zh-CN/api-reference/rtc/unity/metadata/metadata-observer#api_irtcengine_setmaxmetadatasize) - [`SendMetadata`](/zh-CN/api-reference/rtc/unity/metadata/metadata-observer#api_irtcengine_sendmetadata) - [`RegisterAudioFrameObserver`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#api_imediaengine_registeraudioframeobserver) 新增 `position` 参数 - [`RegisterVideoFrameObserver`](/zh-CN/api-reference/rtc/unity/video/video-raw#api_imediaengine_registervideoframeobserver) 新增 `formatPreference` 和 `position` 参数 #### 废弃 [#废弃-22] - [`Preload`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_preload)[1/2] (Android, iOS) #### 删除 [#删除-26] - `GetObservedAudioFramePosition` - `GetPlaybackAudioParams` - `GetRecordAudioParams` - `GetMixedAudioParams` - `GetEarMonitoringAudioParams` - `GetVideoFormatPreference` - `GetObservedFramePosition` - `GetMaxMetadataSize` - [`OnReadyToSendMetadata`](/zh-CN/api-reference/rtc/unity/metadata/metadata-observer#callback_imetadataobserver_onreadytosendmetadata) ## v4.2.1 [#v421-7] 该版本于 2023 年 6 月 30 日发布。 ### 改进 [#改进-132] 该版本改进了网络传输策略，提升了音视频交互的流畅度。 ### 问题修复 [#问题修复-134] 该版本修复了以下问题： - SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。 - 发送端调用 [`SetAINSMode`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。 - 发送端将两路摄像头采集的视频进行本地合图并发布后，接收端偶现第二路摄像头画面缺失。(Windows) - 发送端启用屏幕共享功能后，偶现接收端看到共享画面的延迟较高。(macOS) - 调用 [`DestroyMediaPlayer`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-initialize#api_irtcengine_destroymediaplayer) 销毁媒体播放器时偶现崩溃。(iOS) - 屏幕共享场景下，部分机型必现接收端看到共享的画面卡顿。(Android) ## v4.2.0 [#v420-7] 该版本于 2023 年 5 月 26 日发布。 ### 升级必看 [#升级必看-76] 该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。 #### 视频采集 [#视频采集-2] 原有用于摄像头和屏幕采集的方法已删除，请改用下表中列出的替代方法，并通过设置 `sourceType` 来指定视频源。 | 已删除方法 | 替代方法 | | --- | --- | | [release-notes-unity-html-5-1-0 details](#table-slot-release-notes-unity-html-5-1-0) | [`StartCameraCapture`](/zh-CN/api-reference/rtc/unity/video/camera-capture#api_irtcengine_startcameracapture) | | [release-notes-unity-html-5-2-0 details](#table-slot-release-notes-unity-html-5-2-0) | [`StopCameraCapture`](/zh-CN/api-reference/rtc/unity/video/camera-capture#api_irtcengine_stopcameracapture) | | [release-notes-unity-html-5-3-0 details](#table-slot-release-notes-unity-html-5-3-0) | [`StartScreenCapture`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapture2)[2/2] | | [release-notes-unity-html-5-4-0 details](#table-slot-release-notes-unity-html-5-4-0) | [`StopScreenCapture`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_stopscreencapture2)[2/2] | **release-notes-unity-html-5-1-0 details** - `StartPrimaryCameraCapture` (Windows) - `StartSecondaryCameraCapture`（Windows，iOS） **release-notes-unity-html-5-2-0 details** - `StopPrimaryCameraCapture` (Windows) - `StopSecondaryCameraCapture`（Windows，iOS） **release-notes-unity-html-5-3-0 details** - `StartPrimaryScreenCapture` (Windows) - `StartSecondaryScreenCapture`（Windows，iOS） **release-notes-unity-html-5-4-0 details** - `StopPrimaryScreenCapture` (Windows) - `StopSecondaryScreenCapture`（Windows，iOS） #### 视频渲染 [#视频渲染] 自该版本起，声网 Unity SDK 不支持同时使用 [`VideoSurface`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_videosurface) 和 [`VideoSurfaceYUV`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_videosurfaceyuv) 来渲染不同的视频源。在成功创建 [`IRtcEngine`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 后，如果第一个视图是通过 [`VideoSurfaceYUV`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_videosurfaceyuv) 渲染，则在整个 [`IRtcEngine`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 生命周期中，都需要使用 [`VideoSurfaceYUV`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_videosurfaceyuv) 渲染。 #### 视频数据获取 [#视频数据获取-5] [`OnCaptureVideoFrame`](/zh-CN/api-reference/rtc/unity/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`OnPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/unity/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调中新增了 `sourceType` 参数，用于表示具体的视频源类型。 #### 媒体发布选项 [#媒体发布选项-5] - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中的 `PublishCustomAudioTrackEnableAec` 已删除，请改用 `PublishCustomAudioTrack`。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中的 `PublishTrancodedVideoTrack` 变更为 `PublishTranscodedVideoTrack`。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中的 `PublishCustomAudioSourceId` 变更为 `PublishCustomAudioTrackId`。 #### 音视频录制 [#音视频录制-5] - 删除 `GetMediaRecorder` 方法，可通过该版本新增的 [`CreateMediaRecorder`](/zh-CN/api-reference/rtc/unity/recording#api_irtcengine_createmediarecorder) 方法来创建录制对象。 - 删除 [`StartRecording`](/zh-CN/api-reference/rtc/unity/recording#api_imediarecorder_startrecording) 、[`StopRecording`](/zh-CN/api-reference/rtc/unity/recording#api_imediarecorder_stoprecording)、[`SetMediaRecorderObserver`](/zh-CN/api-reference/rtc/unity/recording#api_imediarecorder_setmediarecorderobserver) 中的 `connection` 参数。 #### 本地合图 (Windows) [#本地合图-windows] [`TranscodingVideoStream`](/zh-CN/api-reference/rtc/unity/class-transcodingvideostream) 中的枚举类 [`MEDIA_SOURCE_TYPE`](/zh-CN/api-reference/rtc/unity/enum-mediasourcetype) 变更为 [`VIDEO_SOURCE_TYPE`](/zh-CN/api-reference/rtc/unity/enum-videosourcetype)。 #### 虚拟声卡 (macOS) [#虚拟声卡-macos-1] 自该版本起，SDK 新增对第三方虚拟声卡的支持，你可以将第三方虚拟声卡作为 SDK 的音频输入或输出设备。你可以通过 stateChanged 回调来了解当前 SDK 选择的输入输出设备是否为虚拟声卡。 :::info[信息] 加频道时如果设置 AgoraALD、Soundflower 做为系统的默认输入或输出设备，会造成无声。 ::: #### 视频编码分辨率 [#视频编码分辨率] 自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。 如果你想自定义视频编码分辨率，可调用 [`SetVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法，重新设置视频编码参数配置中的视频编码分辨率。 :::warning[注意] 由于默认分辨率的提升，会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 其他兼容性变更 [#其他兼容性变更-5] - `OnApiCallExecuted` 已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。 - [`IAudioFrameObserver`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_iaudioframeobserver) 类名变更为 [`IAudioPcmFrameSink`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_iaudiopcmframesink)，因此下列方法原型也有相应更新： - [`OnFrame`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-observer#callback_iaudiopcmframesink_onframe_iaudiopcmframesink) - [`IMediaPlayer`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imediaplayer) 下的 [`RegisterAudioFrameObserver`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-observer#api_imediaplayer_registeraudioframeobserver1_imediaplayer)[1/2]、[`RegisterAudioFrameObserver`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-observer#api_imediaplayer_registeraudioframeobserver2_imediaplayer)[2/2] - [`EnableDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_enabledualstreammode)[1/2] 和 [`EnableDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_enabledualstreammode3)[2/2] 已废弃，请改用 [`SetDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setdualstreammode)[1/2] 和 [`SetDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2]。 - `StartChannelMediaRelay`、`UpdateChannelMediaRelay`、`StartChannelMediaRelayEx` 和 `UpdateChannelMediaRelayEx` 已废弃，请改用 [`StartOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`StartOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex)。 ### 新增特性 [#新增特性-113] #### AI 降噪 [#ai-降噪-5] 该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 [`SetAINSMode`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。 #### 增强虚拟背景 [#增强虚拟背景-5] 为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 [`EnableVirtualBackground`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 方法时，将自定义背景设置为更多类型： - 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。 - 将背景替换为多种格式的本地视频。 #### 视频场景化设置 [#视频场景化设置-5] 该版本新增 [`SetVideoScenario`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoscenario) 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化： - 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。 - 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。 #### 本地录制远端音视频 (Beta) [#本地录制远端音视频-beta-5] 该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 [`OnRecorderStateChanged`](/zh-CN/api-reference/rtc/unity/recording#callback_imediarecorderobserver_onrecorderstatechanged) 、[`OnRecorderInfoUpdated`](/zh-CN/api-reference/rtc/unity/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数，用于表示录制的音视频流的具体信息，并新增 [`CreateMediaRecorder`](/zh-CN/api-reference/rtc/unity/recording#api_irtcengine_createmediarecorder) 方法，用于创建本地或远端的录制对象。 你可以通过如下方法体验本地录制远端音视频功能： - [`CreateMediaRecorder`](/zh-CN/api-reference/rtc/unity/recording#api_irtcengine_createmediarecorder)：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。 - [`SetMediaRecorderObserver`](/zh-CN/api-reference/rtc/unity/recording#api_imediarecorder_setmediarecorderobserver)：设置录制回调对象。 - [`StartRecording`](/zh-CN/api-reference/rtc/unity/recording#api_imediarecorder_startrecording)：开始录制。 - [`StopRecording`](/zh-CN/api-reference/rtc/unity/recording#api_imediarecorder_stoprecording)：停止录制。 - [`DestroyMediaRecorder`](/zh-CN/api-reference/rtc/unity/recording#api_irtcengine_destroymediarecorder)：销毁录制对象。 #### 本地合图 [#本地合图-9] Windows: 该版本新增了 [`OnLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调，当你在开启本地合图或者更新本地合图配置失败时，SDK 会触发该回调并报告合图失败的原因。 macOS，iOS，Android：该版本新增本地合图功能，用户可以调用 [`StartLocalVideoTranscoder`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) 方法，在本地将多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）混合和渲染，以实现自定义布局和效果。通过这项功能，你可以轻松创建个性化的视频显示效果，满足各种场景需求，如远程会议、直播、在线教育场景，同时支持人像画中画等功能。 另外，SDK 还提供了 [`UpdateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 方法和 [`OnLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调。当你在开启本地合图后，可以调用 [`UpdateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 更新合图的配置；当你在开启本地合图或者更新本地合图配置失败时，可通过 [`OnLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调得知合图失败的原因。 :::info[信息] 本地合图对 CPU 的消耗较高，声网建议你在性能较高的设备上开启该功能。 ::: #### 多端同步 [#多端同步-5] 在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 [`GetNtpWallTimeInMs`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_getntpwalltimeinms) 方法获取当前的 NTP（网络时间协议）时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。 #### 快速出图出声 [#快速出图出声-5] 该版本新增 [`EnableInstantMediaRendering`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_enableinstantmediarendering) 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。 #### 视频渲染数据打点 [#视频渲染数据打点-5] 该版本新增 [`StartMediaRenderingTracing`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_startmediarenderingtracing) 和 [`StartMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 [`OnVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/unity/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告相关事件的信息。 声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 [`OnVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/unity/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。 ### 改进 [#改进-133] #### 优化变声 [#优化变声-5] 该版本新增了 [`SetLocalVoiceFormant`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceformant) 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 [`SetLocalVoicePitch`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch) 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。 #### 增强屏幕共享 (Android, iOS) [#增强屏幕共享-android-ios] 该版本新增 [`QueryScreenCaptureCapability`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_queryscreencapturecapability) 方法，用于查询当前设备的屏幕捕获能力。如果你想在屏幕共享时启用高帧率（如 60 Fps）、但不确定设备是否支持时，可以调用该方法、然后从返回值中得知设备支持的最高帧率是否满足需求。 该版本新增 [`SetScreenCaptureScenario`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_setscreencapturescenario) 方法，用于设置屏幕共享的场景类型，SDK 会根据场景类型自动调整共享画面的的流畅度和清晰度。 #### 提升音频文件类型兼容性 (Android) [#提升音频文件类型兼容性-android] 该版本提升了音频文件类型兼容性，你可以通过 [`StartAudioMixing`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#api_irtcengine_startaudiomixing2)[2/2]、`PlayEffect`[3/3]、`Open`、[`OpenWithMediaSource`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 方法来打开以 `Content://` 开头的 URI 文件。 #### 提升渲染兼容性 (Windows) [#提升渲染兼容性-windows-1] 提升了渲染的兼容性，解决了部分设备渲染失败而导致的黑屏问题。 #### 提升音视频同步能力 [#提升音视频同步能力-5] 针对自定义视频和音频采集场景，该版本新增 [`GetCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_getcurrentmonotonictimeinms) 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。 #### 优化多路摄像头及屏幕采集 [#优化多路摄像头及屏幕采集-3] 该版本新增 [`StartScreenCapture`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapture2)[2/2] (仅支持 PC 端) 和 [`StartCameraCapture`](/zh-CN/api-reference/rtc/unity/video/camera-capture#api_irtcengine_startcameracapture) 方法，通过多次调用并指定 `sourceType` 参数可以开启多路摄像头采集的视频流和多路屏幕采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头和显示器的场景。 #### 优化版权音乐（Android，iOS） [#优化版权音乐androidios] 针对在线 K 歌房场景，该版本新增 [`GetCaches`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_getcaches) 和 [`RemoveCache`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_removecache) 方法，用于获取、删除音乐资源缓存，并新增状态码和错误码，可方便用户排查问题。 #### 优化跨频道连麦 [#优化跨频道连麦-5] 该版本新增 [`StartOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`StartOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。 #### 多路音频自采集 [#多路音频自采集-5] 为更好地满足音频自采集的场景需求，该版本新增了 [`CreateCustomAudioTrack`](/zh-CN/api-reference/rtc/unity/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 和 [`DestroyCustomAudioTrack`](/zh-CN/api-reference/rtc/unity/audio/audio-custom-capturenrendering#api_imediaengine_destroycustomaudiotrack) 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性： - 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。 - 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。 #### 超分辨率 （Android, iOS） [#超分辨率-android-ios] 该版本提升了超分辨率的性能表现。为提升超分辨率易用性，该版本删除了 `EnableRemoteSuperResolution`，超分辨率不再需要手动开启，SDK 将自动根据用户设备性能优化远端视频的分辨率。 ### 问题修复 [#问题修复-135] 该版本修复了以下问题： **Windows** - 使用媒体播放器播放网络摄像头的 RTSP 码流时，偶现花屏。 - 加入频道后添加水印然后删除，远端仍能看到水印。 - 开始屏幕共享后添加水印，远端接收的屏幕共享画面没有水印。 - 在屏幕共享场景下，如果将一个窗口设置为前置和描边，则必现窗口前置失败。 - 在本地合图场景下，不支持对 PNG 和 GIF 图片的 Alpha 通道渲染，导致透明底色的图片显示为非透明底色。 - 加入频道后接入外接摄像头，调用 [`SetDevice`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_ivideodevicemanager_setdevice_ivideodevicemanager) 指定视频采集设备为该外接摄像头，方法未生效。 **Android** - 偶现耳返开启无效。 - 偶现回声。 - 由于 [`OnRemoteAudioStateChanged`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged) 回调异常造成客户端状态异常。 - 在红米 9A 上进行 CDN 推流，将推流的视频分辨率设置为 3840 × 2160 必现崩溃。 - 合唱模式下，OPPO R11 设备外放加入频道后，对端听到明显杂声和回音。 - 本地音乐文件结束播放时，未能触发 [`OnAudioMixingFinished`](/zh-CN/api-reference/rtc/unity/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingfinished) 回调。 - 接收端通过视频观测器接收的第一帧视频帧偶现丢包。 - 在多频道场景下开启屏幕共享，偶现远端看到的本地屏幕共享画面为黑屏。 - 开启虚拟背景时切换至后置摄像头会导致背景倒置。 **iOS** - 跨频道连麦时 [`OnFirstRemoteVideoFrame`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onfirstremotevideoframe) 回调偶现丢失。 - 接收端主动订阅大流但是异常接收小流。 - 由于 [`OnRemoteAudioStateChanged`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged) 回调异常造成客户端状态异常。 **macOS** - 接收端默认接收小流几秒后自动变为大流。 - 屏幕共享偶现共享画面抖动。 - 把播放器的渲染视图设为 UIViewController 的视图后，使用播放器播放视频，视频窗口切到全屏时视频画面会从左下角开始逐渐放大。 - 加入频道后接入外接摄像头，调用 [`SetDevice`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_ivideodevicemanager_setdevice_ivideodevicemanager) 指定视频采集设备为该外接摄像头，方法未生效。 **全平台** - 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。 - 当快速切换身份角色时，观众端听不到声音。 - 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。 ### API 变更 [#api-变更-71] #### 新增 [#新增-65] - [`StartCameraCapture`](/zh-CN/api-reference/rtc/unity/video/camera-capture#api_irtcengine_startcameracapture) - [`StopCameraCapture`](/zh-CN/api-reference/rtc/unity/video/camera-capture#api_irtcengine_stopcameracapture) - [`StartScreenCapture`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapture2)[2/2] (Windows,macOS) - [`StopScreenCapture`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_stopscreencapture2)[2/2] (Windows,macOS) - [`StartOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) - [`StartOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) - [`GetNtpWallTimeInMs`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_getntpwalltimeinms) - [`SetVideoScenario`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoscenario) - [`GetCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_getcurrentmonotonictimeinms) - [`OnLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) - [`StartLocalVideoTranscoder`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder)（macOS, iOS, Android） - [`UpdateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration)（macOS, iOS, Android） - [`QueryScreenCaptureCapability`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_queryscreencapturecapability) (iOS, Android) - [`SetScreenCaptureScenario`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_setscreencapturescenario) (iOS, Android) - [`SetAINSMode`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) - [`CreateCustomAudioTrack`](/zh-CN/api-reference/rtc/unity/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) - [`DestroyCustomAudioTrack`](/zh-CN/api-reference/rtc/unity/audio/audio-custom-capturenrendering#api_imediaengine_destroycustomaudiotrack) - [`IMusicContentCenter`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imusiccontentcenter) 中新增如下方法：(iOS, Android) - [`RemoveCache`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_removecache) - [`GetCaches`](/zh-CN/api-reference/rtc/unity/play/drm#api_imusiccontentcenter_getcaches) - [`AudioTrackConfig`](/zh-CN/api-reference/rtc/unity/class-audiotrackconfig) - [`MusicCacheInfo`](/zh-CN/api-reference/rtc/unity/class-musiccacheinfo) (iOS, Android) - [`AUDIO_AINS_MODE`](/zh-CN/api-reference/rtc/unity/enum-audioainsmode) - [`AUDIO_TRACK_TYPE`](/zh-CN/api-reference/rtc/unity/enum-audiotracktype) - [`MUSIC_CACHE_STATUS_TYPE`](/zh-CN/api-reference/rtc/unity/enum-musiccachestatustype) (iOS, Android) - [`VIDEO_APPLICATION_SCENARIO_TYPE`](/zh-CN/api-reference/rtc/unity/enum-videoapplicationscenariotype) - [`SCREEN_CAPTURE_FRAMERATE_CAPABILITY`](/zh-CN/api-reference/rtc/unity/enum-screencaptureframeratecapability) - [`RtcEngineContext`](/zh-CN/api-reference/rtc/unity/class-rtcengineconfig) 中新增 `DomainLimit` 和 `AutoRegisterAgoraExtensions` 属性 - [`OnRecorderStateChanged`](/zh-CN/api-reference/rtc/unity/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`OnRecorderInfoUpdated`](/zh-CN/api-reference/rtc/unity/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数 - [`OnCaptureVideoFrame`](/zh-CN/api-reference/rtc/unity/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`OnPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/unity/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 中增加 `sourceType` 参数 - [`BACKGROUND_SOURCE_TYPE`](/zh-CN/api-reference/rtc/unity/enum-backgroundsourcetype) 中新增 `BACKGROUND_NONE` 和 `BACKGROUND_VIDEO` - `PreloadStatusCode` 中增加 `KPreloadStatusRemoved` (iOS, Android) - `MusicContentCenterStatusCode` 中增加如下枚举：(iOS, Android) - `KMusicContentCenterStatusErrGateway` - `KMusicContentCenterStatusErrPermissionAndResource` - `KMusicContentCenterStatusErrInternalDataParse` - `KMusicContentCenterStatusErrMusicLoading` - `KMusicContentCenterStatusErrMusicDecryption` - [`MusicContentCenterConfiguration`](/zh-CN/api-reference/rtc/unity/class-musiccontentcenterconfiguration) 中新增 `maxCacheSize` (iOS, Android) - [`EnableInstantMediaRendering`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_enableinstantmediarendering) - [`StartMediaRenderingTracing`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengine_startmediarenderingtracing) - [`StartMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/unity/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) - [`OnVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/unity/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) - [`MEDIA_TRACE_EVENT`](/zh-CN/api-reference/rtc/unity/enum-mediatraceevent) - [`VideoRenderingTracingInfo`](/zh-CN/api-reference/rtc/unity/class-videorenderingtracinginfo) #### 修改 [#修改-17] - [`OnMusicChartsResult`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 中的 `status` 修改为 `error_code` (iOS, Android) - [`OnMusicCollectionResult`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 中的 `status` 修改为 `error_code` (iOS, Android) - [`OnLyricResult`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 中的 `status` 修改为 `error_code` (iOS, Android) - [`OnPreLoadEvent`](/zh-CN/api-reference/rtc/unity/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 中的 `msg` 修改为 `error_code` (iOS, Android) #### 废弃 [#废弃-23] - [`EnableDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_enabledualstreammode)[1/2] - [`EnableDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_enabledualstreammode3)[2/2] - `StartChannelMediaRelay` - `StartChannelMediaRelayEx` - `UpdateChannelMediaRelay` - `UpdateChannelMediaRelayEx` - `OnChannelMediaRelayEvent` - `CHANNEL_MEDIA_RELAY_EVENT` #### 删除 [#删除-27] - `StartPrimaryScreenCapture` (Windows) - `StartSecondaryScreenCapture` (Windows) - `StopPrimaryScreenCapture` (Windows) - `StopSecondaryScreenCapture` (Windows) - `StartPrimaryCameraCapture` (Windows) - `StartSecondaryCameraCapture` (Windows/iOS) - `StopPrimaryCameraCapture` (Windows) - `StopSecondaryCameraCapture` (Windows/iOS) - `OnApiCallExecuted` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中的 `PublishCustomAudioTrackEnableAec` - `EnableRemoteSuperResolution` - [`RemoteVideoStats`](/zh-CN/api-reference/rtc/unity/class-remotevideostats) 中删除 `superResolutionType` ## v4.1.0 [#v410-6] 该版本于 2022 年 12 月 20 日发布。 ### 升级必看 [#升级必看-77] 如果你已经使用了以下方法，请在升级到该版本后重新调用方法并更新参数设置： 删除了 `EnableDualStreamMode`[3/3] 中的 `sourceType` 参数以及 `EnableDualStreamMode`[2/3] 方法，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。 ### 新增特性 [#新增特性-114] #### 耳返 [#耳返-5] 该版本新增耳返功能。你可以调用 [`EnableInEarMonitoring`](/zh-CN/api-reference/rtc/unity/audio/audio-capture#api_irtcengine_enableinearmonitoring2) 开启耳返功能。 成功开启耳返功能后，你可以调用 [`RegisterAudioFrameObserver`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#api_imediaengine_registeraudioframeobserver) 注册音频观测器，SDK 会触发 [`OnEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#callback_iaudioframeobserverbase_onearmonitoringaudioframe) 回调报告耳返原始音频数据。你可以使用自己的音效处理模块对耳返音频数据进行前处理，实现自定义音效，声网推荐你在如下两种方式中选其一来设置耳返音频数据格式： - 调用[`SetEarMonitoringAudioFrameParameters`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#api_irtcengine_setearmonitoringaudioframeparameters) 方法设置耳返音频数据格式，SDK 会根据该方法中的参数计算采样间隔，并根据该采样间隔触发 [`OnEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#callback_iaudioframeobserverbase_onearmonitoringaudioframe) 回调。 - 在 `GetEarMonitoringAudioParams` 回调的返回值中设置耳返音频数据格式，SDK 会根据该回调的返回值计算采样间隔，并根据该采样间隔触发 [`OnEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#callback_iaudioframeobserverbase_onearmonitoringaudioframe) 回调。 如需调节耳返音量，你可以调用 [`SetInEarMonitoringVolume`](/zh-CN/api-reference/rtc/unity/audio/audio-capture#api_irtcengine_setinearmonitoringvolume)。 #### 音频采集设备测试 (Android) [#音频采集设备测试-android] 该版本支持加入频道前测试本地音频采集设备。你可以调用 [`StartRecordingDeviceTest`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_startrecordingdevicetest) 开启音频采集设备测试，测试完成后，调用 [`StopPlaybackDeviceTest`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_stopplaybackdevicetest) 方法停止音频采集设备测试。 #### 本地网络连接类型 [#本地网络连接类型-5] 为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 [`GetNetworkType`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_getnetworktype) 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 [`OnNetworkTypeChanged`](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onnetworktypechanged) 回调，报告当前的网络连接类型。 #### 音强选流 [#音强选流-5] 声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请联系技术支持。 同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗，详见[音强选流](/zh-CN/realtime-media/rtc/build/audio/audio-stream-filter)。 :::info[信息] 该版本新增音强选流功能，如需开启该功能，请联系[技术支持](https://ticket.shengwang.cn/)。 ::: #### 双流模式 [#双流模式-6] 该版本对双流模式做了优化，在加入频道前后均可调用 `EnableDualStreamMode` 和 `EnableDualStreamModeEx`。 扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式（即：默认不主动发送小流），可通过以下步骤开启发送小流： 1. 接收端主播调用 [`SetRemoteVideoStreamType`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setremotevideostreamtype) 或 [`SetRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 发起接收小流申请。 2. 发送端收到申请后自动切换为发送小流模式。 如果你想修改上述发送端的默认行为，可以调用 [`SetDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setdualstreammode)[1/2] 或 [`SetDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2] 方法，将 `mode` 参数设置为 `DISABLE_SIMULCAST_STREAM`（始终不发送小流）或 `ENABLE_SIMULCAST_STREAM`（始终发送小流）。 #### 声卡采集设备 (Windows) [#声卡采集设备-windows-1] SDK 默认使用播放设备为声卡采集设备，自该版本起，你可以另外指定声卡采集设备并将其采集到的音频发布到远端。 - [`SetLoopbackDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_setloopbackdevice)：用于指定声卡采集设备，当你不希望当前的播放设备为声卡采集设备时，可以调用该方法另外指定别的设备作为声卡采集设备。 - [`GetLoopbackDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getloopbackdevice)：用于获取当前的声卡采集设备。 - [`FollowSystemLoopbackDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_followsystemloopbackdevice)：用于设置声卡采集设备是否跟随系统默认的播放设备。 #### 空间音频 [#空间音频-9] 该版本新增了如下适用于空间音频场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。 - 隔声区域：你可以通过调用 [`SetZones`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 设置隔声区域和声音衰减系数。当音源（可以为用户或媒体播放器）跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用 [`SetPlayerAttenuation`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 和 [`SetRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) 方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖 [`SetZones`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 中的声音衰减系数。 - 多普勒音效：你可以通过设置 [`SpatialAudioParams`](/zh-CN/api-reference/rtc/unity/class-spatialaudioparams) 中的 `enable_doppler` 参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下（比如赛车游戏场景），接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用 [`SetHeadphoneEQPreset`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 方法使用预设的耳机均衡效果，以改善耳机的听感。 #### 多路摄像头 (iOS) [#多路摄像头-ios] 该版本新增多路摄像头视频采集功能，你可以通过调用 [`EnableMultiCamera`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_enablemulticamera) 开启多路摄像头采集模式，再调用 `StartSecondaryCameraCapture` 通过第二个摄像头采集视频，然后将采集到的视频发布到多频道中。 如需停止多路摄像头采集，需要先调用 `StopSecondaryCameraCapture` 停止第二个摄像头采集，然后调用 [`EnableMultiCamera`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_enablemulticamera) 并将 `enabled` 设置为 `false`。 #### 版权音乐 （iOS，Android） [#版权音乐-iosandroid] 为解决直播、语聊房、在线 K 歌房等场景下歌曲的应用版权问题，该版本新增版权音乐相关 API。你可以通过调用 [`IMusicContentCenter`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imusiccontentcenter) 类、[`IMusicPlayer`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imusicplayer) 类、[`IMusicContentCenterEventHandler`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imusiccontentcentereventhandler) 类下的相关 API 实现在实时互动场景中播放版权音乐以及相关功能，例如检索音乐资源、获取音乐榜单及榜单详情、预加载及播放音乐资源、下载歌词及海报等功能。你还可以参考[在线 K 歌房](/zh-CN/solutions/online-ktv)来体验搭配了演唱评分、美声音效等一系列功能的线上 K 歌场景化解决方案。 #### 耳机均衡器 [#耳机均衡器-4] 该版本新增 [`SetHeadphoneEQParameters`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) 方法，用于调节耳机均衡器的低频和高频参数，主要应用于空间音频场景。如果在调用 [`SetHeadphoneEQPreset`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。 #### 已编码视频帧观测器 [#已编码视频帧观测器-4] 该版本新增 [`SetRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) 和 [`SetRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) 方法，当你调用 [`RegisterVideoEncodedFrameObserver`](/zh-CN/api-reference/rtc/unity/video/video-encoded#api_imediaengine_registervideoencodedframeobserver) 方法为编码后的视频注册视频帧观测器时，SDK 默认订阅编码后的视频帧。如果你想要修改订阅选项，可以调用该新增的方法进行设置。 有关更多注册视频观测器和订阅选项的介绍，详见 [API 参考](/zh-CN/api-reference/rtc/unity/video/video-encoded#api_imediaengine_registervideoencodedframeobserver)。 #### MPUDP (MultiPath UDP) [#mpudp-multipath-udp-5] 自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在移动端和桌面端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。 :::info[信息] 如果你希望体验该功能，请联系 sales@shengwang.cn。 ::: #### 注册插件 (Windows) [#注册插件-windows-1] 该版本新增 [`RegisterExtension`](/zh-CN/api-reference/rtc/unity/extension#api_irtcengine_registerextension) 方法，用于注册插件。当使用第三方插件时，你需要按照以下顺序调用插件相关的 API： 调用 [`LoadExtensionProvider`](/zh-CN/api-reference/rtc/unity/extension#api_irtcengine_loadextensionprovider) -> [`RegisterExtension`](/zh-CN/api-reference/rtc/unity/extension#api_irtcengine_registerextension) -> [`SetExtensionProviderProperty`](/zh-CN/api-reference/rtc/unity/extension#api_irtcengine_setextensionproviderproperty) -> [`EnableExtension`](/zh-CN/api-reference/rtc/unity/extension#api_irtcengine_enableextension)。 #### 设备管理 （Windows,macOS） [#设备管理-windowsmacos] 该版本新增了一系列回调，帮助你更好地了解音视频设备的状态。 - [`OnVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/unity/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged)：当视频设备的状态发生改变时上报。 - [`OnAudioDeviceStateChanged`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicestatechanged)：当音频设备的状态发生改变时上报。 - [`OnAudioDeviceVolumeChanged`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicevolumechanged)：当音频设备或 App 的音量发生改变时上报。 #### 摄像头采集选项 [#摄像头采集选项-5] 该版本在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/unity/class-cameracapturerconfiguration) 中增加了 `FollowEncodeDimensionRatio` 成员，你可以在使用摄像头采集视频时，通过该成员设置是否跟随 [`SetVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中已经设置的视频宽高比。 #### 多频道管理 [#多频道管理-5] 该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。 - 新增 [`MuteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) 和 [`MuteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) 方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增 [`MuteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) 和 [`MuteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) 方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增 [`StartRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex)、[`StartRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex)、[`UpdateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) 和 [`StopRtmpStreamEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) 方法，用于实现多频道场景下的旁路推流。 - 新增 `StartChannelMediaRelayEx`、`UpdateChannelMediaRelayEx`、[`PauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex)、[`ResumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex)、[`StopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) 方法，用于实现多频道场景下的跨频道媒体流转发。 - 新增 [`LeaveChannelEx`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_leavechannelex2)[2/2] 方法，相较于[`LeaveChannelEx`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_leavechannelex)[1/2] 方法新增了 `options` 参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。 #### 视频编码偏好 [#视频编码偏好-5] 一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unity/class-videoencoderconfiguration) 中新增 [`AdvanceOptions`](/zh-CN/api-reference/rtc/unity/class-advanceoptions) 成员，用于视频编码属性的进阶设置： - `compressionPreference`：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。 - `encodingPreference`：视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。 #### 日志上传 [#日志上传-5] 使用声网私有媒体服务器的场景下，为支持用户在调用 [`SetLocalAccessPoint`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_setlocalaccesspoint) 方法时的进阶设置，该版本在 [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/unity/class-localaccesspointconfiguration) 类中新增 `advancedConfig` 成员参数，该参数支持如下设置： `logUploadServer`：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。 #### 用户角色切换 [#用户角色切换-5] 为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 [`OnClientRoleChanged`](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调中新增 `newRoleOptions` 参数，该参数取值如下： - `AUDIENCE_LATENCY_LEVEL_LOW_LATENCY` (1)：低延时，属于极速直播。 - `AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY` (2)：超低延时，属于互动直播。 ### 改进 [#改进-134] #### 视频信息发生改变回调 [#视频信息发生改变回调-5] 该版本优化了 [`OnVideoSizeChanged`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged) 的触发逻辑，当单独调用 `StartPreview` 时，也可触发该回调并上报本地视频大小发生改变。 #### 首帧出图 (Windows) [#首帧出图-windows-1] 该版本缩短了首帧出图时间，以提升用户视频体验。 #### 屏幕共享 [#屏幕共享-9] 该版本对屏幕共享功能做了一系列优化，除以下列出的功能性改进之外，还有一部分可用性提升，详见[问题修复](#unity-v4.1.0-fix)。 Windows： - 在 [`ScreenCaptureSourceInfo`](/zh-CN/api-reference/rtc/unity/class-screencapturesourceinfo) 中增加了 `minimizeWindow` 成员，用于表示目标窗口是否已最小化。 - 在 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/unity/class-screencaptureparameters) 中增加了 `enableHighLight`、`highLightColor` 和 `highLightWidth` 成员，支持你在屏幕共享时对目标窗口或屏幕进行描边。 - 兼容更多主流 App，包括但不限于：WPS Office，Microsoft Office PowerPoint，Visual Studio Code，Adobe Photoshop，Windows Media Player，Scratch。 - 兼容更多设备和操作系统，包括但不限于：Windows 8 系统，无独立显卡的设备，双显卡设备。 - 支持超高清视频 (分辨率为 4K，帧率为 60 fps)，你可以在满足要求的设备上使用该功能。声网推荐的最低设备规格为：intel(R) Core(TM) i7-9750H CPU @ 2.60GHZ。 macOS： - 兼容更多设备和场景，包括但不限于：双显卡设备，使用外接屏幕进行屏幕共享。 - 支持超高清视频 (分辨率为 4K，帧率为 60 fps)，你可以在满足要求的设备上使用该功能。声网推荐的最低设备规格为：2021 年 M1 MacBook Pro 16 英寸。 #### 蓝牙权限 (Android) [#蓝牙权限-android] 为简化集成步骤，自该版本起，SDK 支持你在不添加 `BLUETOOTH_CONNECT` 权限的情况下，也能让 Android 用户正常使用蓝牙。 #### CDN 推流 [#cdn-推流-5] 为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 `OnDirectCdnStreamingStats` 回调报告推送的视频流的实际分辨率。 #### 跨频道媒体流转发 [#跨频道媒体流转发-11] 该版本对 `UpdateChannelMediaRelay` 方法做了如下优化： - 4.1.0 版本前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码 `RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED`(8)，你需要重新调用 `UpdateChannelMediaRelay` 方法。 - 4.1.0 版本及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。 #### AIAEC [#aiaec-5] 该版本基于 AI 方法重构了AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。 #### 虚拟背景 [#虚拟背景-5] 该版本对虚拟背景算法做了如下优化： - 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。 - 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。 - 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。 - 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。 #### 其他改进 [#其他改进-55] - 降低了推送外部音频源时的上行延迟。 - 提升了会议场景 (`AUDIO_SCENARIO_MEETING`) 默认参数配置下的回声消除性能。 - 提升了 SDK 视频渲染的流畅度。 - 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。 - 降低了当主播调用 [`MuteLocalVideoStream`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_mutelocalvideostream) 方法时本地设备的 CPU 占用率和耗电量。（Window，macOS） ### 问题修复 [#问题修复-136] 该版本修复了以下问题： **屏幕共享相关**： - macOS： - 在屏幕共享场景下，将共享的窗口最小化或关闭共享窗口时，共享窗口自动切换为该 App 的其他窗口。 - 在屏幕共享场景下偶现系统声音音量变小。 - 在屏幕共享场景下，当共享的窗口为半屏模式时，对窗口的描边不正确。 - 在屏幕共享场景下，远端用户看到的画面偶现黑屏、卡顿、崩溃。 - 在屏幕共享场景下，偶现 [`OnNetworkQuality`](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onnetworkquality) 回调报告频道内指定用户的上下行网络状态不准确。 - Windows: - 在屏幕共享场景下，将共享的窗口最小化时，偶现远端用户出现黑屏或远端画面切换为视频小流。 - 在直播场景下，主播开启屏幕共享时，偶现观众听主播说话有回声。 - 在屏幕共享场景下偶现系统声音音量变小。 - 在屏幕共享场景下，在横屏显示器与竖屏显示器之间共享屏幕时出现黑屏。 - 在屏幕共享场景下屏蔽窗口时，屏幕共享区域超出屏幕分辨率导致崩溃。 - 调用 [`StartScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 进行屏幕共享时无法屏蔽窗口。 - 在屏幕共享场景下，远端用户看到的画面偶现黑屏、卡顿、崩溃。 - 在屏幕共享场景下，在共享窗口中看到的鼠标位置与实际位置有偏差。 - 从普通场景切换屏幕共享场景后，由于两种场景下设置的分辨率不同导致偶现崩溃。 - 在屏幕共享场景下，偶现 [`OnNetworkQuality`](/zh-CN/api-reference/rtc/unity/network#callback_irtcengineeventhandler_onnetworkquality) 回调报告频道内指定用户的上下行网络状态不准确。 **其他问题**： - 全平台： - 调用 [`GetExtensionProperty`](/zh-CN/api-reference/rtc/unity/extension#api_irtcengine_getextensionproperty2) 失败，返回空字符串。 - 当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。 - 在频道内调用 [`SetVideoEncoderConfigurationEx`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengineex_setvideoencoderconfigurationex) 将视频的分辨率调高时，偶现失效。 - 使用媒体播放器播放视频，先调用 [`Play`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 再调用 [`Pause`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`Seek`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用 [`Resume`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-control#api_imediaplayer_resume) 恢复播放后，偶现视频画面出现快进。 - 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。 - `RtcEngine` 初始化失败后调用 [`RegisterAudioEncodedFrameObserver`](/zh-CN/api-reference/rtc/unity/audio/audio-encoded#api_irtcengine_registeraudioencodedframeobserver) 会发生崩溃。 - Windows： - 调用 [`StopPreview`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_stoppreview)[1/2] 关闭本地视频预览时，导致已设置的虚拟背景一定概率失效。 - 开启虚拟背景并设置为背景虚化效果时，多次退出频道再加入频道时偶现崩溃。 - 本地端使用 1920 x 1080 的摄像头作为视频采集源，偶现远端视频的分辨率与本地端不一致。 - 通过摄像头采集视频时，如果在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/unity/class-cameracapturerconfiguration) 中设置的视频宽高比例和在 [`SetVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中设置的不一致，导致本地视频预览的画面比例未按照后者的设置呈现。 - Android： - 调用 [`SetCloudProxy`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_setcloudproxy) 设置云代理后，调用 [`JoinChannelEx`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 加入多频道失败。 - 在多人会议场景下，本地用户接听并挂断电话后，偶现本地用户和远端用户无法听见对方的声音。 - iOS： - 调用 `StartAudioMixing` 播放 `ipod-library://item` 路径的音乐文件失败。 - 同时通过 [`OnRecordAudioFrame`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#callback_iaudioframeobserverbase_onrecordaudioframe) 和 [`OnCaptureVideoFrame`](/zh-CN/api-reference/rtc/unity/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 回调分别获取的音频和视频数据时间戳不同。 - macOS： - 启动并停止音频采集设备测试后，启动音频播放设备测试时必现无声。 - [`OnVideoPublishStateChanged`](/zh-CN/api-reference/rtc/unity/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 回调报告的视频源类型不准确。 - 通过摄像头采集视频时，如果在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/unity/class-cameracapturerconfiguration) 中设置的视频宽高比例和在 [`SetVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中设置的不一致，导致本地视频预览的画面比例未按照后者的设置呈现。 ### API 变更 [#api-变更-72] #### 新增 [#新增-66] - [`EnableInEarMonitoring`](/zh-CN/api-reference/rtc/unity/audio/audio-capture#api_irtcengine_enableinearmonitoring2) - [`SetEarMonitoringAudioFrameParameters`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#api_irtcengine_setearmonitoringaudioframeparameters) - [`OnEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/unity/audio/audio-raw#callback_iaudioframeobserverbase_onearmonitoringaudioframe) - [`SetInEarMonitoringVolume`](/zh-CN/api-reference/rtc/unity/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) - `GetEarMonitoringAudioParams` - [`StartRecordingDeviceTest`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_startrecordingdevicetest) (Android) - [`StopRecordingDeviceTest`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_stoprecordingdevicetest) (Android) - [`GetNetworkType`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_getnetworktype) - [`SetRecordingDeviceVolume`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_setrecordingdevicevolume) (Windows) - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中新增 `isAudioFilterable` - [`SetDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setdualstreammode)[1/2] - [`SetDualStreamMode`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setdualstreammode2)[2/2] - [`SetDualStreamModeEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_setdualstreammodeex) - [`SIMULCAST_STREAM_MODE`](/zh-CN/api-reference/rtc/unity/enum-simulcaststreammode) - [`SetLoopbackDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_setloopbackdevice) - [`GetLoopbackDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_getloopbackdevice) - [`FollowSystemLoopbackDevice`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#api_iaudiodevicemanager_followsystemloopbackdevice) - [`SetZones`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) - [`SetPlayerAttenuation`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) - [`SetRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) - `MuteRemoteAudioStream` - [`SpatialAudioParams`](/zh-CN/api-reference/rtc/unity/class-spatialaudioparams) - [`SetHeadphoneEQPreset`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) - [`HEADPHONE_EQUALIZER_PRESET`](/zh-CN/api-reference/rtc/unity/enum-headphoneequalizerpreset) - [`EnableMultiCamera`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_irtcengine_enablemulticamera) (iOS) - `StartSecondaryCameraCapture` (iOS) - `StopSecondaryCameraCapture` (iOS) - [`SetHeadphoneEQParameters`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) - [`SetRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) - [`SetRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) - [`LeaveChannelEx`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_leavechannelex2)[2/2] - [`VideoSubscriptionOptions`](/zh-CN/api-reference/rtc/unity/class-videosubscriptionoptions) - [`MuteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) - [`MuteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) - [`MuteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) - [`MuteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) - [`StartRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex) - [`StartRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex) - [`UpdateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) - [`StopRtmpStreamEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) - `StartChannelMediaRelayEx` - `UpdateChannelMediaRelayEx` - [`PauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex) - [`ResumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) - [`StopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unity/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/unity/class-cameracapturerconfiguration) 中增加 `followEncodeDimensionRatio` - [`LocalVideoStats`](/zh-CN/api-reference/rtc/unity/class-localvideostats) 中增加 `hwEncoderAccelerating` - [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unity/class-videoencoderconfiguration) 中增加 [`AdvanceOptions`](/zh-CN/api-reference/rtc/unity/class-advanceoptions) 成员 - [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/unity/class-localaccesspointconfiguration) 中增加 `advancedConfig` 成员 - [`OnClientRoleChanged`](/zh-CN/api-reference/rtc/unity/channel#callback_irtcengineeventhandler_onclientrolechanged) 中增加 `newRoleOptions` - [`AdjustUserPlaybackSignalVolumeEx`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#api_irtcengineex_adjustuserplaybacksignalvolumeex) - [`OnVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/unity/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) (Windows,macOS) - [`OnAudioDeviceStateChanged`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicestatechanged) (Windows,macOS) - [`OnAudioDeviceVolumeChanged`](/zh-CN/api-reference/rtc/unity/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicevolumechanged) (Windows,macOS) - `MusicContentCenterStatusCode` (iOS) - `PreloadStatusCode` (iOS) - [`IMusicContentCenter`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imusiccontentcenter) 接口类及其中方法 - [`IMusicPlayer`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imusicplayer) 接口类及其中方法 - [`IMusicContentCenterEventHandler`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imusiccontentcentereventhandler) 接口类及其中回调 - [`Music`](/zh-CN/api-reference/rtc/unity/class-music) 类 （Android，iOS） - [`MusicChartInfo`](/zh-CN/api-reference/rtc/unity/class-musicchartinfo) 类（Android，iOS） - [`MusicContentCenterConfiguration`](/zh-CN/api-reference/rtc/unity/class-musiccontentcenterconfiguration) 类（Android，iOS） - [`ClimaxSegment`](/zh-CN/api-reference/rtc/unity/class-climaxsegment) 类（Android，iOS） - [`MusicCollection`](/zh-CN/api-reference/rtc/unity/class-musiccollection) 类 (iOS) - [`EnableAudioVolumeIndicationEx`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#api_irtcengineex_enableaudiovolumeindicationex) - [`IRtcEngine`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 类中的 `SetParameters` (Windows) #### 修改 [#修改-18] - `EnableDualStreamMode`[3/3] #### 废弃 [#废弃-24] - `StartEchoTest`[2/3] - `OnApiCallExecuted`，改用具体方法触发的回调 #### 删除 [#删除-28] - `EnableDualStreamMode`[2/3] - 删除了 [`LiveTranscoding`](/zh-CN/api-reference/rtc/unity/class-livetranscoding) 类中的废弃成员参数 `backgroundImage` 和 `watermark` （Android/iOS/macOS） - `OnChannelMediaRelayEvent` 中删除 `RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED`(8) ## v4.0.0 [#v400-6] 该版本于 2022 年 9 月 28 日发布。 ### 升级必看 [#升级必看-78] #### 兼容性变更 [#兼容性变更-4] v4.0.0 SDK 对部分功能的实现方式进行了优化，从而导致与 v3.x 不兼容。升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见[迁移指南](/zh-CN/realtime-media/rtc/reference/migration-guide)。 - 多频道 - 媒体流发布控制 - 警告码 ### 新增特性 [#新增特性-115] #### 多路媒体流 [#多路媒体流-5] 该版本支持通过设置 [`IRtcEngineEx`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineex) 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 实现一个 [`IRtcEngine`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengine) 实例同时采集多路音视频源并发布到远端： - 调用 `JoinChannel` 加入首个频道后，多次调用 [`JoinChannelEx`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 加入多个频道，通过不同的用户 ID 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 设置发布指定的流到不同的频道。 - 支持通过设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中的 `publishSecondaryCameraTrack` 和 `publishSecondaryScreenTrack` 同时发布多路摄像头采集或者屏幕共享的视频流。 同时，该版本支持通过 [`CreateCustomVideoTrack`](/zh-CN/api-reference/rtc/unity/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流： 1. 创建自采集视频轨道：调用 [`CreateCustomVideoTrack`](/zh-CN/api-reference/rtc/unity/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法创建一个自定义视频轨道，并获得视频轨道 ID。 2. 设置频道中待发布的自采集视频轨道：在每个频道的 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中，将 `customVideoTrackId` 参数设置为你想要发布的视频轨道 ID，并将 `publishCustomVideoTrack` 设置为 true。 3. 推送外部视频源：调用 [`PushVideoFrame`](/zh-CN/api-reference/rtc/unity/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe)，并将 `videoTrackId` 指定为步骤 2 中设置的视频轨道 ID，即可实现在多个频道中发布对应的自定义视频源。 结合多频道能力，你还可以体验如下功能： - 将多组音视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路音频流混音后通过一个用户 ID (`uid`) 发布到远端。 - 将多组视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路视频流合图后通过一个用户 ID (`uid`) 发布到远端。 #### 超高清分辨率 (Beta) (Windows, macOS) [#超高清分辨率-beta-windows-macos] 为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持 4K 分辨率。优化了 FEC（Forward Error Correction）算法，可根据视频帧包数与帧率进行自适应切换，降低 4K 场景下的视频卡顿率。 你可以在调用 [`SetVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 时，设置编码分辨率为 4K (3840 × 2160)、帧率为 60 fps。当你的设备不支持 4K 时，SDK 支持自动回退到适合的分辨率和帧率。 :::info[信息] - 该功能对设备性能和网络带宽有一定要求，在不同的平台上支持的上下行帧率也不同，如需体验该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 - 高分辨率可能会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 全高清和超高清分辨率 (Android, iOS) [#全高清和超高清分辨率-android-ios] 为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持全高清 (FHD) 和超高清 (UHD) 视频分辨率。你可以在调用 [`SetVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法时，将 `dimensions` 参数设置为 1920 × 1080 或更高的分辨率。如果你的设备不支持高分辨率，SDK 支持自动回退到适合的分辨率。 :::info[信息] - 高分辨率通常需要更高的性能消耗，为避免设备性能不足导致体验下降，声网建议你在性能较好的设备上开启全高清和超高清视频分辨率。 - 高分辨率可能会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 内置媒体播放器 [#内置媒体播放器-5] 为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 [`CreateMediaPlayer`](/zh-CN/api-reference/rtc/unity/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer) 创建媒体播放器后，你可以通过 [`IMediaPlayer`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imediaplayer) 类的一系列方法体验内置媒体播放器的各类功能： - 自动播放本地、在线、自定义的媒体资源。 - 预先加载待播放的媒体资源。 - 根据网络情况切换媒体资源的播放线路。 - 将媒体播放器的音视频流推送到任意频道、分享给远端用户。 - 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。 #### 新版 AI 降噪 [#新版-ai-降噪-5] 自该版本起，SDK 支持新版 AI 降噪（相对于 v3.x 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。 如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。 #### 超高音质 [#超高音质-5] 为还原音频的细节、提升音频的清晰度，该版本新增 `ULTRA_HIGH_QUALITY_VOICE`。在语聊、歌唱等以人声为主的场景中，你可以调用 [`SetVoiceBeautifierPreset`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) 并使用该枚举体验超高音质。 #### 空间音频 [#空间音频-10] :::info[信息] 空间音频功能当前处于实验阶段，请联系 sales@shengwang.cn 开通空间音频功能，如果需要技术支持，请 [联系技术支持](https://ticket.shengwang.cn/)。 ::: 该版本提供本地直角坐标系计算方案实现空间音频： - 使用 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) 类实现空间音频，通过 SDK 计算远端用户的空间坐标。你需要分别调用 [`UpdateSelfPosition`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`UpdateRemotePosition`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音频。 ![](https://web-cdn.agora.io/docs-files/1662709597990) - 通过 SDK 计算媒体播放器的空间坐标。你需要在 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_ilocalspatialaudioengine) 类中分别调用 [`UpdateSelfPosition`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`UpdatePlayerPositionInfo`](/zh-CN/api-reference/rtc/unity/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateplayerpositioninfo) 更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音频。 ![](https://web-cdn.agora.io/docs-files/1662709627854) #### 实时合唱 [#实时合唱-5] 该版本为实时合唱赋予了如下能力： - 支持两人及两人以上合唱。 - 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。 - 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。 该版本新增 `AUDIO_SCENARIO_CHORUS` 枚举来设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。 #### 增强的频道管理 [#增强的频道管理-5] 为满足各类业务场景对频道管理的需求，该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 结构体中新增了如下功能： - 设置或切换多种音视频源的发布 - 设置或切换频道场景、用户角色 - 设置或切换订阅视频的大小流类型 - 控制音频发布时延 在调用 `JoinChannel` 或 [`JoinChannelEx`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengineex_joinchannelex) 时设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions)，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 [`UpdateChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_updatechannelmediaoptions) 随时更新 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/class-channelmediaoptions) 中的设置，例如，切换发布的音视频源。 #### 屏幕共享 [#屏幕共享-10] 该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享。 在 Windows 和 macOS 平台： - 在加入频道前调用 [`StartScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapturebydisplayid)，然后调用 [`JoinChannel`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2)[2/2] 加入频道并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `true`，即可开始屏幕共享。 - 在加入频道后调用 [`StartScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/unity/video/screencapture#api_irtcengine_startscreencapturebydisplayid)，然后调用 `updateChannelMediaOptions` 设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `true`，即可开始屏幕共享。 在 Android 和 iOS 平台： - 在加入频道前调用 `StartScreenCapture`，然后调用 [`JoinChannel`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_joinchannel2)[2/2] 加入频道并设置 `publishScreenCaptureVideo` 为 `true`，即可开始屏幕共享。 - 在加入频道后调用 `StartScreenCapture`，然后调用 [`UpdateChannelMediaOptions`](/zh-CN/api-reference/rtc/unity/channel#api_irtcengine_updatechannelmediaoptions) 设置 `publishScreenCaptureVideo` 为 `true`，即可开始屏幕共享。 #### 设置音视频流订阅黑/白名单 [#设置音视频流订阅黑白名单-5] 该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通过 [`IRtcEngineEx`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_irtcengineex) 类下的同名方法来实现该功能。 - `SetSubscribeAudioBlacklist`：设置音频订阅黑名单。 - `SetSubscribeAudioWhitelist`：设置音频订阅白名单。 - `SetSubscribeVideoBlacklist`：设置视频订阅黑名单。 - `SetSubscribeVideoWhitelist`：设置视频订阅白名单。 如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。 #### 设置音频场景 [#设置音频场景-5] 为方便用户灵活修改音频场景，该版本新增 [`SetAudioScenario`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#api_irtcengine_setaudioscenario) 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (`AudioScenarioDefault`) 切换为高音质场景 (`AudioScenarioGameStreaming`)，你可以调用该方法。 #### 设置本地代理 [#设置本地代理-5] 该版本新增 [`SetLocalAccessPoint`](/zh-CN/api-reference/rtc/unity/network#api_irtcengine_setlocalaccesspoint) 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。 #### 垫片推流 [#垫片推流-6] 该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 [`EnableVideoImageSource`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 来开启该功能，并通过 `options` 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。 #### 本地合图 [#本地合图-10] 该版本新增本地合图功能，可支持在本地将多路视频流合并为一路视频流。常见场景如下： 在直播场景或使用旁路推流功能时，可以在本地将多个主播的画面合并为一个画面。 将本地采集的多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）合并为一路视频流，然后在频道内发布已合图的视频流。 你可以调用 [`StartLocalVideoTranscoder`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) 方法开启本地合图、调用 [`StopLocalVideoTranscoder`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#api_irtcengine_stoplocalvideotranscoder) 方法停止本地合图；在开启本地合图后，可以调用 [`UpdateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/unity/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 进行本地合图的配置更新。 #### 视频设备管理 [#视频设备管理-2] 视频采集设备可能支持多种视频格式，每一种格式都支持不同的视频帧宽度、视频帧高度、帧率组合。 该版本新增 [`NumberOfCapabilities`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_ivideodevicemanager_numberofcapabilities) 和 [`GetCapability`](/zh-CN/api-reference/rtc/unity/device-management/video-device#api_ivideodevicemanager_getcapability) 方法，用于获取视频采集设备支持的视频格式数量以及指定视频格式下的视频帧详细信息。在调用 `StartPrimaryCameraCapture` 或 `StartSecondaryCameraCapture` 方法使用摄像头采集视频时，你可以使用指定的视频格式进行采集。 SDK 会根据你在 [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unity/class-videoencoderconfiguration) 中的设置，自动选择选择视频采集设备的最佳视频格式进行采集。一般情况下，你不需要用到该组新增方法。 ### 改进 [#改进-135] #### 快速切换频道 [#快速切换频道-5] 该版本通过 `LeaveChannel` 和 `JoinChannel` 切换频道即可实现和 v3.x 中 `SwitchChannel` 一样的切换速度，无需额外调用 `SwitchChannel` 方法。 #### 推送外部视频帧 [#推送外部视频帧-5] 该版本新增支持推送 I422 格式的外部视频帧，你可以通过 [`PushVideoFrame`](/zh-CN/api-reference/rtc/unity/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe) 方法将 I422 格式的外部视频帧推送至 SDK。 #### 视频画面宽高变化回调 [#视频画面宽高变化回调] 该版本新增 [`OnTextureSizeModify`](/zh-CN/api-reference/rtc/unity/video/video-rendering#callback_videosurface_ontexturesizemodify)，你可以通过该 API 来监听视频画面的宽度和高度变化。 #### 本地人声音调 [#本地人声音调-5] 该版本在 [`OnAudioVolumeIndication`](/zh-CN/api-reference/rtc/unity/audio/audio-basic#callback_irtcengineeventhandler_onaudiovolumeindication) 的 [`AudioVolumeInfo`](/zh-CN/api-reference/rtc/unity/class-audiovolumeinfo) 中新增 `voicePitch` 参数。你可以通过 `voicePitch` 获取本地用户的人声音调，从而实现唱歌评分等业务功能。 #### 本地视频预览 [#本地视频预览-5] 该版本优化了 `StartPreview` 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 `StartPreview` 方法来开启视频预览，无调用时序要求。 #### 订阅视频流 [#订阅视频流-5] 你可以通过 [`SetRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/unity/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="flutter" /> ### 已知问题和局限性 [#已知问题和局限性-3] **AirPods Pro 蓝牙连接问题 (iOS)** 由于 AirPods Pro 不支持在通话音量模式下使用 A2DP 协议，可能会导致该设备在该模式下无法成功连接。 ## v6.6.4 (对应 Native v4.6.4) [#v664-对应-native-v464] 该版本于 2026 年 8 月 31 日发布。 ### 升级必看 [#升级必看-79] #### iOS 27 横屏采集画面方向适配 (iOS) [#ios-27-横屏采集画面方向适配-ios] 在使用 Xcode 27 编译 App 并运行于 iOS 27.0 及以上系统时，由于声网 RTC SDK 旧版本依赖的界面方向相关系统 API，如 [`UIApplicationWillChangeStatusBarOrientationNotification`](https://developer.apple.com/documentation/uikit/uiapplication/willchangestatusbarorientationnotification)，在 iOS 27 中不再支持，导致 App 在横屏界面下启用摄像头采集时出现采集画面方向异常。该版本已完成新方案适配。 更多信息请参考 Apple 的 [iOS & iPadOS 27 Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-27-release-notes)。 ### 新增特性 [#新增特性-116] #### 视频采集 (Android) [#视频采集-android] 新增两个回调事件，用于通知 Android 广角 / 超广角摄像头采集开启的成功或失败。 ### 问题修复 [#问题修复-137] 该版本修复了以下问题： - 修复了断网后 `onNetworkQuality` 回调报告的网络质量可能不准确的问题。(Android, iOS) - 修复了接收端设置音频场景为`AUDIO_SCENARIO_AI_CLIENT`，发送端频繁停止和恢复发送音频流，当接收端网络不佳时偶现无声问题。(Android, iOS) - 修复了使用有线耳机进行音视频互动时，在特定音频路由配置场景下偶现音质变差的问题。(Android, iOS) - 修复了自渲染视频帧场景下，本地预览画面偶现卡住的问题。(Android, iOS) - 修复了在 Android 模拟器上部分场景下偶现回声的问题。(Android, iOS) - 修复了启用 Google 安全加固后，音视频互通过程中偶现 App 崩溃或无响应（ANR）的问题。(Android, iOS) - 修复了 Android 手表连接蓝牙耳机时，音频路由可能切换到外放的问题。(Android) - 修复了 App 集成调用 `setExternalVideoSource` 设置推送的外部视频源类型为已编码的视频帧（`ENCODED_VIDEO_FRAME`），推送的已编码视频帧包含的 SEI 信息长度如果与编码协议规定不匹配，偶现崩溃问题。(Android, iOS) - 修复了音视频互动场景下偶现 App 崩溃的问题。(Android) - 修复了 Web 与 Native 音视频互通场景下，偶现视频编码失败、远端视频卡顿或花屏的问题。(Android) - 修复了开启媒体播放器缓存后，在断网场景下播放已缓存资源时，可能延迟约 10 秒并回调错误的问题。(Android, iOS) - 修复了使用媒体播放器播放 CDN 流时，分辨率变化后偶现花屏的问题。(Android) - 修复了 App 以通信模式（`CHANNEL_PROFILE_COMMUNICATION`）加入频道后，调用 `updateChannelMediaOptions` 更新频道媒体选项后，NCS 和 RESTful API 返回的频道信息被错误识别为互动直播模式的问题。(Android, iOS) ## v6.6.2 (对应 Native v4.6.2) [#v662-对应-native-v462] 该版本于 2026 年 3 月 18 日发布。 ### 升级必看 [#升级必看-80] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的废弃及删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 直推 CDN 相关接口废弃 [#直推-cdn-相关接口废弃-6] 该版本废弃直推 CDN 功能的相关接口，并会在后续版本中删除，请改用[服务端旁路推流](/zh-CN/realtime-media/media-push)。 - `setDirectCdnStreamingAudioConfiguration` - `setDirectCdnStreamingVideoConfiguration` - `startDirectCdnStreaming` - `stopDirectCdnStreaming` - `DirectCdnStreamingMediaOptions` - `DirectCdnStreamingStats` - `DirectCdnStreamingState` - `DirectCdnStreamingReason` #### 虚拟节拍器接口废弃 [#虚拟节拍器接口废弃-6] 该版本废弃虚拟节拍器功能的相关接口，并会在后续版本中删除。 - [`startRhythmPlayer`](/zh-CN/api-reference/rtc/flutter/play/rhythmplayer#api_irtcengine_startrhythmplayer) - [`configRhythmPlayer`](/zh-CN/api-reference/rtc/flutter/play/rhythmplayer#api_irtcengine_configrhythmplayer) - [`onRhythmPlayerStateChanged`](/zh-CN/api-reference/rtc/flutter/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) #### 水印接口废弃 [#水印接口废弃-6] 该版本废弃水印功能的相关接口，推荐使用该版本新增的水印接口。 - [`addVideoWatermark`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2) - [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex) #### 冗余接口删除 [#冗余接口删除-6] 该版本删除了下列冗余接口及参数： - `setLocalPublishFallbackOption` - `onLocalPublishFallbackToAudioOnly` - `onDownlinkNetworkInfoUpdated` - `onWlAccStats` - `enableWirelessAccelerate` #### 美妆功能实现变更 [#美妆功能实现变更-6] 受该版本美颜重构的影响，自 v4.6.2 起，不再支持调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/flutter/extension#api_irtcengine_setextensionproperty) 启用美妆功能，改用 `STYLE_MAKEUP` 节点实现。 #### 双流模式行为变更 [#双流模式行为变更-3] - v4.6.2 之前：发送端开启小流自适应模式 (autoSimulcastStream) 时，不会主动发送小流，仅当主播身份的接收端调用 [`setRemoteVideoStreamType`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_setremotevideostreamtype) 发起小流申请后，发送端收到申请才会开始发送小流。 - v4.6.2 及之后版本：发送端开启小流自适应模式 (autoSimulcastStream) 时，会根据订阅端用户的下行网络质量，自动决定发送或停止发送小流。若将 **mode** 设置为其他发送模式或显式配置了小流的宽、高、码率或帧率，则此自适应功能失效。 #### 新增域名白名单 [#新增域名白名单-6] 如果你由之前的版本升级到 v4.6.2 且使用了域名白名单功能（`RtcEngineConfig` 下的 `domainLimit` 为 `true`），请在白名单中添加以下域名，以确保互通顺畅： - `*.rtnsvc.com` - `*.realtimemesh.com` #### EncodedVideoFrameInfo 结构体删除参数 uid [#encodedvideoframeinfo-结构体删除参数-uid-4] 该版本删除了 [`EncodedVideoFrameInfo`](/zh-CN/api-reference/rtc/flutter/class-encodedvideoframeinfo) 结构体中的 `uid` 参数。你可以直接从 [`onEncodedVideoFrameReceived`](/zh-CN/api-reference/rtc/flutter/video/video-encoded#callback_ivideoencodedframeobserver_onencodedvideoframereceived) 回调中获取 `uid` 信息。如果你之前集成过相关代码，请相应更新集成逻辑。 ### 新增特性 [#新增特性-117] #### 多路分辨率视频流 [#多路分辨率视频流-6] 该版本新增多路分辨率视频流（Adaptive Bitrate Video Streaming，简称 ABR）功能，支持对同一视频源设置同时发送多路不同分辨率的视频流，并支持多频道场景。接收端通过自动/手动订阅目标分辨率的视频流。 启用 ABR 后，你可以配置不同分辨率的视频流（最多四层分辨率，即一个最高分辨率的主流和三层其他较低分辨率的视频流），并设置视频流的分辨率、码率、是否启用分层推流回退等选项来灵活控制流的发布。启用分层推流回退后，SDK 会在弱网环境下自动回退到低分辨率的视频流，确保流畅的观看体验。订阅端可根据实际需求选择想要接收的视频流。适用于会议场景、大班课、互动直播等多终端、多网络环境，可显著提升弱网下的观看体验。 #### 多路径网络传输 [#多路径网络传输-6] 该版本新增多路径传输功能，适用于终端支持多网卡传输（比如 5G、Wi-Fi、LAN）的设备，可以有效降低甚至消除弱网带来的体验回退，适用于弱网环境、对传输稳定性要求高的实时音视频通信场景，如车载、IoT、火车、高速公路等复杂网络环境。通过在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中设置 `enableMultipath` 为 `true`，可开启多路径传输能力。支持两种传输模式（[`MultipathMode`](/zh-CN/api-reference/rtc/flutter/enum-multipathmode)）： - 动态模式：（默认）根据网络状况动态选择最佳路径进行传输，适用于流量敏感、对体验要求比较高的场景，如会议、教育等。动态模式下，你可以通过 `preferMultipathType` 指定首选的网络传输路径（如优先 Wi-Fi 或移动网络）。 - 全冗余模式：数据会在所有可用网络路径上同时传输，适用于流量不敏感，对体验有极致要求的场景，如户外采播、平行操控等。该模式会产生额外费用，如需使用请[联系技术支持](https://ticket.shengwang.cn/)。 上下行还可分别通过 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中的 `uplinkMultipathMode`、`downlinkMultipathMode` 配置。启用后，SDK 会通过回调 [`onMultipathStats`](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onmultipathstats) 实时上报各路径的传输统计信息，包括每一个传输路径的流量消耗，便于开发者监控和优化网络表现。 #### 视频质量评分 [#视频质量评分-6] 该版本在 [`RemoteVideoStats`](/zh-CN/api-reference/rtc/flutter/class-remotevideostats) 中新增 `mosValue` 成员，报告声网实时视频 MOS（平均主观意见分）评估系统对接收到的远端视频流的质量评分。评分共有 5 个档次，5 分表示视频画质优秀，画面清晰无噪点，1 分表示视频画质极差，画面严重模糊。你可以通过该参数实时观测远端视频流的主观画质表现，便于动态调整视频参数、优化用户体验，或用于质量监控和告警等场景。如需启用该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 支持添加多个水印 [#支持添加多个水印-6] 该版本废弃了 [`addVideoWatermark`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2) 和 [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex) 方法，新增 [`addVideoWatermarkWithConfig`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/watermark#api_irtcengine_addvideowatermark3) 和 [`addVideoWatermarkWithConfigEx`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex1) 方法，支持通过水印 ID 来给视频添加多个水印，并可对水印进行排序。如果你需要移除指定水印，可调用 [`removeVideoWatermark`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/watermark#api_irtcengine_removevideowatermark) 方法。 #### Token 更新结果回调 [#token-更新结果回调-6] 该版本新增 [`onRenewTokenResult`](/zh-CN/api-reference/rtc/flutter/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调及 [`RenewTokenErrorCode`](/zh-CN/api-reference/rtc/flutter/enum-renewtokenerrorcode) 错误码。当调用 `renewToken` 方法更新 Token 后，SDK 会通过 [`onRenewTokenResult`](/zh-CN/api-reference/rtc/flutter/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调通知 Token 更新的结果，并通过 [`RenewTokenErrorCode`](/zh-CN/api-reference/rtc/flutter/enum-renewtokenerrorcode) 返回详细的错误码，开发者可在回调中根据错误码及时处理 Token 更新失败的场景。 #### Android 新增支持共享单个 App [#android-新增支持共享单个-app-2] 从 Android 14 开始，系统支持用户在屏幕共享时选择共享整个屏幕或共享单个 App，以提升隐私保护和多任务处理能力。 该版本适配了该系统能力，在支持共享整个屏幕的基础上，新增支持共享单个 App。同时，为便于管理相关事件，新增 [`onLocalVideoEvent`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onlocalvideoevent) 回调，用于报告本地视频，尤其是屏幕共享相关的事件。 #### Android 新增权限被授予回调 [#android-新增权限被授予回调-2] 为便于确认屏幕共享场景下的权限授权情况，该版本新增 [`onPermissionGranted`](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onpermissiongranted) 回调。你可以通过该回调判断当前用户授予的是相机（Camera）权限还是屏幕（Screen）权限。 #### Media Player 支持获取音频缓冲延迟 [#media-player-支持获取音频缓冲延迟-6] 为解决 K 歌场景中可能会出现的主唱与伴唱伴奏不同步的问题，该版本在 Media Player 模块中新增 [`getAudioBufferDelay`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-info#api_imediaplayer_getaudiobufferdelay) 方法，用于获取播放媒体文件时毫秒级的音频缓冲延迟。 #### 画中画功能 [#画中画功能] 该版本新增画中画（Picture-in-Picture，PiP）功能，支持将视频通话窗口以画中画模式显示，让用户在切换应用或返回主屏幕时仍能继续观看视频通话。 该功能支持自动进入画中画模式，并提供了丰富的配置选项。在 Android 平台上，你可以配置画中画窗口的宽高比、初始位置、无缝调整大小等参数；在 iOS 平台上，你可以配置视频流的布局方式（支持流式布局，视频流从左到右、从上到下排列）、画中画窗口的尺寸、系统控制按钮样式等。同时，该功能还支持通过 [`AgoraPipStateChangedObserver`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_agorapipstatechangedobserver) 监听画中画状态变化，便于及时处理进入、退出或失败等场景。适用于视频通话、在线教育、直播等需要多任务处理的场景，提升用户的使用体验。 #### 其他 [#其他-29] - 新增 [`setPlaybackAudioFrameBeforeMixingParameters`](/zh-CN/api-reference/rtc/flutter/audio/audio-raw#api_irtcengine_setplaybackaudioframebeforemixingparameters1) 方法用于设置 [`onPlaybackAudioFrameBeforeMixing`](/zh-CN/api-reference/rtc/flutter/audio/audio-raw#callback_iaudioframeobserver_onplaybackaudioframebeforemixing) 回调中返回的音频帧格式，包括采样率、声道数以及每次回调的数据采样点数。调用此方法后，SDK 会按照设定的参数返回混音前的原始音频数据，便于开发者进行自定义处理或分析。 - 新增 [`preloadEffectEx`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_preloadeffectex) 方法，用于将指定音效文件预加载到指定频道，支持本地或在线音效文件，便于后续快速播放，适合多频道场景。 - 新增 [`playEffectEx`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengineex_playeffectex) 方法，用于在指定频道播放音效文件，支持设置循环次数、音调、空间位置、音量、是否发布到频道及播放起始位置等参数，满足丰富的音效播放需求。 - 本地截图上传功能支持通过 [`ContentInspectModule`](/zh-CN/api-reference/rtc/flutter/class-contentinspectmodule) 中新增的 `position` 成员设置截图的视频观测位置，从而实现对原始视频数据或效果处理前后的视频流进行截图并上传。 - 为了提升用户使用绿幕或蓝幕开启虚拟背景功能时，人像分割的准确性和稳定性，该版本在 [`SegmentationProperty`](/zh-CN/api-reference/rtc/flutter/class-segmentationproperty) 中新增 `screenColorType` 属性，支持指定背景幕布的颜色为绿色、蓝色或自动识别。 ### 改进 [#改进-136] #### 美颜重构 [#美颜重构-6] 该版本对美颜功能进行了彻底重构和升级，不仅拓展了美颜功能，提升了美颜效果和性能，还解决了美颜参数配置复杂、集成成本高、美颜资源依赖网络易失效等痛点。主要改进包括： - **新增美颜功能**：新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。 - **API 大幅简化**：将过去版本中的基础美颜、美型、美妆、滤镜功能整合为 `BEAUTY`、`STYLE_MAKEUP`、`FILTER` 三个核心节点 (node)，通过 [`VideoEffectObject`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ivideoeffectobject) 统一管理生命周期和参数设置，减少频繁 API 调用带来的性能负担。 - **预设模板开箱即用**：提供多套预设风格模板（如"自然美颜"、"学姐妆"、"冷白滤镜"），大幅简化集成流程，无需手动调试数十项参数。 - **美颜参数动态控制**：该版本新增实时获取美颜参数的能力，开发者可通过 key-value 方式动态读取或修改任意细粒度参数（如磨皮强度、口红类型）。同时支持：调用预设模板快速启用风格效果、保存主播自定义参数配置、随时重置参数至默认状态，极大提升了业务层状态同步的灵活性和开发效率。 - **美颜资源外置**：该版本通过美颜资源外置化设计，将所有美颜资源（特效、滤镜、妆容）均打包为本地 bundle 文件，彻底消除因网络下载失败导致美颜失效的风险。 #### playEffect 支持无缝切换 [#playeffect-支持无缝切换-6] 该版本新增支持音效文件的无缝切换。对于同一个音效文件，如果先调用 [`preloadEffect`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_preloadeffect) 再调用 [`playEffect`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3)，在播放完成或通过 [`stopEffect`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_stopeffect) 停止播放后，SDK 不会关闭该音效文件。当再次调用 [`playEffect`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 时，SDK 会直接复用已加载的文件进行播放，从而实现循环播放和无缝切换。该能力同样适用于多频道场景。 #### 屏蔽窗口支持第二屏幕 [#屏蔽窗口支持第二屏幕-3] 在 4.6.2 之前的版本中，通过屏幕 ID（[`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapturebydisplayid)）进行屏幕共享时，不支持在多屏场景下配置屏蔽窗口（[`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/flutter/class-screencaptureparameters) 中的 `excludeWindowList`）。为提升屏幕共享体验，该版本新增支持该配置。 同时，为便于识别屏幕共享过程中屏蔽窗口的状态，该版本在 [`LocalVideoStreamReason`](/zh-CN/api-reference/rtc/flutter/enum-localvideostreamreason) 中新增 `localVideoStreamReasonScreenCaptureExcludeWindowFailed`，用于报告屏幕共享屏蔽窗口失败的情况。 #### onVideoDeviceStateChanged 回调时机优化 [#onvideodevicestatechanged-回调时机优化-3] 该版本优化了 [`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) 回调的触发时机。在此前版本中，该回调仅在加入频道后才能触发。从 4.6.2 起，在 `IRtcEngine` 完成初始化后即可收到一次该回调，加入频道后仍可继续监听该事件。 #### onNetworkQuality 准确性提升 [#onnetworkquality-准确性提升-4] 该版本提升了 [`onNetworkQuality`](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onnetworkquality) 回调中网络质量评估的准确性，使回调数据更贴近用户的主观体验。 #### onPlaybackAudioFrame 支持 24k 采样率的音频帧 [#onplaybackaudioframe-支持-24k-采样率的音频帧-5] 该版本在 [`onPlaybackAudioFrame`](/zh-CN/api-reference/rtc/flutter/audio/audio-raw#callback_iaudioframeobserverbase_onplaybackaudioframe) 中新增支持采样率为 **24000 Hz** 的音频数据。在调用 [`setPlaybackAudioFrameParameters`](/zh-CN/api-reference/rtc/flutter/audio/audio-raw#api_irtcengine_setplaybackaudioframeparameters) 设置播放音频数据格式时，可以将 `sampleRate` 设为 `24000`。 #### onEncodedVideoFrameReceived 回调支持获取频道 ID [#onencodedvideoframereceived-回调支持获取频道-id-5] 该版本在 [`onEncodedVideoFrameReceived`](/zh-CN/api-reference/rtc/flutter/video/video-encoded#callback_ivideoencodedframeobserver_onencodedvideoframereceived) 回调中新增 `channelId` 参数，方便你在获取编码后视频数据时识别其所属频道。 #### 其他改进 [#其他改进-56] - 优化了在 Windows 11 24H2 及后续版本上的权限请求，避免非必要地获取位置信息。 - 在与 Web 端互通时，新增对 g711 和 g722 音频编解码器的支持，进一步提升了跨平台音频播放的兼容性和清晰度。 - 优化了屏幕共享文档场景下的共享视频清晰度。 - 该版本新增错误码 `errPcmSendFormat` (200) 和 `errPcmSendBufferOverflow` (201)，用于报告 PCM 数据发送相关错误。 ### 问题修复 [#问题修复-138] 该合并版本修复了以下问题： - 调用 [`open`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-open#api_imediaplayer_open) 打开在线音效文件后，调用 [`playEffect`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 开始播放，当调用 [`seek`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定播放位置后，音效文件会从头开始播放。 - 在媒体音量模式下，主播在频道中发布麦克风采集的音频流，同时调用 [`playEffect`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效文件、调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_irtcengine_startaudiomixing2) 播放音乐文件，偶现回声。 - 调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengineex_joinchannelex) 加入频道，然后调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 开始跨频道媒体流转发，下麦、退出频道后重新加入频道开始连麦，偶现 [`onChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) 回调报告 `state` 为 `relayStateFailure`，`code` 为 `relayErrorServerErrorResponse`。 - 部分机型的笔记本电脑开启节能模式下，发送端共享屏幕和音频，偶现接收端听到回声。 - 在线教育场景下，偶现教师端本地看多个学生端音画不同步。 - 第二次调用 [`enumerateVideoDevices`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_ivideodevicemanager_enumeratevideodevices) 接口获取设备列表不生效。 - Windows 7 设备上共享 PPT 窗口，当 PPT 以全屏自动播放模式运行且包含大量动画时，远端看到的画面有概率出现闪烁。 ## v6.5.2 (对应 Native v4.5.2) [#v652-对应-native-v452] 该版本于 2025 年 5 月 9 日发布。 ### 新增特性 [#新增特性-118] #### 16 KB 内存页大小（Android） [#16-kb-内存页大小android-1] 自 Android 15 起，系统新增了对 16 KB 内存页大小的支持，详见 [Support 16 KB page sizes](https://developer.android.com/guide/practices/page-sizes?hl=zh-cn) 。为了保证 App 的稳定性和性能表现，自该版本起，SDK 支持 16 KB 内存页大小，确保可以在使用 4 KB 和 16 KB 内存页大小的设备上无缝运行，提升兼容性并避免崩溃。 ### 问题修复 [#问题修复-139] 该版本修复了以下问题： - 开启导唱功能播放多音轨歌曲时，调用 [`setAudioPitch`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setaudiopitch) 方法调整歌曲音调后出现杂音。 - 主播端调用 [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/flutter/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 创建自定义音频采集轨道并将 `trackType` 设为 `audioTrackDirect`，调用 [`pushAudioFrame`](/zh-CN/api-reference/rtc/flutter/audio/audio-custom-capturenrendering#api_imediaengine_pushaudioframe) 将自采集音频推送到频道内，然后调用 [`playEffect`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效，频道内的观众听主播的音频有杂音。 - 集成了 SDK 的 App 在音视频互动过程中偶现主线程阻塞导致的 UI 卡顿。 - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_irtcengine_startaudiomixing2) 播放 EAC3 音频编码的 MP4 文件时偶现无声。(Android) - 调用 [`startScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapture2) 开启屏幕共享并在 `config` 中将 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/flutter/class-screencaptureparameters) 的 `enableHighLight` 设为 `true` 对共享窗口进行描边，将共享窗口置于最上层并最大化后，本地预览的共享画面出现闪烁。(Windows) - 调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 共享指定屏幕的视频流，通过 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/flutter/class-screencaptureparameters) 的 `excludeWindowList` 来指定屏蔽的窗口，偶现部分窗口屏蔽失败。(Windows) - 应用程序共享外接屏幕的视频流，断开外接屏幕连接后偶现应用程序崩溃。(Windows) - 退出频道停止视频渲染后出现渲染内存泄漏。(Android) - 调用 [`setCameraFocusPositionInPreview`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_setcamerafocuspositioninpreview) 设置手动对焦位置，摄像头拍摄缩放画面后，设置的对焦位置不准确。(Android) - 调用 [`setExternalMediaProjection`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_setexternalmediaprojection) 设置 SDK 外部的 MediaProjection 采集屏幕视频流，当屏幕变为横屏或竖屏时，发送的视频流宽、高没有随之变化。(Android) - 调用 [`openWithMediaSource`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 并通过 `source` 参数将 `isLiveSource` 设为 `true` 并播放纯视频流，播放失败。 - 调用 [`enableVirtualBackground`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 开启虚拟背景功能，手机横竖屏旋转后，虚拟背景图像变大变模糊。(iOS) - 使用媒体播放器打开实际不存在的本地媒体文件时，播放器状态改变回调 [`onPlayerSourceStateChanged`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) 不会报告 `PLAYER_STATE_FAILED`，不符合预期。(Android) - 发送端传输多声道编码音频时，接收端偶现杂音。 - App 集成媒体播放器场景下，先后两次调用 open 打开不同媒体资源，第二次打开时，媒体播放器信息变化回调 [`onPlayerInfoUpdated`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerinfoupdated) 返回第一次媒体资源的信息，不符合预期。 - 调用 [`enableAudioVolumeIndication`](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 启用用户音量提示本地发流用户和远端用户音量相关信息，用户音量提示回调 `onAudioVolumeIndication` 返回的本地用户音量为 0。 - 音视频互通过程中偶现 App 卡死。(Android) - 调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/flutter/extension#api_irtcengine_setextensionproperty) 设置 key 为 "makeup_options" 实现美妆效果失败。(Android) - 发送端用户在光线较暗的环境中进行音视频互通，部分机型偶现本地预览的图像偏暗。(Android) - 使用 21:9 的显示屏（带鱼屏）进行音视频互通和屏幕共享场景下，设置高分辨率，如 3840*2160，屏幕共享画面在本地预览和接收端显示被裁剪。(Windows) - App 调用 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 启用垫片推流功能，偶现发送端推流成功但是 [`onVideoPublishStateChanged`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 返回当前的发布状态不是 PUB_STATE_PUBLISHED，不符合预期。 - 多频道场景下，App 在调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengineex_joinchannelex) 成功前调用 [`setupRemoteVideoEx`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengineex_setupremotevideoex) 初始化远端用户视图，偶现远端用户视图首帧图像显示延时大。 - App 退出时偶现崩溃。(iOS) - 加入频道失败后，在没有调用 [`leaveChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_leavechannel2) 离开频道的情况下，再次调用 [`joinChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 加入频道时偶现崩溃。 ## v6.5.1 (对应 Native v4.5.1) [#v651-对应-native-v451] 该版本于 2025 年 3 月 13 日发布。 ### 新增特性 [#新增特性-119] #### AI 对话场景 [#ai-对话场景-6] 该版本新增了专为与[声网对话式 AI 引擎](/zh-CN/ai)创建的智能体互动设计的 `audioScenarioAiClient` 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。 ### 改进 [#改进-137] 优化了特定机型上 SDK 初始化的耗时。(iOS) ### 问题修复 [#问题修复-140] 该版本修复了以下问题： - 集成 SDK 的 App 设置 `targetSdkVersion` 为 34，在 Android 14 系统上首次开启屏幕共享进行授权时出现崩溃。(Android) - 同时加入两个及以上的频道，连续调用 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。 - 使用媒体播放器时，调用 [`pause`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 定位到指定播放位置、然后调用 [`play`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。 - 使用媒体播放器时，调用 [`switchSrc`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换媒体资源后，调用 [`getPlaySrc`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-info#api_imediaplayer_getplaysrc_imediaplayer) 获取当前正在播放的媒体资源的路径没有变化。 - 用户在特定机型上进行音视频互动并使用蓝牙耳机，偶现调整手机音量后改变的是媒体音量而非蓝牙音量。(Android) - 音视频互动时，偶现接收端观看发送端画面出现黑屏。(Android) - 在特定机型上，调用 [`setCameraExposureFactor`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_setcameraexposurefactor) 在设备的某个特定角度设置当前摄像头的曝光系数后，当设备移动到另一个角度时，偶现视频画面变暗。(Android) - 播放 CDN 直播流时，直播流短暂中断后恢复，偶现播放画面长时间卡住。(Android) - 在推送 i420 格式的视频帧到频道内时，使用 CVPixelBuffer 会导致崩溃。(iOS) - 调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_setuplocalvideo) 设置两个视图（view），然后调用 [`enableFaceDetection`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/face-detection#api_irtcengine_enablefacedetection) 开启人脸检测，后传入的视图中无法检测到人脸信息。(iOS) - 屏幕共享场景下，接收端用户看到的共享图像出现绿线。(iOS) - 在极速直播场景下，观众通过 `string` 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。 - 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。 ## v6.5.0 (对应 Native v4.5.0) [#v650-对应-native-v450] 该版本于 2024 年 12 月 10 日发布。 ### 升级必看 [#升级必看-81] 该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 插件回调 [#插件回调] 为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的 [`ExtensionContext`](/zh-CN/api-reference/rtc/flutter/class-extensioncontext) 了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。 | 原有回调 | 现有回调 | | --- | --- | | `onExtensionEvent` | [`onExtensionEventWithContext`](/zh-CN/api-reference/rtc/flutter/extension#callback_irtcengineeventhandler_onextensioneventwithcontext) | | `onExtensionStarted` | [`onExtensionStartedWithContext`](/zh-CN/api-reference/rtc/flutter/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) | | `onExtensionStopped` | [`onExtensionStoppedWithContext`](/zh-CN/api-reference/rtc/flutter/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext) | | `onExtensionError` | [`onExtensionErrorWithContext`](/zh-CN/api-reference/rtc/flutter/extension#callback_irtcengineeventhandler_onextensionerrorwithcontext) | #### 强效视频降噪实现变更 [#强效视频降噪实现变更-6] 该版本调整了强效视频降噪的实现方式，在 [`VideoDenoiserLevel`](/zh-CN/api-reference/rtc/flutter/enum-videodenoiserlevel) 中删除了 `videoDenoiserLevelStrength`，改为调用 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 启用视频降噪后，调用 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)。 此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 [`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)。 #### 摄像头插拔状态变更 (macOS, Windows) [#摄像头插拔状态变更-macos-windows-2] 在之前版本中，当摄像头拔出并重新插入时，[`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) 回调会将设备状态报告为 `mediaDeviceStateActive`(1)（设备正在使用）。该版本起，摄像头重新插入后，设备状态将改为 `mediaDeviceStateIdle`(0)（设备就绪）。 #### 视频编码偏好变更 [#视频编码偏好变更-6] 为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好： - 在 [`CompressionPreference`](/zh-CN/api-reference/rtc/flutter/enum-compressionpreference) 枚举类中新增 `preferCompressionAuto` (-1) 枚举，并替代原有的 `preferQuality` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `preferLowLatency` 或 `preferQuality`，以获得最佳的用户体验。 - 在 [`DegradationPreference`](/zh-CN/api-reference/rtc/flutter/enum-degradationpreference) 枚举类中新增 `maintainAuto` (-1) 枚举，并替代原有的 `maintainQuality` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `maintainFramerate`、`maintainBalanced` 或 `maintainResolution`，以获得最优的综合质量体验 (QoE)。 ### 新增特性 [#新增特性-120] #### 高级美颜 [#高级美颜-6] 该版本新增以下两种高级美颜功能： - 美型：调用 [`setFaceShapeBeautyOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 [`setFaceShapeAreaOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapeareaoptions) 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。 - 美妆：调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/flutter/extension#api_irtcengine_setextensionproperty) 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。 :::info[信息] 目前，高级美颜功能为**限时免费**，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 秀场直播场景 [#秀场直播场景-6] 该版本在 [`VideoApplicationScenarioType`](/zh-CN/api-reference/rtc/flutter/enum-videoapplicationscenariotype) 类下新增枚举 `applicationScenarioLiveshow`(3)（秀场直播），你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为[秀场直播](/zh-CN/solutions/showroom)。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，重点提升了首帧出图体验和画质表现，同时增强了在弱网环境和低端设备上的画质和流畅度表现。 #### 限制视频渲染帧率 [#限制视频渲染帧率-6] 该版本新增 [`setLocalRenderTargetFps`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_setlocalrendertargetfps) 和 [`setRemoteRenderTargetFps`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_setremoterendertargetfps) 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。 在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。 #### 滤镜效果 [#滤镜效果-6] 该版本新增 [`setFilterEffectOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setfiltereffectoptions) 方法，你可以在 `config` 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 `built_in_whiten_filter.cube` 文件，用于快速实现美白滤镜效果。 #### 本地音频合流 [#本地音频合流-6] 该版本新增本地音频合流功能，你可以调用 [`startLocalAudioMixer`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/audiomixer#api_irtcengine_startlocalaudiomixer) 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 [`stopLocalAudioMixer`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/audiomixer#api_irtcengine_stoplocalaudiomixer) 方法停止本地音频合流；在合流过程中，可以调用 [`updateLocalAudioMixerConfiguration`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/audiomixer#api_irtcengine_updatelocalaudiomixerconfiguration) 方法更新正在合流的音频流配置。 该功能的使用场景示例如下： - 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。 - 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。 - 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。 #### 外部 MediaProjection (Android) [#外部-mediaprojection-android-1] 该版本新增 [`setExternalMediaProjection`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_setexternalmediaprojection) 方法，该方法支持你自行设置外部 `MediaProjection`，并取代 SDK 申请的 `MediaProjection`。 如果你具备自行申请 `MediaProjection` 的开发能力，可通过该功能实现更加灵活的屏幕采集。 #### EGL 环境上下文 (Android) [#egl-环境上下文-android-1] 该版本新增了 [`setExternalRemoteEglContext`](/zh-CN/api-reference/rtc/flutter/video/video-custom-capturenrendering#api_irtcengine_setexternalremoteeglcontext) 方法，用于设置远端视频流渲染的 EGL 环境上下文。使用 Texture 格式的视频数据进行远端视频自渲染时，你可以通过该方法替换 SDK 默认的远端 EGL 环境上下文，实现统一的 EGL 上下文管理。 #### 色彩空间设置 [#色彩空间设置-6] 该版本在 [`VideoFrame`](/zh-CN/api-reference/rtc/flutter/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/flutter/class-externalvideoframe) 中新增了 **colorSpace**，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。 #### AI 调音器 [#ai-调音器-6] 该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 [`enableVoiceAITuner`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/audio-effect#api_irtcengine_enablevoiceaituner) 方法并传入 [`VoiceAiTunerType`](/zh-CN/api-reference/rtc/flutter/enum-voiceaitunertype) 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。 #### 1v1 视频通话场景 [#1v1-视频通话场景-6] 该版本在 [`VideoApplicationScenarioType`](/zh-CN/api-reference/rtc/flutter/enum-videoapplicationscenariotype) 类下新增枚举 `applicationScenario1v1`（1v1 视频通话）。你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。 #### 版权音乐优化 (Android, iOS) [#版权音乐优化-android-ios-1] - 该版本新增 [`setPlayMode`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusicplayer_setplaymode) 方法，用于设置音乐资源的播放模式。在在线 K 歌房等场景下，你可以根据需求启用伴唱、原唱或导唱模式。 - 该版本新增 [`destroyMusicPlayer`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_destroymusicplayer) 方法，用于销毁音乐播放器并释放相应的资源。 #### 其他 [#其他-30] - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调新增 `localVideoStreamReasonDeviceDisconnected` 枚举，表示当前正在使用的视频采集设备已经断开连接（例如，被拔出）。(Windows) - [`MediaDeviceStateType`](/zh-CN/api-reference/rtc/flutter/enum-mediadevicestatetype) 新增 `mediaDeviceStatePluggedIn` 枚举，表示设备已插入。 ### 改进 [#改进-138] #### 虚拟背景算法优化 [#虚拟背景算法优化-12] 该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。 #### 录制本地预览视频 [#录制本地预览视频-6] 该版本在 [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/flutter/class-recorderstreaminfo) 中新增 **type** 成员。当调用 [`createMediaRecorder`](/zh-CN/api-reference/rtc/flutter/recording#api_irtcengine_createmediarecorder) 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 [`MediaRecorderConfiguration`](/zh-CN/api-reference/rtc/flutter/class-mediarecorderconfiguration) 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 [`startRecording`](/zh-CN/api-reference/rtc/flutter/recording#api_imediarecorder_startrecording) 即可开始录制本地预览的视频。 #### 指定视频观测位置截图 [#指定视频观测位置截图-6] 该版本新增 [`takeSnapshotWithConfig`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/snapshot#api_irtcengine_takesnapshot2) 和 [`takeSnapshotWithConfigEx`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex2) 方法，你可以在调用该方法时通过 `config` 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。 #### 自定义音频采集改进 [#自定义音频采集改进-6] 该版本在 [`AudioTrackConfig`](/zh-CN/api-reference/rtc/flutter/class-audiotrackconfig) 中新增了 `enableAudioProcessing` 成员参数，用于控制是否对 `audioTrackDirect` 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 `false`，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。 #### 自适应硬解支持 (Android, Windows) [#自适应硬解支持-android-windows-1] 该版本新增自适应硬解支持，改进了低端机的渲染流畅性，有效降低系统负载。 #### 渲染能力提升 (Windows) [#渲染能力提升-windows-2] Windows 设备上默认启用 DirectX 11 渲染器，可提供高性能、高质量的图形渲染能力。 #### 人脸区域美颜 [#人脸区域美颜-6] 为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。 #### 其他改进 [#其他改进-57] - 通过拼接视频帧和 Alpha 数据实现 Alpha 透明特效的应用场景下，提升了接收端的渲染性能，有效减少卡顿和延迟。（Android, iOS） - 优化了调用 [`queryDeviceScore`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_querydevicescore) 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。 - 支持使用 YV 12 格式的虚拟摄像头作为视频采集设备。(Windows) - 调用 [`switchSrc`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 [`onPlayerEvent`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent) 回调报告 `playerEventSwitchError` 事件，表示媒体资源切换时发生错误。 - 调用 [`setPlaybackSpeed`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，最低支持 0.3 倍速播放。 - 优化了传输策略，调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_enableinstantmediarendering) 不再对传输链路的安全性产生影响。 - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增 `localVideoStreamReasonScreenCaptureDisplayDisconnected` 枚举，表示进行屏幕采集的显示器已断开连接。(Windows, macOS) - 优化了共享窗口的视频链路，降低了 CPU 占用率。(macOS) - 优化了屏幕共享场景下的回声消除。(Windows) - 该版本在 [`Metadata`](/zh-CN/api-reference/rtc/flutter/class-metadata) 中新增 `channelId` 参数，用于获取发送 Metadata 的源频道名称。 - 废弃了 [`ClientRoleChangeFailedReason`](/zh-CN/api-reference/rtc/flutter/enum-clientrolechangefailedreason) 中的冗余枚举值 `clientRoleChangeFailedRequestTimeOut`、`clientRoleChangeFailedConnectionFailed`。 ### 问题修复 [#问题修复-141] 该版本修复了以下问题： - 调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享屏幕时，通过 **regionRect** 指定的窗口采集区域不准确，导致接收端看到的屏幕共享窗口宽高错误。（Windows） - 当发送端视频源类型为 JPEG 格式时，偶现接收端帧率低于预期。(Android、iOS) - 在播放音乐内容中心的音乐资源时，偶现杂音和卡顿。(Android) - 在 App 没有获取麦克风权限时，通过 [`MusicPlayer`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusicplayer) 播放伴奏音乐偶现卡顿。(Android) - 音视频互动过程中被系统来电打断后，通过 `onAudioVolumeIndication` 回调上报的用户音量错误。(Android) - 在接收端默认订阅视频小流、加入频道时不自动订阅任何视频流的前提下，加入频道后调用 `muteRemoteVideoStream(uid,false)` 恢复接收视频流，但接收到的视频流为视频大流，不符合预期。(Android) - Windows 7 系统下进行音视频互动，偶现找不到系统文件的报错。(Windows) - 调用 [`followSystemRecordingDevice`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_followsystemrecordingdevice) 或 [`followSystemPlaybackDevice`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_followsystemplaybackdevice) 设置 SDK 使用的音频采集或播放设备不跟随系统默认的音频播放设备，当音频设备被移除时，本地音频状态回调 [`onLocalAudioStateChanged`](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) 没有被触发，不符合预期。(Windows) - 音视频互动过程中，偶现接收端听发送端没有声音。(iOS) - 音视频互动过程中，如果发送端设备的系统版本为 iOS 17，偶现接收端听不到来自发送端的声音。(iOS) - 直播场景下，观众端因切换网络导致断开连接，重新连接直播间花费的时间长于预期。(iOS) - App 启动后使用媒体播放器播放在线媒体资源，播放无声。(iOS) - 音视频互动过程中被系统其他 App 打断后恢复，偶现音频采集无声。(iOS) - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_irtcengine_startaudiomixing2) 后，立即调用 [`pauseAudioMixing`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_irtcengine_pauseaudiomixing) 暂停播放音乐文件不生效。 - 音视频互动过程中偶现崩溃。(Android) - 在实时互动过程中，当多个远端同时加入频道时 App 偶现崩溃。(iOS) - App 切后台一段时间、然后返回前台时，远端视频画面偶现卡住或花屏。(iOS) - 发送端调用 `startDirectCdnStreaming` 开始直接向 CDN 推流后，频繁开关或切换网络，偶现接收端黑屏但发送端未收到推流失败回调。(iOS) - 调用 [`pushAudioFrame`](/zh-CN/api-reference/rtc/flutter/audio/audio-custom-capturenrendering#api_imediaengine_pushaudioframe) 推送外部音频数据，外部音频渲染的采样率如果不是 SDK 推荐的值时，比如 22050 Hz 和 11025 Hz，声音播放失败。(Android, iOS) ## v6.3.2 (对应 Native v4.3.2) [#v632-对应-native-v432] 该版本于 2024 年 6 月 6 日发布。 ### 升级必看 [#升级必看-82] 该版本修改了播放版权音乐的行为，当调用 [`MusicPlayer`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusicplayer) 中的 [`play`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 方法播放版权音乐媒体文件时，存在以下行为变更 (Android, iOS)： - v6.3.2 以前版本：SDK 默认播放当前音频文件的第一个音轨。 - v6.3.2：SDK 默认播放伴奏。 ### 改进 [#改进-139] 提升了 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_setremotesubscribefallbackoption) 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_setremotesubscribefallbackoption) 动态切换弱网环境下的音视频流回退选项。 ### 问题修复 [#问题修复-142] 该版本修复了以下问题： - App 长时间切后台再返回前台时，远端视频画面卡住或花屏。(iOS) - 部分 iPad 设备上的本地预览画面旋转 90°，不符合预期。(iOS) - 音视频互动过程中偶现视频流畅度不佳。 - 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。 - 首次安装 App 或重启系统后，打开 App 并开启屏幕共享时出现崩溃。(Android) - 接听系统电话时加入频道，挂断电话后，本地音频采集失败，远端用户听不到声音。(Android) - 在部分机型（例如：红米 Note8）上进行互动的过程中接听系统来电并挂断后，本地播放媒体文件无声、听远端无声。(Android) - 远端用户离开频道时偶现崩溃。 - 调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享 PPT 窗口，当 PPT 播放动画画面时，接收端偶现画面闪烁。(Windows) - 在 Windows 7 系统上调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享 WPS PPT 窗口，并设置 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/flutter/class-screencaptureparameters) 的 `enableHighLight` 为 `true` 开启窗口描边，放映该 PPT 后退出放映，之后选择最大化 PPT 窗口，窗口描边没有保留原始窗口大小，不符合预期。(Windows) - 调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享窗口，并设置 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/flutter/class-screencaptureparameters) 的 `windowFocus` 和 `enableHighLight` 为 `true` 以前置指定窗口并开启窗口描边，如果当前该窗口被其他窗口覆盖，无法前置该窗口，不符合预期。(Windows) - 在 Windows 7 设备上共享窗口并对窗口描边时，点击桌面控件导致描边部分闪烁。(Windows) - 调用 播放音乐文件，音乐文件播放结束后偶现无法触发 [`onAudioMixingStateChanged`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)`(audioMixingStateStopped,audioMixingReasonAllLoopsCompleted)` 回调报告音乐文件播放完毕。(iOS) - 调用 [`playEffect`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 播放时长不足 1 秒的音效文件并设置不循环播放（`loopCount` 为 `0`）时，出现无声。(iOS) - 使用媒体播放器播放视频，暂停播放后恢复播放，偶现短暂无声。(iOS) ## v6.3.1 (对应 Native v4.3.1) [#v631-对应-native-v431] 该版本于 2024 年 5 月 9 日发布。 ### 新增特性 [#新增特性-121] #### 隐私清单文件 (iOS) [#隐私清单文件-ios-1] 为满足 Apple 对于 App 发布的安全合规要求，SDK 自该版本起新增隐私清单文件 `PrivacyInfo.xcprivacy`，其中包含 SDK 中需要访问或使用用户数据的 API 调用说明和 SDK 采集的数据类型说明。 :::warning[注意] 如果你需要将集成 v4.3.1 之前的 SDK 版本的 App 发布到苹果应用商店，则需要在 Xcode 工程中手动添加 `PrivacyInfo.xcprivacy` 文件。详见[如何在 App 中增加隐私清单？](/zh-CN/reference/faq/other/ios_privacy_manifest) ::: #### 人像锁定 (iOS, macOS) [#人像锁定-ios-macos-1] 为提升在线会议、秀场、在线教育等场景中的主播演讲效果，该版本新增 [`enableCameraCenterStage`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) 方法开启人像锁定功能。该功能可确保主播无论移动与否，始终位于画面中心，以取得良好的演讲效果。 在开启人像锁定前，建议你先调用 [`isCameraCenterStageSupported`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) 查询当前设备性能是否支持该功能。支持的设备清单可参考 [API 文档](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage)。 #### 摄像头防抖 (iOS) [#摄像头防抖-ios-1] 为改善在移动拍摄、暗光环境拍摄、手持拍摄等场景下的视频画面稳定性，该版本新增摄像头防抖功能。你可以调用 [`setCameraStabilizationMode`](/zh-CN/api-reference/rtc/flutter/video/camera-capture#api_irtcengine_setcamerastabilizationmode) 开启该功能并设置适合的防抖模式，以获得更加稳定、清晰的视频画面。 #### 摄像头广角和超广角 (Android, iOS) [#摄像头广角和超广角-android-ios-1] 为了让用户捕捉到更宽阔的视野和更完整的画面内容，该版本新增了对广角和超广角摄像头的支持。你可以先调用 [`queryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 查询设备支持的焦距能力，然后调用 [`setCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 并将 `cameraFocalLengthType` 设置为支持的焦距类型，包括广角、超广角等。 #### 摄像头多路采集 (Android) [#摄像头多路采集-android-1] 该版本针对 Android 摄像头采集新增以下功能： 1. 支持第三个和第四个摄像头视频流的采集和发布。 - [`VideoSourceType`](/zh-CN/api-reference/rtc/flutter/enum-videosourcetype) 中的 `videoSourceCameraThird`(11) 和 `videoSourceCameraFourth`(12) 枚举新增对 Android 的支持，分别用于指定视频源为第三个和第四个摄像头。此项改动允许你在调用 [`startCameraCapture`](/zh-CN/api-reference/rtc/flutter/video/camera-capture#api_irtcengine_startcameracapture) 开启摄像头采集时，指定最多 4 路摄像头采集的视频流。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中的 `publishThirdCameraTrack` 和 `publishFourthCameraTrack` 成员新增对 Android 的支持。调用 [`joinChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 加入频道时，将这两个成员参数设置为 `true` 即可在频道内发布第三个和第四个摄像头采集的视频流。 2. 支持通过摄像头 ID 指定摄像头。 在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/flutter/class-cameracapturerconfiguration) 中新增 `cameraId` 成员。对于多摄像头的设备，`cameraDirection` 无法识别或访问全部可用摄像头。这种情况下，你通过系统 API 获取摄像头 ID，再调用 [`startCameraCapture`](/zh-CN/api-reference/rtc/flutter/video/camera-capture#api_irtcengine_startcameracapture) 并传入 `cameraId` 指定摄像头。 #### 数据流加密 [#数据流加密-7] 该版本在 [`EncryptionConfig`](/zh-CN/api-reference/rtc/flutter/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` 成员用于启用数据流加密。你可以在调用 [`enableEncryption`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_enableencryption) 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 `encryptionErrorDatastreamDecryptionFailure` 和 `encryptionErrorDatastreamEncryptionFailure` 枚举得知。 #### 视频小流自适应配置 [#视频小流自适应配置-6] 该版本新增视频小流的自适应配置功能，当你调用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_setdualstreammode2) 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示： - 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。 - 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。 #### 其他 [#其他-31] - 新增 [`enableEncryptionEx`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengineex_enableencryptionex) 方法，用于多频道场景下开启媒体流或数据流加密。 - 新增 [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) 方法，用于设置音乐文件的播放速度。 - 新增 [`getCallIdEx`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengineex_getcallidex) 方法，用于多频道场景下获取通话 ID。 ### 改进 [#改进-140] #### 屏幕共享游戏场景优化 (Windows) [#屏幕共享游戏场景优化-windows-2] 该版本对屏幕共享的游戏场景进行了专项优化，在超高清（4K, 60 fps）游戏场景下提升了性能表现，增强了窗口采集的稳定性，为游戏玩家带来更清晰、流畅、稳定的游戏体验。 #### 获取音频设备类型 (macOS) [#获取音频设备类型-macos-2] 该版本在 [`AudioDeviceInfo`](/zh-CN/api-reference/rtc/flutter/class-audiodeviceinfo) 中新增 `deviceTypeName` 成员，用于获取音频设备的类型，如 built-in、USB、HDMI 等。 #### 虚拟背景算法优化 [#虚拟背景算法优化-13] 为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法： - 支持识别任意纯色背景，不再局限于绿幕。 - 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。 - 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。 #### 降低耳返的 CPU 消耗 [#降低耳返的-cpu-消耗-6] 该版本在 [`EarMonitoringFilterType`](/zh-CN/api-reference/rtc/flutter/enum-earmonitoringfiltertype) 中新增 `earMonitoringFilterReusePostProcessingFilter`(`1 << 15`) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。 #### 其他改进 [#其他改进-58] 该版本还进行了如下改进： - 优化了非屏幕共享场景的视频编解码策略，节省系统性能开销。(iOS, macOS, Windows) - 提升了本地合图功能的性能和稳定性，并降低了该功能对 CPU 的占用率。(Android) - 提升了原始视频帧观测器在处理视频时的稳定性。(iOS) - 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。 - 在 [`AudioEffectPreset`](/zh-CN/api-reference/rtc/flutter/enum-audioeffectpreset) 中新增 `roomAcousticsChorus`（合唱音效），可使人声在合唱场景下更具空间立体感。 - 在 [`RemoteAudioStats`](/zh-CN/api-reference/rtc/flutter/class-remoteaudiostats) 中新增 `e2eDelay`，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。 ### 问题修复 [#问题修复-143] 该版本修复了以下问题： - 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。 - 屏幕共享场景中，App 调用 [`enableLoopbackRecording`](/zh-CN/api-reference/rtc/flutter/audio/audio-capture#api_irtcengine_enableloopbackrecording) 开启声卡采集功能采集共享屏幕的音频，本地用户手动禁用本地音频采集设备后，声卡采集的音频发送失败，远端用户听不见共享屏幕的声音。(Windows) - 主播使用部分型号设备在扬声器下进行音视频互动，之后切换 App 进程到后台再切回前台，偶现本地音频采集失败，远端用户听不到主播的声音。(Android) - 在音视频互动过程中，本地用户调用 设置系统默认播放设备为扬声器后，听远端无声。(Windows) - 在 Android 8.0 系统的设备上，启用屏幕共享功能时 App 偶现崩溃。(Android) - 在共享 Excel 文档窗口时，偶现远端用户看到的画面出现绿屏。(Windows) - 使用摄像头采集本地视频场景下，在 App 切后台时已调用 [`disableVideo`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_disablevideo) 或 [`stopPreview`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_stoppreview2) 关闭视频采集，但将 App 再切回前台时，摄像头采集被打开，不符合预期。(Android) - 当发送端用户的网络环境恶化（例如弱网）时，接收端偶现视频流畅度降低、卡顿增加。 ### API 变更 [#api-变更-73] #### 新增 [#新增-67] - [`enableCameraCenterStage`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) (iOS, macOS) - [`isCameraCenterStageSupported`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) (iOS, macOS) - [`setCameraStabilizationMode`](/zh-CN/api-reference/rtc/flutter/video/camera-capture#api_irtcengine_setcamerastabilizationmode) (iOS) - [`CameraStabilizationMode`](/zh-CN/api-reference/rtc/flutter/enum-camerastabilizationmode) (iOS) - [`EncryptionConfig`](/zh-CN/api-reference/rtc/flutter/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` - [`EncryptionErrorType`](/zh-CN/api-reference/rtc/flutter/enum-encryptionerrortype) 中新增如下枚举： - `encryptionErrorDatastreamDecryptionFailure` - `encryptionErrorDatastreamEncryptionFailure` - [`AudioDeviceInfo`](/zh-CN/api-reference/rtc/flutter/class-audiodeviceinfo) 中新增 `deviceTypeName` (macOS) - [`RemoteAudioStats`](/zh-CN/api-reference/rtc/flutter/class-remoteaudiostats) 新增 `e2eDelay` - [`ErrorCodeType`](/zh-CN/api-reference/rtc/flutter/enum-errorcodetype) 新增 `errDatastreamDecryptionFailed` - [`AudioEffectPreset`](/zh-CN/api-reference/rtc/flutter/enum-audioeffectpreset) 新增 `roomAcousticsChorus` - [`getCallIdEx`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengineex_getcallidex) - [`enableEncryptionEx`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengineex_enableencryptionex) - [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) - [`queryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) (Android, iOS) - [`FocalLengthInfo`](/zh-CN/api-reference/rtc/flutter/class-focallengthinfo) (Android, iOS) - [`CameraFocalLengthType`](/zh-CN/api-reference/rtc/flutter/enum-camerafocallengthtype) (Android, iOS) - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/flutter/class-cameracapturerconfiguration) 新增成员 `cameraFocalLengthType` (Android, iOS) - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/flutter/class-cameracapturerconfiguration) 新增成员 `cameraId` (Android) - [`EarMonitoringFilterType`](/zh-CN/api-reference/rtc/flutter/enum-earmonitoringfiltertype) 新增枚举 `earMonitoringFilterBuiltInAudioFilters`(`1 << 15`) ## v6.3.0 (对应 Native v4.3.0) [#v630-对应-native-v430] 该版本于 2024 年 2 月 28 日发布。 ### 升级必看 [#升级必看-83] 该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 回调中的参数改名 [#回调中的参数改名-6] 为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。 | 回调 | 原有参数名 | 现有参数名 | | --- | --- | --- | | [`onLocalAudioStateChanged`](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) | `error` | `reason` | | [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) | `error` | `reason` | | `onDirectCdnStreamingStateChanged` | `error` | `reason` | | [`onMusicChartsResult`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) | `errorCode` | `reason` | | [`onPreLoadEvent`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) | [release-notes-flutter-html-1-5-1 details](#table-slot-release-notes-flutter-html-1-5-1) | [release-notes-flutter-html-1-5-2 details](#table-slot-release-notes-flutter-html-1-5-2) | | [`onMusicCollectionResult`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) | `errorCode` | `reason` | | [`onLyricResult`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) | `errorCode` | `reason` | | [`onSongSimpleInfoResult`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) | `errorCode` | `reason` | | [`onPlayerSourceStateChanged`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) | `ec` | `reason` | | [`onRtmpStreamingStateChanged`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/media-push#callback_irtcengineeventhandler_onrtmpstreamingstatechanged) | `errCode` | `reason` | **release-notes-flutter-html-1-5-1 details** - `status` - `state` **release-notes-flutter-html-1-5-2 details** - `errorCode` - `reason` | 原有枚举类 | 现有枚举类 | | -------------------------- | ----------------------------- | | `LocalAudioStreamError` | [`LocalAudioStreamReason`](/zh-CN/api-reference/rtc/flutter/enum-localaudiostreamreason) | | `LocalVideoStreamError` | [`LocalVideoStreamReason`](/zh-CN/api-reference/rtc/flutter/enum-localvideostreamreason) | | `DirectCdnStreamingError` | `DirectCdnStreamingReason` | | `MediaPlayerError` | [`MediaPlayerReason`](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason) | | `RtmpStreamPublishErrorType` | [`RtmpStreamPublishReason`](/zh-CN/api-reference/rtc/flutter/enum-rtmpstreampublishreason) | | `MusicContentCenterStatusCode` | [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/flutter/enum-musiccontentcenterstatereason) | :::info[信息] 有关具体枚举的改名详见 [API 变更](#api-changes)。 ::: #### 跨频道媒体流转发 [#跨频道媒体流转发-12] 为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项： | 已删除的方法和回调 | 替代的方法和回调 | | --- | --- | | [release-notes-flutter-html-2-1-0 details](#table-slot-release-notes-flutter-html-2-1-0) | [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) | | [release-notes-flutter-html-2-2-0 details](#table-slot-release-notes-flutter-html-2-2-0) | [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) | | `onChannelMediaRelayEvent` | [`onChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) | **release-notes-flutter-html-2-1-0 details** - `startChannelMediaRelay` - `updateChannelMediaRelay` **release-notes-flutter-html-2-2-0 details** - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` #### 音频路由 [#音频路由-3] 该版本起，[`AudioRoute`](/zh-CN/api-reference/rtc/flutter/enum-audioroute) 中的`routeBluetooth` 更名为 `routeHeadsetbluetooth`，表示音频路由为使用 HFP 协议的蓝牙设备，新增 `routeBluetoothSpeaker`(10) 表示音频路由为使用 A2DP 协议的蓝牙设备。 #### 本地视频状态改变原因 [#本地视频状态改变原因-6] 该版本对 [`LocalVideoStreamReason`](/zh-CN/api-reference/rtc/flutter/enum-localvideostreamreason) 枚举类中的枚举进行了如下修改： - `localVideoStreamReasonScreenCapturePaused` （原 `localVideoStreamErrorScreenCapturePaused`）的值从 23 变更为 28。 (Windows) - `localVideoStreamReasonScreenCaptureResumed` （原 `localVideoStreamErrorScreenCaptureResumed`）的值从 24 变更为 29。 (Windows) - `localVideoStreamErrorEncodeFailure` 的枚举名变更为 `localVideoStreamReasonCodecNotSupport`。 #### 日志加密行为变更 [#日志加密行为变更-6] 出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案： - 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。 - 如有其他特殊需求，请[联系技术支持](https://ticket.shengwang.cn/)并附上对应的加密日志。 #### 声卡采集（Windows，macOS） [#声卡采集windowsmacos] - 在 v6.3.0 之前，当你调用 [`disableAudio`](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#api_irtcengine_disableaudio) 关闭整个音频模块后，声卡采集功能不会被关闭。 - 从 v6.3.0 起，当你调用 [`disableAudio`](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#api_irtcengine_disableaudio) 关闭音频模块后，声卡采集功能也会被关闭，如果你需要再次启用声卡采集功能，需要在调用 [`enableAudio`](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#api_irtcengine_enableaudio) 启用音频模块后再次调用 [`enableLoopbackRecording`](/zh-CN/api-reference/rtc/flutter/audio/audio-capture#api_irtcengine_enableloopbackrecording)。 ### 新增特性 [#新增特性-122] #### 接收端自定义合图布局 (Android, iOS) [#接收端自定义合图布局-android-ios-1] 为支持接收端自定义多路合图流的布局，该版本新增了 [`onTranscodedStreamLayoutInfo`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo) 回调。当接收端收到合图服务器发送的频道内合图视频流时，该回调会被触发，上报合图视频流的布局信息、以及合图流中每一路子视频流的布局信息。接收端可以在调用 [`setupRemoteVideo`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_setupremotevideo) 方法时，为合图视频流中的子视频流（通过 `subviewUid` 区分）设置单独的 `view` 进行渲染，从而达到自定义视频布局的效果。 当合图视频流中的子视频流布局发生变化时，该回调也会被触发，实时上报最新的布局信息。 通过该特性，接收端可以灵活调整本地的视图布局。当在多人视频场景下应用时，接收端只需接收并解码一路合图视频流，可以有效降低接收端解码多路视频时的 CPU 占用率和网络带宽。 :::info[信息] 关于该特性在多主播场景下的最佳实践，详见[多主播场景下的视频体验优化](/zh-CN/realtime-media/rtc/build/video/custom-layout)。 ::: #### 多视图本地预览 [#多视图本地预览-6] 该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下： 1. 调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第一个视图：在 [`VideoCanvas`](/zh-CN/api-reference/rtc/flutter/class-videocanvas) 中设置 `position` 参数为 `positionPostCapturerOrigin`（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。 2. 调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_setuplocalvideo) 设置第二个视图：在 [`VideoCanvas`](/zh-CN/api-reference/rtc/flutter/class-videocanvas) 中设置 `position` 参数为 `positionPostCapturer`，此处观测到的视频具备视频前处理的效果。 3. 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。 #### 查询设备评分等级 [#查询设备评分等级-6] 该版本新增 [`queryDeviceScore`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_querydevicescore) 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请[联系技术支持](https://ticket.shengwang.cn/)。 #### 本地播放及发布至远端的音轨控制 [#本地播放及发布至远端的音轨控制-6] 该版本新增 [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 [`openWithMediaSource`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并通过 [`MediaSource`](/zh-CN/api-reference/rtc/flutter/class-mediasource) 中新增的 `enableMultiAudioTrack` 成员来开启音轨控制。 #### 其他 [#其他-32] 该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。 - [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_setremotesubscribefallbackoption)：设置弱网环境下订阅的音视频流回退选项。 - [`onRemoteSubscribeFallbackToAudioOnly`](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly)：订阅流已回退为音频流或恢复为音视频流回调。 - [`setPlaybackDeviceVolume`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_setplaybackdevicevolume) (Windows)：设置播放设备音量。 - [`getRecordingDeviceVolume`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_getrecordingdevicevolume) (Windows)：获取音频采集设备音量。 - [`setPlayerOptionInInt`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption) 和 [`setPlayerOptionInString`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption2)：设置媒体播放器选项，用于提供技术预览或特别定制功能。 - [`enableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/flutter/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback)：设置是否在本地播放外部音频源。 ### 改进 [#改进-141] #### SDK 任务处理调度优化 [#sdk-任务处理调度优化-6] 该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面： - 远端及本地的首帧出图与出声速度均有明显提升。 - API 的调用耗时和响应耗时缩短 50% 以上。 - SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。 - SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。 #### 耳返音量提升 [#耳返音量提升-6] 该版本为用户提供更灵活的耳返音频调整选项，支持调用 [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/flutter/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) 将耳返音量设置为原始音量的 4 倍。 #### 空间音频易用性提升 [#空间音频易用性提升-6] - 该版本优化了 [`setZones`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 方法的设计，支持将 `zones` 参数设置为 `NULL`，表示清除所有隔声区域。 - 自该版本起，在调用 [`LocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine) 中的方法之前，无需先取消订阅频道内所有远端用户的音频流。 #### 其他改进 [#其他改进-59] 该版本还进行了如下改进： - 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。 - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增 `localVideoStreamReasonScreenCaptureAutoFallback` 枚举，表示屏幕共享过程中发生意外错误（可能由于窗口阻塞失败），导致性能下降，但屏幕共享过程本身没有受到影响。(Windows) - 新增 [`onPlayerCacheStats`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) 回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。 - 新增 [`onPlayerPlaybackStats`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) 回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过 [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/flutter/class-playerplaybackstats) 来获取当前音、视频的码率等信息。 - [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/flutter/enum-musiccontentcenterstatereason) 中新增状态码 `kMusicContentCenterReasonHttpInternalError` 表示 HTTP 内部发生错误，请稍后重试。(Android, iOS) - 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_setlocalaccesspoint) 解析域名时的稳定性。 - 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。 - [`LocalAudioStats`](/zh-CN/api-reference/rtc/flutter/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。 ### 问题修复 [#问题修复-144] 该版本修复了以下问题： - 当同时共享两路屏幕共享视频流时，[`onLocalVideoStats`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onlocalvideostats) 回调上报的 `captureFrameRate` 为 0，不符合预期。 - 在指定屏幕区域共享时，鼠标在共享区域内的坐标不准确。当鼠标位于共享区域的边界附近时，可能导致共享的画面中看不到鼠标。(Windows) - 使用 3.5 mm 耳机多次插拔设备后，SDK 未能检测到音频路由的变化。(Windows) ### API 变更 [#api-变更-74] #### 新增 [#新增-68] - [`onTranscodedStreamLayoutInfo`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo) (Android, iOS) - [`VideoLayout`](/zh-CN/api-reference/rtc/flutter/class-videolayout) (Android, iOS) - [`VideoCanvas`](/zh-CN/api-reference/rtc/flutter/class-videocanvas) 新增 `subviewUid` 和 `uid` 成员 - [`enableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/flutter/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback) - [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) - [`onPlayerCacheStats`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) - [`onPlayerPlaybackStats`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) - [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/flutter/class-playerplaybackstats) - [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/flutter/enum-musiccontentcenterstatereason) 中新增 `kMusicContentCenterReasonHttpInternalError` (Android,iOS) - [`LocalAudioStats`](/zh-CN/api-reference/rtc/flutter/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员 - [`queryDeviceScore`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_querydevicescore) - [`MediaSourceType`](/zh-CN/api-reference/rtc/flutter/enum-mediasourcetype) 中新增 `customVideoSource` 枚举 - [`AudioRoute`](/zh-CN/api-reference/rtc/flutter/enum-audioroute) 中新增 `routeBluetoothSpeaker` 枚举 #### 修改 [#修改-19] - `routeBluetooth` 枚举名变更为 `routeHeadsetbluetooth` - 以下枚举名中的 `Error` 字段全部修改为 `Reason`： - `localAudioStreamErrorOk` - `localAudioStreamErrorFailure` - `localAudioStreamErrorDeviceNoPermission` - `localAudioStreamErrorDeviceBusy` - `localAudioStreamErrorRecordFailure` - `localAudioStreamErrorEncodeFailure` - `localAudioStreamErrorRecordInvalidId` (Windows) - `localAudioStreamErrorPlayoutInvalidId` (Windows) - `localVideoStreamErrorOk` - `localVideoStreamErrorFailure` - `localVideoStreamErrorDeviceNoPermission` - `localVideoStreamErrorDeviceBusy` - `localVideoStreamErrorCaptureFailure` - `localVideoStreamErrorCodecNotSupport` - `localVideoStreamErrorCaptureInbackground` (iOS) - `localVideoStreamErrorCaptureMultipleForegroundApps` (iOS) - `localVideoStreamErrorDeviceNotFound` - `localVideoStreamErrorDeviceDisconnected` - `localVideoStreamErrorDeviceInvalidId` - `localVideoStreamErrorScreenCaptureWindowMinimized` - `localVideoStreamErrorScreenCaptureWindowClosed` - `localVideoStreamErrorScreenCaptureWindowOccluded` - `localVideoStreamErrorScreenCaptureNoPermission` (Windows) - `localVideoStreamErrorScreenCapturePaused` (Windows) - `localVideoStreamErrorScreenCaptureResumed` (Windows) - `localVideoStreamErrorScreenCaptureWindowHidden` (Windows) - `localVideoStreamErrorScreenCaptureWindowRecoverFromHidden` (Windows) - `localVideoStreamErrorScreenCaptureWindowRecoverFromMinimized` (Windows) - `localVideoStreamErrorScreenCaptureFailure` (Windows) - `localVideoStreamErrorDeviceSystemPressure` (Windows) - `directCdnStreamingErrorOk` - `directCdnStreamingErrorFailed` - `directCdnStreamingErrorAudioPublication` - `directCdnStreamingErrorVideoPublication` - `directCdnStreamingErrorNetConnect` - `directCdnStreamingErrorBadName` - `playerErrorNone` - `playerErrorInvalidArguments` - `playerErrorInternal` - `playerErrorNoResource` - `playerErrorInvalidMediaSource` - `playerErrorUnknownStreamType` - `playerErrorObjNotInitialized` - `playerErrorCodecNotSupported` - `playerErrorVideoRenderFailed` - `playerErrorInvalidState` - `playerErrorUrlNotFound` - `playerErrorInvalidConnectionState` - `playerErrorSrcBufferUnderflow` - `playerErrorInterrupted` - `playerErrorNotSupported` - `playerErrorTokenExpired` - `playerErrorUnknown` - `rtmpStreamPublishErrorOk` - `rtmpStreamPublishErrorInvalidArgument` - `rtmpStreamPublishErrorEncryptedStreamNotAllowed` - `rtmpStreamPublishErrorConnectionTimeout` - `rtmpStreamPublishErrorInternalServerError` - `rtmpStreamPublishErrorRtmpServerError` - `rtmpStreamPublishErrorTooOften` - `rtmpStreamPublishErrorReachLimit` - `rtmpStreamPublishErrorNotAuthorized` - `rtmpStreamPublishErrorStreamNotFound` - `rtmpStreamPublishErrorFormatNotSupported` - `rtmpStreamPublishErrorNotBroadcaster` - `rtmpStreamPublishErrorTranscodingNoMixStream` - `rtmpStreamPublishErrorNetDown` - `rtmpStreamPublishErrorInvalidPrivilege` - `rtmpStreamUnpublishErrorOk` - `MusicContentCenterStatusCode` 修改为 [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/flutter/enum-musiccontentcenterstatereason)，其中的枚举名的 `StatusErr` 字段全部修改为 `Reason`：(Android, iOS) - `kMusicContentCenterStatusErrGateway` - `kMusicContentCenterStatusErrPermissionAndResource` - `kMusicContentCenterStatusErrInternalDataParse` - `kMusicContentCenterStatusErrMusicLoading` - `kMusicContentCenterStatusErrMusicDecryption` - `kMusicContentCenterStatusOk` 修改为 `kMusicContentCenterReasonOk` (Android, iOS) - `kMusicContentCenterStatusErr` 修改为 `kMusicContentCenterReasonError` (Android, iOS) #### 删除 [#删除-29] - `startChannelMediaRelay` - `updateChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - `onChannelMediaRelayEvent` - `ChannelMediaRelayEvent` ## v6.2.6 (对应 Native v4.2.6) [#v626-对应-native-v426] 该版本于 2023 年 11 月 21 日发布。 ### 问题修复 [#问题修复-145] 该版本修复了在使用 Android 14 系统版本时可能出现的问题： - 在屏幕共享过程中切换横竖屏模式导致当前屏幕共享进程中断，需要在弹出窗口中点击确认录制屏幕才可重新开始屏幕共享。(Android) - 在集成 SDK 时，如果将 Android `targetSdkVersion` 设置为 34，导致屏幕共享不可用甚至 App 崩溃。(Android) - 先调用 [`startScreenCapture`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapture) 但不共享视频（设置 `captureVideo` 为 `false`）、后调用 [`updateScreenCaptureParameters`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_updatescreencaptureparameters) 共享视频（设置 `captureVideo` 为 `true`）时，接收端看到的屏幕共享画面冻结。(Android) - 采用横屏模式进行屏幕共享时，观众端看到的共享画面被拆分成两部分：一侧的画面被压缩；另一侧为黑屏。(Android) 该版本还修复了以下问题： - 使用 iOS 16 版本或以上设备在加入频道前连接了蓝牙耳机，在加入频道后的音频路由不符合预期：音频从扬声器播放、而非蓝牙耳机。(iOS) - 在直播场景下，观众端看到的画面偶现变形。(Android) - 在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。 ## v6.2.4 (对应 Native v4.2.3) [#v624-对应-native-v423] 该版本于 2023 年 10 月 24 日发布。 ### 问题修复 [#问题修复-146] 该版本修复了如下问题： `AgoraRtcWrapper` 中的 `CFBundleShortVersionString` 版本号错误，导致 App 无法被提交至 App Store。(iOS, macOS) ## v6.2.3 (对应 Native v4.2.3) [#v623-对应-native-v423] 该版本于 2023 年 10 月 13 日发布。 ### 升级必看 [#升级必看-84] #### 兼容性变更 (Android) [#兼容性变更-android] 该版本优化了 SDK 采集和自定义视频采集场景下 Texture Buffer 的管理方式，有效消除丢帧和崩溃隐患。自该版本起，TextureBuffer 类型的纹理格式不再包括 OES 格式，仅为 RGB 格式。你需要在处理视频数据时增加对 I420、RGB 纹理格式的适配。 ### 新增特性 [#新增特性-123] #### 本地截图上传更新 [#本地截图上传更新-6] 为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动： - [`ContentInspectType`](/zh-CN/api-reference/rtc/flutter/enum-contentinspecttype) 中新增 `contentInspectImageModeration` 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。 - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/flutter/class-contentinspectconfig) 中新增的 `serverConfig` 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请[联系技术支持](https://ticket.shengwang.cn/)。 此外，该版本还新增了 [`enableContentInspectEx`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) 方法，支持同时对多条视频流截图并上传。 #### 支持 ID3D11Texture2D 渲染 (Windows) [#支持-id3d11texture2d-渲染-windows-1] 自该版本起，SDK 支持 ID3D11Texture2D 类型的视频格式，提升了游戏场景中视频帧的渲染效果。你可以在调用 [`pushVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe) 方法将外部原始视频帧推送到 SDK 时，设置 `format` 为 `VIDEO_TEXTURE_ID3D11TEXTURE2D`；并通过设置 `textureSliceIndex` 属性，来确定要使用的 ID3D11Texture2D 纹理对象。 #### 本地视频状态错误码更新 (Windows, macOS) [#本地视频状态错误码更新-windows-macos-1] 为了帮助用户在屏幕共享场景下了解本地视频出错的准确原因，[`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中新增了如下几组枚举： - `localVideoStreamErrorScreenCapturePaused`(23)：屏幕采集已暂停。当前屏幕可能已切换到安全桌面，例如 UAC 对话框或者 Winlogon 桌面。 - `localVideoStreamErrorScreenCaptureResumed`(24)：屏幕采集已从暂停状态中恢复。 - `localVideoStreamErrorScreenCaptureWindowHidden`(25)：当前屏幕采集的窗口处于隐藏状态，并且在当前屏幕上不可见。 - `localVideoStreamErrorScreenCaptureWindowRecoverFromHidden`(26)：进行屏幕采集的窗口已经从隐藏状态中恢复。 - `localVideoStreamErrorScreenCaptureWindowRecoverFromMinimized`(27)：进行屏幕采集的窗口已经从最小化状态中恢复。 #### 进阶功能查询 [#进阶功能查询-6] 该版本新增了 [`isFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_isfeatureavailableondevice) 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。 在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。 此外，自该版本起，调用 [`enableVirtualBackground`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 和 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 `-4: errNotSupported` 表示该设备不支持开启该功能。 ### 改进 [#改进-142] #### 优化虚拟背景内存占用 [#优化虚拟背景内存占用-6] 该版本升级了虚拟背景算法，降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。 #### 屏幕共享场景优化 [#屏幕共享场景优化-4] 该版本优化了在超高清（4K，60 fps）游戏共享场景下的性能和编码效率，有效降低了屏幕共享时系统资源占用率。(Windows) #### 其他改进 [#其他改进-60] 该版本还优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。 ### 问题修复 [#问题修复-147] 该版本修复了以下问题： - 在屏幕共享场景下偶现崩溃、掉帧。(Windows) - 加入频道偶现的崩溃。(macOS) - 本地系统时间不正确时，偶现加入频道失败。 - 调用 [`playEffect`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3) 使用相同的 `soundId` 播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 - 主播调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_irtcengine_startaudiomixing2) 播放音乐文件时，偶现主播本地无法听见音乐，远端用户可以正常听见。(Android) - 合唱场景下，调用 [`preload`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_preload2)加载音乐，偶现加载失败。(Android, iOS) - 在特定机型上开启 AI 降噪偶现崩溃。(Android) - 当本地系统时间不准确时，歌曲榜单加载失败。(Android, iOS) - 调用一次 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 获取视频截图会收到多次 [`onSnapshotTaken`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 视频截图结果回调。 - 在仅调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengineex_joinchannelex) 加入的频道中，调用 [`setEnableSpeakerphone`](/zh-CN/api-reference/rtc/flutter/device-management/audio-route#api_irtcengine_setenablespeakerphone) 无法将音频路由从扬声器切换至听筒。(Android) ### API 变更 [#api-变更-75] #### 新增 [#新增-69] - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 中新增如下枚举 (Windows, macOS)： - `localVideoStreamErrorScreenCapturePaused` - `localVideoStreamErrorScreenCaptureResumed` - `localVideoStreamErrorScreenCaptureWindowHidden` - `localVideoStreamErrorScreenCaptureWindowRecoverFromHidden` - `localVideoStreamErrorScreenCaptureWindowRecoverFromMinimized` - [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/flutter/class-externalvideoframe) 中新增 `textureSliceIndex` 成员 (Windows) - [`VideoPixelFormat`](/zh-CN/api-reference/rtc/flutter/enum-videopixelformat) 中新增 `videoTextureId3d11texture2d` 枚举 (Windows) - [`enableContentInspectEx`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) - [`ContentInspectType`](/zh-CN/api-reference/rtc/flutter/enum-contentinspecttype) 新增 `contentInspectImageModeration` - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/flutter/class-contentinspectconfig) 中新增 `serverConfig` 可选参数 - [`isFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_isfeatureavailableondevice) - [`FeatureType`](/zh-CN/api-reference/rtc/flutter/enum-featuretype) ## v6.2.2 (对应 Native v4.2.2) [#v622-对应-native-v422] 该版本于 2023 年 8 月 1 日发布。 ### 升级必看 [#升级必看-85] 该版本删除了 [`MusicContentCenter`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusiccontentcenter) 类下的 [`preload`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_preload2) 方法中的 `jsonOption` 参数，请在升级到该版本后更新 App 代码。 ### 新增特性 [#新增特性-124] #### 通配 Token [#通配-token-6] 该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 :::warning[注意] 声网 4.x RTC SDK 均支持使用通配 Token。 ::: #### 预加载频道 [#预加载频道-7] 该版本新增 [`preloadChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_preloadchannel) 和 [`preloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_preloadchannelwithuseraccount) 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。 在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 #### 自定义视频画布背景颜色 [#自定义视频画布背景颜色-6] 该版本在 [`VideoCanvas`](/zh-CN/api-reference/rtc/flutter/class-videocanvas) 中增加了 `backgroundColor` 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。 #### 发布多源采集的视频流 (Windows, macOS) [#发布多源采集的视频流-windows-macos-1] 该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中新增下列成员，支持你发布第三个、第四个摄像头和屏幕采集到的视频流： - `publishThirdCameraTrack`：发布第三个摄像头采集的视频。 - `publishFourthCameraTrack`：发布第四个摄像头采集的视频。 - `publishThirdScreenTrack`：发布第三个屏幕采集的视频。 - `publishFourthScreenTrack`：发布第四个屏幕采集的视频。 :::warning[注意] 目前 SDK 支持在同一时间、同一 `RtcConnection` 中发布多路音频流、一路视频流。 ::: #### 支持仅播放副歌片段 (Android, iOS) [#支持仅播放副歌片段-android-ios-1] 该版本新增 [`getInternalSongCode`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_getinternalsongcode) 方法，如果你仅需要播放某一音乐资源的副歌片段，在播放前你需要调用该方法来为该副歌片段创建一个内部歌曲编号，作为该资源的唯一标识。你可以查看[在线 K 歌房文档](/zh-CN/solutions/online-ktv)了解更多 K 歌场景方案。 ### 改进 [#改进-143] #### 摄像头采集效果提升 (Android, iOS) [#摄像头采集效果提升-android-ios-1] 该版本从以下几个方面提升了摄像头采集效果： 1. 支持摄像头采集曝光调节 新增 [`isCameraExposureSupported`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_iscameraexposuresupported) 和 [`setCameraExposureFactor`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_setcameraexposurefactor) 方法，用于查询当前设备是否支持曝光调节和设置摄像头的曝光增益。 2. 优化默认摄像头选择 (iOS) 自该版本起，SDK 的默认摄像头选择对齐 iOS 系统相机行为。如果设备拥有多个后置摄像头，则在视频采集时可以获得更好的拍摄视野、变焦能力、低光性能和深度感应，从而提高视频采集的质量。 #### 虚拟背景算法升级 [#虚拟背景算法升级-6] 该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。 #### 跨频道连麦优化 [#跨频道连麦优化-6] 该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 时，你可以指定最多 6 个目标频道。 #### 视频编解码查询能力增强 [#视频编解码查询能力增强-6] 为提升设备编解码能力查询功能，该版本在 [`CodecCapInfo`](/zh-CN/api-reference/rtc/flutter/class-codeccapinfo) 中新增 `codecLevels` 成员。当成功调用 [`queryCodecCapability`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_querycodeccapability) 后，可通过 `codecLevels` 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。 #### 其他改进 [#其他改进-61] - 为了提升多种音频路由之间的切换体验，该版本新增了 [`setRouteInCommunicationMode`](/zh-CN/api-reference/rtc/flutter/device-management/audio-route#api_irtcengine_setrouteincommunicationmode) 方法，用于在通话音量模式 ([`MODE_IN_COMMUNICATION`](https://developer.android.google.cn/reference/kotlin/android/media/AudioManager?hl=en#mode_in_communication)) 下，将音频路由从蓝牙耳机切换为听筒、有线耳机或扬声器。 (Android) - 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。 - 为帮助用户了解更多类型的远端视频状态改变的原因，[`onRemoteVideoStateChanged`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调中新增了 `remoteVideoStateReasonCodecNotSupport` 枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。 - 版权音乐新增 [`getSongSimpleInfo`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_getsongsimpleinfo) 方法，可用于获取某一指定歌曲的详细信息，你可以通过触发的 [`onSongSimpleInfoResult`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) 回调来获取歌曲信息。 (Android, iOS) ### 问题修复 [#问题修复-148] 该版本修复了以下问题： - 加入频道后，偶现本地用户听自己及远端的声音时出现杂音。 (macOS) - 网络异常导致频道连接断开后，频道连接恢复较慢。 - 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。 - 自采集场景下，[`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions)、[`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)、[`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 和 [`setColorEnhanceOptions`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions) 无法自动加载插件。 - 多设备音频录制场景下，反复插拔或开启/禁用音频录制设备后，偶现调用 [`startRecordingDeviceTest`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_startrecordingdevicetest) 进行音频采集设备测试时听不到声音。 (Windows) ### API 变更 [#api-变更-76] #### 新增 [#新增-70] - [`setCameraExposureFactor`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_setcameraexposurefactor) (Android, iOS) - [`isCameraExposureSupported`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_iscameraexposuresupported) (Android, iOS) - [`preloadChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_preloadchannel) - [`preloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_preloadchannelwithuseraccount) - [`updatePreloadChannelToken`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_updatepreloadchanneltoken) - [`getSongSimpleInfo`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_getsongsimpleinfo) (Android, iOS) - [`onSongSimpleInfoResult`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) (Android, iOS) - [`getInternalSongCode`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_getinternalsongcode) (Android, iOS) - [`onLyricResult`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 中增加 `songCode` (Android, iOS) - [`onPreLoadEvent`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 中增加 `requestId` (Android, iOS) - [`setRouteInCommunicationMode`](/zh-CN/api-reference/rtc/flutter/device-management/audio-route#api_irtcengine_setrouteincommunicationmode) (Android) - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中增加下列成员： - `publishThirdCameraTrack` (Windows, macOS) - `publishFourthCameraTrack` (Windows, macOS) - `publishThirdScreenTrack` (Windows, macOS) - `publishFourthScreenTrack` (Windows, macOS) - [`CodecCapLevels`](/zh-CN/api-reference/rtc/flutter/class-codeccaplevels) - [`VideoCodecCapabilityLevel`](/zh-CN/api-reference/rtc/flutter/enum-videocodeccapabilitylevel) - [`VideoCanvas`](/zh-CN/api-reference/rtc/flutter/class-videocanvas) 中增加 `backgroundColor` 成员 - [`CodecCapInfo`](/zh-CN/api-reference/rtc/flutter/class-codeccapinfo) 中增加 `codecLevels` 成员 - [`RemoteVideoStateReason`](/zh-CN/api-reference/rtc/flutter/enum-remotevideostatereason) 中增加 `remoteVideoStateReasonCodecNotSupport` 枚举 #### 删除 [#删除-30] - [`MusicContentCenter`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusiccontentcenter) 类下的 [`preload`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_preload2) 方法中的 `jsonOption` 参数 (Android, iOS) ## v6.2.1 (对应 Native v4.2.1) [#v621-对应-native-v421] 该版本于 2023 年 6 月 30 日发布。 ### 改进 [#改进-144] 该版本改进了网络传输策略，提升了音视频交互的流畅度。 ### 问题修复 [#问题修复-149] 该版本修复了以下问题： - SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。 - 发送端调用 [`setAINSMode`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。 - 发送端启用屏幕共享功能后，偶现接收端看到共享画面的延迟较高。 (macOS) - 调用 [`destroyMediaPlayer`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-initialize#api_irtcengine_destroymediaplayer) 销毁媒体播放器时偶现崩溃。 (iOS) - 发送端将两路摄像头采集的视频进行本地合图并发布后，接收端偶现第二路摄像头画面缺失。 (Windows) - 屏幕共享场景下，部分机型必现接收端看到共享的画面卡顿。 (Android) ## v6.2.0 (对应 Native v4.2.0) [#v620-对应-native-v420] 该版本于 2023 年 5 月 24 日发布。 ### 升级必看 [#升级必看-86] 该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。 #### 视频采集 (Windows, iOS) [#视频采集-windows-ios] 原有用于摄像头和屏幕采集的方法已删除，请改用下表中列出的替代方法，并通过设置 `sourceType` 来指定视频源。 | 已删除方法 | 替代方法 | | --- | --- | | [release-notes-flutter-html-3-1-0 details](#table-slot-release-notes-flutter-html-3-1-0) | [`startCameraCapture`](/zh-CN/api-reference/rtc/flutter/video/camera-capture#api_irtcengine_startcameracapture) | | [release-notes-flutter-html-3-2-0 details](#table-slot-release-notes-flutter-html-3-2-0) | [`stopCameraCapture`](/zh-CN/api-reference/rtc/flutter/video/camera-capture#api_irtcengine_stopcameracapture) | | [release-notes-flutter-html-3-3-0 details](#table-slot-release-notes-flutter-html-3-3-0) | [`startScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapture2) (Windows) | | [release-notes-flutter-html-3-4-0 details](#table-slot-release-notes-flutter-html-3-4-0) | [`stopScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_stopscreencapture2) (Windows) | **release-notes-flutter-html-3-1-0 details** - `startPrimaryCameraCapture` (Windows) - `startSecondaryCameraCapture` (Windows, iOS) **release-notes-flutter-html-3-2-0 details** - `stopPrimaryCameraCapture` (Windows) - `stopSecondaryCameraCapture` (Windows, iOS) **release-notes-flutter-html-3-3-0 details** - `startPrimaryScreenCapture` (Windows) - `startSecondaryScreenCapture` (Windows) **release-notes-flutter-html-3-4-0 details** - `stopPrimaryScreenCapture` (Windows) - `stopSecondaryScreenCapture` (Windows) #### 视频数据获取 [#视频数据获取-6] - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调中新增了 `sourceType` 参数，用于表示具体的视频源类型。 - 以下回调已删除，请通过 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 和 [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 中的 `sourceType` 参数得知视频源类型。 - `onSecondaryPreEncodeCameraVideoFrame` (Windows) - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` - `onSecondaryPreEncodeScreenVideoFrame` (Windows) #### 媒体发布选项 [#媒体发布选项-6] - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` 已删除，请改用 `publishCustomAudioTrack`。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中的成员 `publishTrancodedVideoTrack` 变更为 `publishTranscodedVideoTrack`。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中的成员 `publishCustomAudioSourceId` 变更为 `publishCustomAudioTrackId`。 #### 音视频录制 [#音视频录制-6] - 删除 [`InterfaceIdType`](/zh-CN/api-reference/rtc/flutter/enum-interfaceidtype) 中的 `agoraIidMediaRecorder`。在创建录制对象前无需再获取 `agoraIidMediaRecorder` 接口类指针，你可以直接调用该版本新增的 [`createMediaRecorder`](/zh-CN/api-reference/rtc/flutter/recording#api_irtcengine_createmediarecorder) 方法创建录制对象。(Windows) - 删除 `getMediaRecorder` 方法，可通过该版本新增的 [`createMediaRecorder`](/zh-CN/api-reference/rtc/flutter/recording#api_irtcengine_createmediarecorder) 方法来创建录制对象。(Android, iOS, macOS) - 删除 [`startRecording`](/zh-CN/api-reference/rtc/flutter/recording#api_imediarecorder_startrecording) 、[`stopRecording`](/zh-CN/api-reference/rtc/flutter/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/flutter/recording#api_imediarecorder_setmediarecorderobserver) 中的 `connection` 参数。 - 删除 [`MediaRecorder`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediarecorder) 类中的 `release` 方法，你可直接调用该版本新增的 [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/flutter/recording#api_irtcengine_destroymediarecorder) 方法来销毁录制对象以释放资源。 #### 本地合图 (Windows) [#本地合图-windows-1] - [`LocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/flutter/class-localtranscoderconfiguration) 中的 `VideoInputStreams` 变更为 `videoInputStreams`。 - [`TranscodingVideoStream`](/zh-CN/api-reference/rtc/flutter/class-transcodingvideostream) 中的枚举类 [`MediaSourceType`](/zh-CN/api-reference/rtc/flutter/enum-mediasourcetype) 变更为 [`VideoSourceType`](/zh-CN/api-reference/rtc/flutter/enum-videosourcetype)。 #### 视频编码算法 [#视频编码算法] 自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。 如果你想自定义视频编码分辨率，可调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法，重新设置视频编码参数配置中的视频编码分辨率。 由于默认分辨率的提升，会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 #### 其他兼容性变更 [#其他兼容性变更-6] - `onApiCallExecuted` 已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。 - `IAudioFrameObserver` 类名变更为 `IAudioPcmFrameSink`，因此下列方法原型也有相应更新： - `onFrame` - [`MediaPlayer`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayer) 下的 `registerAudioFrameObserver` 和 `unregisterAudioFrameObserver` - `startChannelMediaRelay`、`updateChannelMediaRelay`、`startChannelMediaRelayEx` 和 `updateChannelMediaRelayEx` 已废弃，请改用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex)。 ### 新增特性 [#新增特性-125] #### AI 降噪 [#ai-降噪-6] 该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 [`setAINSMode`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。 #### 增强虚拟背景 [#增强虚拟背景-6] 为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 [`enableVirtualBackground`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 方法时，将自定义背景设置为更多类型： - 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。 - 将背景替换为多种格式的本地视频。 #### 视频场景化设置 [#视频场景化设置-6] 该版本新增 [`setVideoScenario`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoscenario) 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化： - 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。 - 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。 #### 本地录制远端音视频 (Beta) [#本地录制远端音视频-beta-6] 该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 [`onRecorderStateChanged`](/zh-CN/api-reference/rtc/flutter/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`onRecorderInfoUpdated`](/zh-CN/api-reference/rtc/flutter/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数，用于表示录制的音视频流的具体信息，并新增 [`createMediaRecorder`](/zh-CN/api-reference/rtc/flutter/recording#api_irtcengine_createmediarecorder) 方法，用于创建本地或远端的录制对象。 你可以通过如下方法体验本地录制远端音视频功能： - [`createMediaRecorder`](/zh-CN/api-reference/rtc/flutter/recording#api_irtcengine_createmediarecorder)：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。 - [`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/flutter/recording#api_imediarecorder_setmediarecorderobserver)：设置录制回调对象。 - [`startRecording`](/zh-CN/api-reference/rtc/flutter/recording#api_imediarecorder_startrecording)：开始录制。 - [`stopRecording`](/zh-CN/api-reference/rtc/flutter/recording#api_imediarecorder_stoprecording)：停止录制。 - [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/flutter/recording#api_irtcengine_destroymediarecorder)：销毁录制对象。 #### 本地合图 (macOS, iOS, Android) [#本地合图-macos-ios-android] 该版本新增本地合图功能，用户可以调用 [`startLocalVideoTranscoder`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) 方法，在本地将多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）混合和渲染，以实现自定义布局和效果。通过这项功能，你可以轻松创建个性化的视频显示效果，满足各种场景需求，如远程会议、直播、在线教育场景，同时支持人像画中画等功能。 另外，SDK 还提供了 [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 方法和 [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调。当你在开启本地合图后，可以调用 [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 更新合图的配置；当你在开启本地合图或者更新本地合图配置失败时，可通过 [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调得知合图失败的原因。 :::warning[注意] 本地合图对 CPU 的消耗较高，声网建议你在性能较高的设备上开启该功能。 ::: #### 本地合图 (Windows) [#本地合图-windows-2] 该版本新增了 [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调，当你在开启本地合图或者更新本地合图配置失败时，SDK 会触发该回调并报告合图失败的原因。 #### 多端同步 [#多端同步-6] 在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_getntpwalltimeinms) 方法获取当前的 NTP (网络时间协议) 时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。 #### 快速出图出声 [#快速出图出声-6] 该版本新增 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_enableinstantmediarendering) 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。 #### 视频渲染数据打点 [#视频渲染数据打点-6] 该版本新增 [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_startmediarenderingtracing) 和 [`startMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告相关事件的信息。 声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击 “加入频道” 按钮的时刻调用该方法进行打点，然后通过 [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。 ### 改进 [#改进-145] #### 优化变声 [#优化变声-6] 该版本新增了 [`setLocalVoiceFormant`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceformant) 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 [`setLocalVoicePitch`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch) 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。 #### 增强屏幕共享 (Android, iOS) [#增强屏幕共享-android-ios-1] 该版本新增 [`queryScreenCaptureCapability`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_queryscreencapturecapability) 方法，用于查询当前设备的屏幕捕获能力。如果你想在屏幕共享时启用高帧率（如 60 fps）、但不确定设备是否支持时，可以调用该方法、然后从返回值中得知设备支持的最高帧率是否满足需求。 该版本新增 [`setScreenCaptureScenario`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_setscreencapturescenario) 方法，用于设置屏幕共享的场景类型，SDK 会根据场景类型自动调整共享画面的的流畅度和清晰度。 #### 提升音频文件类型兼容性 (Android) [#提升音频文件类型兼容性-android-1] 该版本提升了音频文件类型兼容性，你可以通过 [`startAudioMixing`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_irtcengine_startaudiomixing2)、[`playEffect`](/zh-CN/api-reference/rtc/flutter/play/audio-effect-file#api_irtcengine_playeffect3)、[`openWithMediaSource`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 方法来打开以 `content://` 开头的 URI 文件。 #### 提升渲染兼容性 (Windows) [#提升渲染兼容性-windows-2] 提升了渲染的兼容性，解决了部分设备渲染失败而导致的黑屏问题。 #### 提升音视频同步能力 [#提升音视频同步能力-6] 针对自定义视频和音频采集场景，该版本新增 [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_getcurrentmonotonictimeinms) 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。 #### 优化多路摄像头及屏幕采集 [#优化多路摄像头及屏幕采集-4] 该版本新增 [`startScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapture2) (仅支持 PC 端) 和 [`startCameraCapture`](/zh-CN/api-reference/rtc/flutter/video/camera-capture#api_irtcengine_startcameracapture) 方法，通过多次调用并指定 `sourceType` 参数可以开启多路摄像头采集的视频流和多路屏幕采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头和显示器的场景。 #### 优化版权音乐 (Android, iOS) [#优化版权音乐-android-ios] 针对在线 K 歌房场景，改版本新增 [`getCaches`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_getcaches) 和 [`removeCache`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_removecache) 方法，用于获取、删除音乐资源缓存，并新增状态码和错误码，可方便用户排查问题。 #### 优化跨频道连麦 [#优化跨频道连麦-6] 该版本新增 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。 #### 多路音频自采集 [#多路音频自采集-6] 为更好地满足音频自采集的场景需求，该版本新增了 [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/flutter/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 和 [`destroyCustomAudioTrack`](/zh-CN/api-reference/rtc/flutter/audio/audio-custom-capturenrendering#api_imediaengine_destroycustomaudiotrack) 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性： - 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。 - 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。 #### 视频观测器 [#视频观测器-6] 自该版本起，SDK 对 [`onRenderVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 回调进行了优化，在不同的视频处理模式下返回值的意义不同： - 当视频处理模式为 `processModeReadOnly` 时，返回值无实际含义。 - 当视频处理模式为 `processModeReadWrite` 时，返回 `true` 代表设置 SDK 接收视频帧；返回 `false` 代表设置 SDK 丢弃视频帧。 #### 超分辨率 (Android, iOS) [#超分辨率-android-ios-1] 该版本提升了超分辨率的性能表现。为提升超分辨率易用性，该版本删除了 `enableRemoteSuperResolution`，超分辨率不再需要手动开启，SDK 将自动根据用户设备性能优化远端视频的分辨率。 ### 问题修复 [#问题修复-150] 该版本修复了以下问题： - 加入或退出频道时，安卓设备端偶现的崩溃。(Android) - 当快速切换身份角色时，观众端听不到声音。 - 偶现耳返开启无效。(Android) - 跨频道连麦时 [`onFirstRemoteVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onfirstremotevideoframe) 回调偶现丢失。(iOS) - 接收端主动订阅大流但是异常接收小流。(iOS) - 接收端默认接收小流几秒后自动变为大流。(macOS)。 - 偶现回声。(Android) - 屏幕共享偶现共享画面抖动。(macOS) - 由于 [`onRemoteAudioStateChanged`](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged) 回调异常造成客户端状态异常。(iOS, Android)。 - 使用媒体播放器播放网络摄像头的 RTSP 码流时，偶现花屏。(Windows) - 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。 - 在红米 9A 上进行 CDN 推流，将推流的视频分辨率设置为 3840 × 2160 必现崩溃。(Android) - 把播放器的渲染视图设为 UIViewController 的视图后，使用播放器播放视频，视频窗口切到全屏时视频画面会从左下角开始逐渐放大。(macOS) - 在本地合图场景下，不支持对 PNG 和 GIF 图片的 Alpha 通道渲染，导致透明底色的图片显示为非透明底色。(Windows) - 合唱模式下，OPPO R11 设备外放加入频道后，对端听到明显杂声和回音。(Android) - 本地音乐文件结束播放时，未能触发 [`onAudioMixingFinished`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingfinished) 回调。(Android) - 加入频道后添加水印然后删除，远端仍能看到水印。(Windows) - 开始屏幕共享后添加水印，远端接收的屏幕共享画面没有水印。(Windows) - 加入频道后接入外接摄像头，调用 [`setDevice`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_ivideodevicemanager_setdevice_ivideodevicemanager) 指定视频采集设备为该外接摄像头，方法未生效。(macOS, Windows) - 接收端通过视频观测器接收的第一帧视频帧偶现丢包。(Android) - 在多频道场景下开启屏幕共享，偶现远端看到的本地屏幕共享画面为黑屏。(Android) - 在屏幕共享场景下，如果将一个窗口设置为前置和描边，则必现窗口前置失败。(Windows) - 开启虚拟背景时切换至后置摄像头会导致背景倒置。(Android) - 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。 - 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。 ### API 变更 [#api-变更-77] #### 新增 [#新增-71] - [`startCameraCapture`](/zh-CN/api-reference/rtc/flutter/video/camera-capture#api_irtcengine_startcameracapture) - [`stopCameraCapture`](/zh-CN/api-reference/rtc/flutter/video/camera-capture#api_irtcengine_stopcameracapture) - [`startScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapture2) (Windows, macOS) - [`stopScreenCaptureBySourceType`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_stopscreencapture2) (Windows, macOS) - [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) - [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) - [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_getntpwalltimeinms) - [`setVideoScenario`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoscenario) - [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_getcurrentmonotonictimeinms) - [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) - [`startLocalVideoTranscoder`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) (macOS, iOS, Android) - [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) (macOS, iOS, Android) - [`queryScreenCaptureCapability`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_queryscreencapturecapability) (iOS, Android) - [`setScreenCaptureScenario`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_setscreencapturescenario) (iOS, Android) - [`setAINSMode`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) - [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/flutter/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) - [`destroyCustomAudioTrack`](/zh-CN/api-reference/rtc/flutter/audio/audio-custom-capturenrendering#api_imediaengine_destroycustomaudiotrack) - [`createMediaRecorder`](/zh-CN/api-reference/rtc/flutter/recording#api_irtcengine_createmediarecorder) - [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/flutter/recording#api_irtcengine_destroymediarecorder) - [`MusicContentCenter`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusiccontentcenter) 中新增如下方法 (Android, iOS)： - [`getCaches`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_getcaches) - [`removeCache`](/zh-CN/api-reference/rtc/flutter/play/drm#api_imusiccontentcenter_removecache) - [`AudioTrackConfig`](/zh-CN/api-reference/rtc/flutter/class-audiotrackconfig) - [`MusicCacheInfo`](/zh-CN/api-reference/rtc/flutter/class-musiccacheinfo) (Android, iOS) - [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/flutter/class-recorderstreaminfo) - [`AudioAinsMode`](/zh-CN/api-reference/rtc/flutter/enum-audioainsmode) - [`AudioTrackType`](/zh-CN/api-reference/rtc/flutter/enum-audiotracktype) - [`MusicCacheStatusType`](/zh-CN/api-reference/rtc/flutter/enum-musiccachestatustype) (Android, iOS) - [`VideoApplicationScenarioType`](/zh-CN/api-reference/rtc/flutter/enum-videoapplicationscenariotype) - [`ScreenCaptureFramerateCapability`](/zh-CN/api-reference/rtc/flutter/enum-screencaptureframeratecapability) - [`RtcEngineContext`](/zh-CN/api-reference/rtc/flutter/class-rtcengineconfig) 中新增 `domainLimit` 和 `autoRegisterAgoraExtensions` 属性 - [`onRecorderStateChanged`](/zh-CN/api-reference/rtc/flutter/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`onRecorderInfoUpdated`](/zh-CN/api-reference/rtc/flutter/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数 - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 中增加 `sourceType` 参数 - [`backgroundSourceType`](/zh-CN/api-reference/rtc/flutter/enum-backgroundsourcetype) 中新增 `backgroundNone` 和 `backgroundVideo` - `PreloadStatusCode` 中增加 `kPreloadStatusRemoved` (Android, iOS) - `MusicContentCenterStatusCode` 中增加如下枚举 (Android, iOS)： - `kMusicContentCenterStatusErrGateway` - `kMusicContentCenterStatusErrPermissionAndResource` - `kMusicContentCenterStatusErrInternalDataParse` - `kMusicContentCenterStatusErrMusicLoading` - `kMusicContentCenterStatusErrMusicDecryption` - [`MusicContentCenterConfiguration`](/zh-CN/api-reference/rtc/flutter/class-musiccontentcenterconfiguration) 中新增 `maxCacheSize` (Android, iOS) - [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_enableinstantmediarendering) - [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengine_startmediarenderingtracing) - [`startMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) - [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/flutter/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) - [`MediaTraceEvent`](/zh-CN/api-reference/rtc/flutter/enum-mediatraceevent) - [`VideoRenderingTracingInfo`](/zh-CN/api-reference/rtc/flutter/class-videorenderingtracinginfo) #### 修改 [#修改-20] - [`onMusicChartsResult`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 中的 `status` 修改为 `errorCode` (Android, iOS) - [`onMusicCollectionResult`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 中的 `status` 修改为 `errorCode` (Android, iOS) - [`onLyricResult`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 中的 `status` 修改为 `errorCode` (Android, iOS) - [`onPreLoadEvent`](/zh-CN/api-reference/rtc/flutter/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 中的 `msg` 修改为 `errorCode` (Android, iOS) #### 废弃 [#废弃-25] - `startChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelay` - `updateChannelMediaRelayEx` - `onChannelMediaRelayEvent` - `ChannelMediaRelayEvent` #### 删除 [#删除-31] - `startPrimaryScreenCapture` (Windows) - `startSecondaryScreenCapture` (Windows) - `stopPrimaryScreenCapture` (Windows) - `stopSecondaryScreenCapture` (Window) - `startPrimaryCameraCapture` (Windows) - `startSecondaryCameraCapture` (Windows, iOS) - `stopPrimaryCameraCapture` (Windows) - `stopSecondaryCameraCapture` (Windows, iOS) - `onSecondaryPreEncodeCameraVideoFrame` (Windows) - `onScreenCaptureVideoFrame` - `onPreEncodeScreenVideoFrame` - `onSecondaryPreEncodeScreenVideoFrame` (Windows) - `onApiCallExecuted` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` - `getMediaRecorder` - [`MediaRecorder`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediarecorder) 类中的 `release` - [`InterfaceIdType`](/zh-CN/api-reference/rtc/flutter/enum-interfaceidtype) 中的 `agoraIidMediaRecorder` (Windows) - [`startRecording`](/zh-CN/api-reference/rtc/flutter/recording#api_imediarecorder_startrecording)、[`stopRecording`](/zh-CN/api-reference/rtc/flutter/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/flutter/recording#api_imediarecorder_setmediarecorderobserver) 中删除 `connection` 参数 - `enableRemoteSuperResolution` - [`RemoteVideoStats`](/zh-CN/api-reference/rtc/flutter/class-remotevideostats) 中删除 `superResolutionType` ## v6.1.0 (对应 Native v4.1.0) [#v610-对应-native-v410] 该版本于 2022 年 12 月 20 日发布。 ### 升级必看 [#升级必看-87] 如果你已经使用了以下类或方法，请在升级到该版本后重新调用方法并更新参数设置： 删除了 [`enableDualStreamMode`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_enabledualstreammode3) 中的 `sourceType` 参数，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。 ### 新增特性 [#新增特性-126] #### 耳返 [#耳返-6] 该本版新增耳返功能。你可以调用 [`enableInEarMonitoring`](/zh-CN/api-reference/rtc/flutter/audio/audio-capture#api_irtcengine_enableinearmonitoring2) 开启耳返功能。 成功开启耳返功能后，你可以调用 `registerAudioFrameObserver` 注册音频观测器，SDK 会触发 [`onEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/flutter/audio/audio-raw#callback_iaudioframeobserverbase_onearmonitoringaudioframe) 回调报告耳返原始音频数据。你可以使用自己的音效处理模块对耳返音频数据进行前处理，实现自定义音效，声网推荐你调用 [`setEarMonitoringAudioFrameParameters`](/zh-CN/api-reference/rtc/flutter/audio/audio-raw#api_irtcengine_setearmonitoringaudioframeparameters) 方法设置耳返音频数据格式，SDK 会根据该方法中的参数计算采样间隔，并根据该采样间隔触发 [`onEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/flutter/audio/audio-raw#callback_iaudioframeobserverbase_onearmonitoringaudioframe) 回调。 如需调节耳返音量，你可以调用 [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/flutter/audio/audio-capture#api_irtcengine_setinearmonitoringvolume)。 #### 音频采集设备测试 (Android) [#音频采集设备测试-android-1] 该版本支持加入频道前测试本地音频采集设备。你可以调用 [`startRecordingDeviceTest`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_startrecordingdevicetest) 开启音频采集设备测试，测试完成后，调用 [`stopPlaybackDeviceTest`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_stopplaybackdevicetest) 方法停止音频采集设备测试。 #### 本地网络连接类型 [#本地网络连接类型-6] 为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 [`getNetworkType`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_getnetworktype) 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 [`onNetworkTypeChanged`](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onnetworktypechanged) 回调，报告当前的网络连接类型。 #### 音强选流 [#音强选流-6] 声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请联系技术支持。 同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗，详见[音强选流](/zh-CN/realtime-media/rtc/build/audio/audio-stream-filter)。 :::info[信息] 该版本新增音强选流功能，如需开启该功能，请联系[技术支持](https://ticket.shengwang.cn/)。 ::: #### 双流模式 [#双流模式-7] 该版本对双流模式做了优化，在加入频道前后均可调用 [`enableDualStreamMode`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_enabledualstreammode3) 和 [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_enabledualstreammodeex)。 扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式（即：默认不主动发送小流），可通过以下步骤开启发送小流： 1. 接收端主播调用 [`setRemoteVideoStreamType`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_setremotevideostreamtype) 或 [`setRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 发起接收小流申请。 2. 发送端收到申请后自动切换为发送小流模式。 如果你想修改上述发送端的默认行为，可以调用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_setdualstreammode2) 方法，将 `mode` 参数设置为 `disableSimulcastStream` (始终不发送小流) 或 `enableSimulcastStream` (始终发送小流)。 #### 声卡采集设备 (Windows) [#声卡采集设备-windows-2] SDK 默认使用播放设备为声卡采集设备，自该版本起，你可以另外指定声卡采集设备并将其采集到的音频发布到远端。 - [`setLoopbackDevice`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_setloopbackdevice)：用于指定声卡采集设备，当你不希望当前的播放设备为声卡采集设备时，可以调用该方法另外指定别的设备作为声卡采集设备。 - [`getLoopbackDevice`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_getloopbackdevice)：用于获取当前的声卡采集设备。 - [`followSystemLoopbackDevice`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_followsystemloopbackdevice)：用于设置声卡采集设备是否跟随系统默认的播放设备。 #### 空间音频 [#空间音频-11] 该版本新增了如下适用于空间音频场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。 - 隔声区域：你可以通过调用 [`setZones`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 设置隔声区域和声音衰减系数。当音源 (可以为用户或媒体播放器) 跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用 [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 和 [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) 方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖 [`setZones`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 中的声音衰减系数。 - 多普勒音效：你可以通过设置 [`SpatialAudioParams`](/zh-CN/api-reference/rtc/flutter/class-spatialaudioparams) 中的 `enableDoppler` 参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下（比如赛车游戏场景），接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用 [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 方法使用预设的耳机均衡效果，以改善耳机的听感。如果在调用 [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。 #### 多路摄像头 (iOS) [#多路摄像头-ios-1] 该版本新增多路摄像头视频采集功能，你可以通过调用 [`enableMultiCamera`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_enablemulticamera) 开启多路摄像头采集模式，再调用 `startSecondaryCameraCapture` 通过第二个摄像头采集视频，然后将采集到的视频发布到多频道中。 如需停止多路摄像头采集，需要先调用 `stopSecondaryCameraCapture` 停止第二个摄像头采集，然后调用 [`enableMultiCamera`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_enablemulticamera) 并将 `enabled` 设置为 `false`。 #### 版权音乐 (iOS, Android) [#版权音乐-ios-android] 为解决直播、语聊房、在线 K 歌房等场景下歌曲的应用版权问题，该版本新增版权音乐相关 API。你可以通过调用 [`MusicContentCenter`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusiccontentcenter) 类、[`MusicPlayer`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusicplayer) 类、[`MusicContentCenterEventHandler`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusiccontentcentereventhandler) 类下的相关 API 实现在实时互动场景中播放版权音乐以及相关功能，例如检索音乐资源、获取音乐榜单及榜单详情、预加载及播放音乐资源、下载歌词及海报等功能。你还可以参考[在线 K 歌房](/zh-CN/solutions/online-ktv)来体验搭配了演唱评分、美声音效等一系列功能的线上 K 歌场景化解决方案。 #### 已编码视频帧观测器 [#已编码视频帧观测器-5] 该版本新增 [`setRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) 和 [`setRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) 方法，当你调用 [`registerVideoEncodedFrameObserver`](/zh-CN/api-reference/rtc/flutter/video/video-encoded#api_imediaengine_registervideoencodedframeobserver) 方法为编码后的视频注册视频帧观测器时，SDK 默认订阅编码后的视频帧。如果你想要修改订阅选项，可以调用新增的方法进行设置。 有关更多注册视频观测器和订阅选项的介绍，详见 [API 参考](/zh-CN/api-reference/rtc/flutter/video/video-encoded#api_imediaengine_registervideoencodedframeobserver)。 #### MPUDP (MultiPath UDP) [#mpudp-multipath-udp-6] 自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在移动端和桌面端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。 :::info[信息] 如果你希望体验该功能，请联系 sales@shengwang.cn。 ::: #### 注册插件 (Windows) [#注册插件-windows-2] 该版本新增 [`registerExtension`](/zh-CN/api-reference/rtc/flutter/extension#api_irtcengine_registerextension) 方法，用于注册插件。当使用第三方插件时，你需要按照以下顺序调用插件相关的 API： 调用 [`loadExtensionProvider`](/zh-CN/api-reference/rtc/flutter/extension#api_irtcengine_loadextensionprovider) -> [`registerExtension`](/zh-CN/api-reference/rtc/flutter/extension#api_irtcengine_registerextension) -> [`setExtensionProviderProperty`](/zh-CN/api-reference/rtc/flutter/extension#api_irtcengine_setextensionproviderproperty) -> [`enableExtension`](/zh-CN/api-reference/rtc/flutter/extension#api_irtcengine_enableextension)。 #### 设备管理 (Windows, macOS) [#设备管理-windows-macos] 该版本新增了一系列回调，帮助你更好地了解音视频设备的状态。 - [`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged)：当视频设备的状态发生改变时上报。 - [`onAudioDeviceStateChanged`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicestatechanged)：当音频设备的状态发生改变时上报。 - [`onAudioDeviceVolumeChanged`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicevolumechanged)：当音频设备或 App 的音量发生改变时上报。 #### 摄像头采集选项 [#摄像头采集选项-6] 该版本在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/flutter/class-cameracapturerconfiguration) 中增加了 `followEncodeDimensionRatio` 成员，你可以在使用摄像头采集视频时，通过该成员设置是否跟随 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中已经设置的视频宽高比。 #### 多频道管理 [#多频道管理-6] 该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。 - 新增 [`muteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) 和 [`muteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) 方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增 [`muteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) 和 [`muteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) 方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增 [`startRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex)、[`startRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex)、[`updateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) 和 [`stopRtmpStreamEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) 方法，用于实现多频道场景下的旁路推流。 - 新增 `startChannelMediaRelayEx`、`updateChannelMediaRelayEx`、[`pauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex)、[`resumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) 和 [`stopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) 方法，用于实现多频道场景下的跨频道媒体流转发。 - [`leaveChannelEx`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengineex_leavechannelex2) 方法新增 `options` 参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。 #### 视频编码偏好 [#视频编码偏好-6] 一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/flutter/class-videoencoderconfiguration) 中新增 `advanceOptions` 成员参数，用于视频编码属性的进阶设置： - [`CompressionPreference`](/zh-CN/api-reference/rtc/flutter/enum-compressionpreference)：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。 - [`EncodingPreference`](/zh-CN/api-reference/rtc/flutter/enum-encodingpreference)：视频编码器偏好设置，用于进阶设置视频编码属性，视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。 #### 日志上传 [#日志上传-6] 使用声网私有媒体服务器的场景下，为支持用户在调用 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_setlocalaccesspoint) 方法时的进阶设置，该版本在 [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/flutter/class-localaccesspointconfiguration) 中新增 `advancedConfig` 成员参数，该参数支持如下设置： - `logUploadServer`：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。 #### 用户角色切换 [#用户角色切换-6] 为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 [`onClientRoleChanged`](/zh-CN/api-reference/rtc/flutter/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调中新增 `newRoleOptions` 参数，该参数取值如下： - `audienceLatencyLevelLowLatency`(1)：低延时，属于极速直播。 - `audienceLatencyLevelUltraLowLatency`(2)：超低延时，属于互动直播。 ### 改进 [#改进-146] #### 视频信息发生改变回调 [#视频信息发生改变回调-6] 该版本优化了 [`onVideoSizeChanged`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged) 的触发逻辑，当单独调用 [`startPreview`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_startpreview2) 时，也可触发该回调并上报本地视频大小发生改变。 #### 首帧出图 (Windows) [#首帧出图-windows-2] 该版本缩短了首帧出图时间，以提升用户视频体验。 #### 屏幕共享 [#屏幕共享-11] 该版本对屏幕共享功能做了一系列优化，除以下列出的功能性改进之外，还有一部分可用性提升，详见[问题修复](#问题修复-150)。 Windows macOS - 在 [`ScreenCaptureSourceInfo`](/zh-CN/api-reference/rtc/flutter/class-screencapturesourceinfo) 中增加了 `minimizeWindow` 成员，用于表示目标窗口是否已最小化。 - 在 [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/flutter/class-screencaptureparameters) 中增加了 `enableHighLight`、`highLightColor` 和 `highLightWidth` 成员，支持你在屏幕共享时对目标窗口或屏幕进行描边。 - 兼容更多主流 App，包括但不限于：WPS Office，Microsoft Office PowerPoint，Visual Studio Code，Adobe Photoshop，Windows Media Player，Scratch。 - 兼容更多设备和操作系统，包括但不限于：Windows 8 系统，无独立显卡的设备，双显卡设备。 - 支持超高清视频 (分辨率为 4K，帧率为 60 fps)，你可以在满足要求的设备上使用该功能。声网推荐的最低设备规格为：intel(R) Core(TM) i7-9750H CPU @ 2.60GHZ。 - 兼容更多设备和场景，包括但不限于：双显卡设备，使用外接屏幕进行屏幕共享。 - 支持超高清视频 (分辨率为 4K，帧率为 60 fps)，你可以在满足要求的设备上使用该功能。声网推荐的最低设备规格为：MacBook Pro (16 英寸，M1，2021 年)。 #### 蓝牙权限 (Android) [#蓝牙权限-android-1] 为简化集成步骤，自该版本起，SDK 支持你在不添加 `BLUETOOTH_CONNECT` 权限的情况下，也能让 Android 用户正常使用蓝牙。 #### CDN 推流 [#cdn-推流-6] 为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 `onDirectCdnStreamingStats` 回调报告推送的视频流的实际分辨率。 #### 跨频道媒体流转发 [#跨频道媒体流转发-13] 该版本对 `updateChannelMediaRelay` 方法做了如下优化： - v6.1.0 前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码 `relayEventPacketUpdateDestChannelRefused `(8)，你需要重新调用 `updateChannelMediaRelay` 方法。 - v6.1.0 及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。 #### AIAEC [#aiaec-6] 该版本基于 AI 方法重构了 AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。 #### 虚拟背景 [#虚拟背景-6] 该版本对虚拟背景算法做了如下优化： - 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。 - 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。 - 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。 - 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。 #### 其他改进 [#其他改进-62] - 降低了推送外部音频源时的上行延迟。 - 提升了会议场景 (`audioScenarioMeeting`) 默认参数配置下的回声消除性能。 - 提升了 SDK 视频渲染的流畅度。 - 降低了当主播调用 [`muteLocalVideoStream`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_mutelocalvideostream) 方法时本地设备的 CPU 占用率和耗电量。(Window, macOS) - 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。 ### 问题修复 [#问题修复-151] 该版本修复了以下问题： 所有平台 Android iOS Windows macOS - 在频道内调用 [`setVideoEncoderConfigurationEx`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengineex_setvideoencoderconfigurationex) 将视频的分辨率调高时，偶现失效。 - 使用媒体播放器播放视频，先调用 [`play`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 再调用 [`pause`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用 [`resume`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-control#api_imediaplayer_resume) 恢复播放后，偶现视频画面出现快进。 - 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。 - 调用 [`getExtensionProperty`](/zh-CN/api-reference/rtc/flutter/extension#api_irtcengine_getextensionproperty2) 失败，返回空字符串。 - 当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。 - 在多人会议场景下，本地用户接听并挂断电话后，偶现本地用户和远端用户无法听见对方的声音。 - 调用 [`setCloudProxy`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_setcloudproxy) 设置云代理后，调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengineex_joinchannelex) 加入多频道失败。 - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/flutter/play/audio-mixing#api_irtcengine_startaudiomixing2) 播放 `ipod-library://item` 路径的音乐文件失败。 - 同时通过 [`onRecordAudioFrame`](/zh-CN/api-reference/rtc/flutter/audio/audio-raw#callback_iaudioframeobserverbase_onrecordaudioframe) 和 [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 回调分别获取的音频和视频数据时间戳不同。 - 调用 [`stopPreview`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_stoppreview2) 关闭本地视频预览时，导致已设置的虚拟背景一定概率失效。 - 开启虚拟背景并设置为背景虚化效果时，多次退出频道再加入频道时偶现崩溃。 - 本地端使用 1920 x 1080 的摄像头作为视频采集源，偶现远端视频的分辨率与本地端不一致。 - 通过摄像头采集视频时，如果在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/flutter/class-cameracapturerconfiguration) 中设置的视频宽高比例和在 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中设置的不一致，导致本地视频预览的画面比例未按照后者的设置呈现。 - 在屏幕共享场景下，将共享的窗口最小化时，偶现远端用户出现黑屏或远端画面切换为视频小流。 - 在直播场景下，主播开启屏幕共享时，偶现观众听主播说话有回声。 - 在屏幕共享场景下，偶现系统声音音量变小。 - 在屏幕共享场景下，在横屏显示器与竖屏显示器之间共享屏幕时出现黑屏。 - 在屏幕共享场景下屏蔽窗口时，屏幕共享区域超出屏幕分辨率导致崩溃。 - 调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapturebydisplayid) 进行屏幕共享时无法屏蔽窗口。 - 在屏幕共享场景下，远端用户看到的画面偶现黑屏、卡顿、崩溃。 - 在屏幕共享场景下，偶现 [`onNetworkQuality`](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onnetworkquality) 回调报告频道内指定用户的上下行网络状态不准确。 - 在屏幕共享场景下，在共享窗口中看到的鼠标位置与实际位置有偏差。 - 从普通场景切换屏幕共享场景后，由于两种场景下设置的分辨率不同导致偶现崩溃。 - 通过摄像头采集视频时，如果在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/flutter/class-cameracapturerconfiguration) 中设置的视频宽高比例和在 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中设置的不一致，导致本地视频预览的画面比例未按照后者的设置呈现。 - 在屏幕共享场景下，将共享的窗口最小化或关闭共享窗口时，共享窗口自动切换为该 App 的其他窗口。 - 在屏幕共享场景下，偶现系统声音音量变小。 - 在屏幕共享场景下，当共享的窗口为半屏模式时，对窗口的描边不正确。 - 在屏幕共享场景下，远端用户看到的画面偶现黑屏、卡顿、崩溃。 - 在屏幕共享场景下，偶现 [`onNetworkQuality`](/zh-CN/api-reference/rtc/flutter/network#callback_irtcengineeventhandler_onnetworkquality) 回调报告频道内指定用户的上下行网络状态不准确。 - 启动并停止音频采集设备测试后，启动音频播放设备测试时必现无声。 - [`onVideoPublishStateChanged`](/zh-CN/api-reference/rtc/flutter/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 回调报告的视频源类型不准确。 ### API 变更 [#api-变更-78] #### 新增 [#新增-72] - [`getNativeHandle`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_getnativehandle) - [`getMusicContentCenter`](/zh-CN/api-reference/rtc/flutter/play/drm#api_irtcengine_getmusiccontentcenter) - [`getPlaybackDefaultDevice`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_getplaybackdefaultdevice) - [`getRecordingDefaultDevice`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_getrecordingdefaultdevice) - [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_enabledualstreammodeex) - [`setDualStreamMode`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_setdualstreammode2) - [`setDualStreamModeEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_setdualstreammodeex) - [`SimulcastStreamMode`](/zh-CN/api-reference/rtc/flutter/enum-simulcaststreammode) - [`getNetworkType`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_getnetworktype) - [`setLoopbackDevice`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_setloopbackdevice) (Windows) - [`getLoopbackDevice`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_getloopbackdevice) (Windows) - [`followSystemLoopbackDevice`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#api_iaudiodevicemanager_followsystemloopbackdevice) (Windows) - [`setZones`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) - [`HeadphoneEqualizerPreset`](/zh-CN/api-reference/rtc/flutter/enum-headphoneequalizerpreset) - [`enableMultiCamera`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_irtcengine_enablemulticamera) (iOS) - [`setRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) - [`setRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) - [`VideoSubscriptionOptions`](/zh-CN/api-reference/rtc/flutter/class-videosubscriptionoptions) - [`AdvanceOptions`](/zh-CN/api-reference/rtc/flutter/class-advanceoptions) - [`EncodingPreference`](/zh-CN/api-reference/rtc/flutter/enum-encodingpreference) - [`CompressionPreference`](/zh-CN/api-reference/rtc/flutter/enum-compressionpreference) - [`adjustUserPlaybackSignalVolumeEx`](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#api_irtcengineex_adjustuserplaybacksignalvolumeex) - [`onRhythmPlayerStateChanged`](/zh-CN/api-reference/rtc/flutter/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) (Android, iOS) - [`RhythmPlayerStateType`](/zh-CN/api-reference/rtc/flutter/enum-rhythmplayerstatetype) - `RhythmPlayerErrorType` - [`enableAudioVolumeIndicationEx`](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#api_irtcengineex_enableaudiovolumeindicationex) - [`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) (Windows, macOS) - [`onAudioDeviceStateChanged`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicestatechanged) (Windows, macOS) - [`onAudioDeviceVolumeChanged`](/zh-CN/api-reference/rtc/flutter/device-management/audio-device#callback_irtcengineeventhandler_onaudiodevicevolumechanged) (Windows, macOS) - [`registerExtension`](/zh-CN/api-reference/rtc/flutter/extension#api_irtcengine_registerextension) (Windows) - [`muteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) - [`muteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) - [`muteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) - [`muteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) - [`startRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex) - [`startRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex) - [`updateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) - [`stopRtmpStreamEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - [`pauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex) - [`resumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) - [`stopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/flutter/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) - [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/flutter/class-localaccesspointconfiguration) - [`AdvancedConfigInfo`](/zh-CN/api-reference/rtc/flutter/class-advancedconfiginfo) - [`LogUploadServerInfo`](/zh-CN/api-reference/rtc/flutter/class-loguploadserverinfo) - [`MusicContentCenter`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusiccontentcenter) 接口类及其中方法 (Android, iOS) - [`MusicPlayer`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusicplayer) 接口类及其中方法 (Android, iOS) - [`MusicContentCenterEventHandler`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imusiccontentcentereventhandler) 接口类及其中回调 (Android, iOS) - [`MusicChartInfo`](/zh-CN/api-reference/rtc/flutter/class-musicchartinfo) 类 (Android, iOS) - [`ClimaxSegment`](/zh-CN/api-reference/rtc/flutter/class-climaxsegment) 类 (Android, iOS) - [`Music`](/zh-CN/api-reference/rtc/flutter/class-music) 类 (Android, iOS) - [`MusicContentCenterConfiguration`](/zh-CN/api-reference/rtc/flutter/class-musiccontentcenterconfiguration) 类 (Android, iOS) - [`MusicChartCollection`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_musicchartcollection) 类 (iOS) - [`MusicCollection`](/zh-CN/api-reference/rtc/flutter/class-musiccollection) 类 (iOS) - `PreloadStatusCode` (iOS) - `MusicContentCenterStatusCode` (iOS) #### 修改 [#修改-21] - [`enableDualStreamMode`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_enabledualstreammode3)：删除 `sourceType` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions)：新增 `isAudioFilterable` - [`enableInEarMonitoring`](/zh-CN/api-reference/rtc/flutter/audio/audio-capture#api_irtcengine_enableinearmonitoring2)：支持 PC 端 - [`setEarMonitoringAudioFrameParameters`](/zh-CN/api-reference/rtc/flutter/audio/audio-raw#api_irtcengine_setearmonitoringaudioframeparameters)：支持 PC 端 - [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/flutter/audio/audio-capture#api_irtcengine_setinearmonitoringvolume)：支持 PC 端 - [`onEarMonitoringAudioFrame`](/zh-CN/api-reference/rtc/flutter/audio/audio-raw#callback_iaudioframeobserverbase_onearmonitoringaudioframe)：支持 PC 端 - [`SpatialAudioParams`](/zh-CN/api-reference/rtc/flutter/class-spatialaudioparams)：新增 `enableDoppler` - [`ScreenCaptureSourceInfo`](/zh-CN/api-reference/rtc/flutter/class-screencapturesourceinfo)：新增 `minimizeWindow` - [`ScreenCaptureParameters`](/zh-CN/api-reference/rtc/flutter/class-screencaptureparameters)：支持 Windows 平台 - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/flutter/class-cameracapturerconfiguration)：新增 `followEncodeDimensionRatio` - [`leaveChannelEx`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengineex_leavechannelex2)：新增 `options` - [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/flutter/class-videoencoderconfiguration)：新增 `advanceOptions` - [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/flutter/class-localaccesspointconfiguration)：新增 `advancedConfig` - [`onClientRoleChanged`](/zh-CN/api-reference/rtc/flutter/channel#callback_irtcengineeventhandler_onclientrolechanged)：新增 `newRoleOptions` - [`VideoCanvas`](/zh-CN/api-reference/rtc/flutter/class-videocanvas)：新增 `setupMode`、`mediaPlayerId` 和 `cropArea` - [`LocalVideoStats`](/zh-CN/api-reference/rtc/flutter/class-localvideostats)：新增 `hwEncoderAccelerating` #### 废弃 [#废弃-26] - `onApiCallExecuted` - `ChannelMediaRelayEvent`：废弃 `relayEventPacketUpdateDestChannelRefused `(8) ## v6.0.0 (对应 Native v4.0.0) [#v600-对应-native-v400] 该版本于 2022 年 9 月 29 日发布。 ### 升级必看 [#升级必看-88] v6.0.0 SDK 包名由 `agora_rtc_ng` 变更为 `agora_rtc_engine`，且对部分功能的实现方式进行了优化，从而导致与 v5.x 不兼容。如下为存在兼容性变更的主要功能： - 多频道 - 媒体流发布控制 - 自定义视频采集与渲染 (Media IO 方式) - 错误码与警告码 升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见[迁移指南](/zh-CN/realtime-media/rtc/reference/migration-guide)。 ### 新增特性 [#新增特性-127] #### 多路媒体流 [#多路媒体流-6] 该版本支持通过设置 [`RtcEngineEx`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex) 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions)，实现一个 [`RtcEngine`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) 实例同时采集多路音视频源并发布到远端，适应各种业务场景。例如： - 调用 [`joinChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 加入首个频道后，多次调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengineex_joinchannelex) 加入多个频道，通过不同的用户 ID 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 设置发布指定的流到不同的频道。 - 支持通过设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中的 `publishSecondaryCameraTrack` 和 `publishSecondaryScreenTrack` 同时发布多路摄像头采集或者屏幕共享的视频流。 该版本支持通过 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/flutter/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流： 1. 创建自采集视频轨道：调用 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/flutter/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法创建一个自定义视频轨道，并获得视频轨道 ID。 2. 设置频道中待发布的自采集视频轨道：在每个频道的 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中，将 `customVideoTrackId` 参数设置为你想要发布的视频轨道 ID，并将 `publishCustomVideoTrack` 设置为 `true`。 3. 推送外部视频源：调用 [`pushVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe)，并将 `videoTrackId` 指定为你想要发布的自定义视频轨道 ID，即可根据步骤 2 的设置，实现在多个频道中发布对应的自定义视频源。 结合多频道能力，你还可以体验如下功能： - 将多组音视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路音频流混音后通过一个用户 ID (`uid`) 发布到远端。 - 将多组视频频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路视频流合图后通过一个用户 ID (`uid`) 发布到远端。 #### 超高清分辨率 (Beta) (Windows, macOS) [#超高清分辨率-beta-windows-macos-1] 为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持 4K 分辨率。优化了 FEC (Forward Error Correction) 算法，可根据视频帧包数与帧率进行自适应切换，降低 4K 场景下的视频卡顿率。你可以在调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 时，设置编码分辨率为 4K (3840 × 2160)、帧率为 60 fps。当你的设备不支持 4K 时，SDK 支持自动回退到适合的分辨率和帧率。 :::info[信息] - 该功能对设备性能和网络带宽有一定要求，在不同的平台上支持的上下行帧率也不同，如需体验该功能，请联系[技术支持](https://ticket.shengwang.cn/)。 - 高分辨率可能会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 全高清和超高清分辨率 (Android, iOS) [#全高清和超高清分辨率-android-ios-1] 为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持全高清 (FHD) 和超高清 (UHD) 视频分辨率。你可以在调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法时，将 `dimensions` 参数设置为 1920 × 1080 或更高的分辨率。如果你的设备不支持高分辨率，SDK 支持自动回退到适合的分辨率。 :::info[信息] - 超高清分辨率 (4K，60 fps) 目前为 Beta 功能，且对设备性能和网络带宽有一定要求，如需体验该功能，请联系[技术支持](https://ticket.shengwang.cn/)。 - 高分辨率通常需要更高的性能消耗，为避免设备性能不足导致体验下降，声网建议你在性能较好的设备上开启全高清和超高清视频分辨率。 - 高分辨率可能会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 内置媒体播放器 [#内置媒体播放器-6] 为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 [`createMediaPlayer`](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer) 创建媒体播放器后，你可以通过 [`MediaPlayer`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayer) 类的一系列方法体验内置媒体播放器的各类功能： - 自动播放本地、在线、自定义的媒体资源。 - 预先加载待播放的媒体资源。 - 根据网络情况切换媒体资源的播放线路。 - 将媒体播放器的音视频流推送到任意频道、分享给远端用户。 - 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。 #### 新版 AI 降噪 [#新版-ai-降噪-6] 自该版本起，SDK 支持新版 AI 降噪 (相对于 agora_rtc_engine: ^5.x 中的基础 AI 降噪) 功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。 如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。 #### 超高音质 [#超高音质-6] 为还原音频的细节、提升音频的清晰度，该版本新增 `ultraHighQualityVoice`。在语聊、歌唱等以人声为主的场景中，你可以调用 [`setVoiceBeautifierPreset`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) 并使用该枚举体验超高音质。 #### 空间音频 [#空间音频-12] :::warning[注意] 空间音频功能当前处于实验阶段，请联系 sales@shengwang.cn 开通空间音频功能，如果需要技术支持，请[联系技术支持](https://ticket.shengwang.cn/)。 ::: 该版本提供本地直角坐标系计算方案实现空间音频： - 使用 [`LocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine) 类实现空间音频，通过 SDK 计算远端用户的空间坐标。你需要分别调用 [`updateSelfPosition`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`updateRemotePosition`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音频。 ![](https://web-cdn.agora.io/docs-files/1663038259399) - 通过 SDK 计算媒体播放器的空间坐标。你需要在 [`LocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_ilocalspatialaudioengine) 类中分别调用 [`updateSelfPosition`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`updatePlayerPositionInfo`](/zh-CN/api-reference/rtc/flutter/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateplayerpositioninfo) 更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音频。 ![](https://web-cdn.agora.io/docs-files/1663038287220) #### 实时合唱 [#实时合唱-6] 该版本为实时合唱赋予了如下能力： - 支持两人及两人以上合唱。 - 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。 - 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。 该版本新增 `audioScenarioChorus` 枚举来设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。 #### 增强的频道管理 [#增强的频道管理-6] 为满足各类业务场景对频道管理的需求，该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 类中新增了如下功能： - 设置或切换多种音视频源的发布 - 设置或切换频道场景、用户角色 - 设置或切换订阅视频的大小流类型 - 控制音频发布时延 在调用 [`joinChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 或 [`joinChannelEx`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengineex_joinchannelex) 时设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions)，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_updatechannelmediaoptions) 随时更新 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中的设置，例如，切换发布的音视频源。 #### 屏幕共享 [#屏幕共享-12] 该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享。 在 Windows 和 macOS 平台： - 在加入频道前调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapturebydisplayid)，然后调用 [`joinChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 加入频道并设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `true`，即可开始屏幕共享。 - 在加入频道后调用 [`startScreenCaptureByDisplayId`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapturebydisplayid)，然后调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_updatechannelmediaoptions) 设置 `publishScreenTrack` 或 `publishSecondaryScreenTrack` 为 `true`，即可开始屏幕共享。 在 Android 和 iOS 平台： - 在加入频道前调用 [`startScreenCapture`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapture)，然后调用 [`joinChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 加入频道并设置 `publishScreenCaptureVideo` 为 `true`，即可开始屏幕共享。 - 在加入频道后调用 [`startScreenCapture`](/zh-CN/api-reference/rtc/flutter/video/screencapture#api_irtcengine_startscreencapture)，然后调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_updatechannelmediaoptions) 设置 `publishScreenCaptureVideo` 为 `true`，即可开始屏幕共享。 #### 设置音视频流订阅黑/白名单 [#设置音视频流订阅黑白名单-6] 该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通 [`RtcEngineEx`](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineex) 类下的同名方法来实现该功能。 - `setSubscribeAudioBlacklist`：设置音频订阅黑名单。 - `setSubscribeAudioWhitelist`：设置音频订阅白名单。 - `setSubscribeVideoBlacklist`：设置视频订阅黑名单。 - `setSubscribeVideoWhitelist`：设置视频订阅白名单。 如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。 #### 设置音频场景 [#设置音频场景-6] 为方便用户灵活修改音频场景，该版本新增 [`setAudioScenario`](/zh-CN/api-reference/rtc/flutter/audio/audio-basic#api_irtcengine_setaudioscenario) 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (`AudioScenarioDefault`) 切换为高音质场景 (`AudioScenarioGameStreaming`)，你可以调用该方法。 #### 设置本地代理 [#设置本地代理-6] 该本版新增 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/flutter/network#api_irtcengine_setlocalaccesspoint) 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。 #### 垫片推流 [#垫片推流-7] 该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 来开启该功能，并通过 `options` 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。 #### 本地合图 [#本地合图-11] 该版本新增本地合图功能，可支持在本地将多路视频流合并为一路视频流。常见场景如下： 在直播场景或使用旁路推流功能时，可以在本地将多个主播的画面合并为一个画面。 将本地采集的多路视频流 (例如：摄像头采集的视频、屏幕共享流、视频文件、图片等) 合并为一路视频流，然后在频道内发布已合图的视频流。 你可以调用 [`startLocalVideoTranscoder`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) 方法开启本地合图、调用 [`stopLocalVideoTranscoder`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#api_irtcengine_stoplocalvideotranscoder) 方法停止本地合图；在开启本地合图后，可以调用 [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 进行本地合图的配置更新。 #### 视频设备管理 [#视频设备管理-3] 视频采集设备可能支持多种视频格式，每一种格式都支持不同的视频帧宽度、视频帧高度、帧率组合。 该版本新增 [`numberOfCapabilities`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_ivideodevicemanager_numberofcapabilities) 和 [`getCapability`](/zh-CN/api-reference/rtc/flutter/device-management/video-device#api_ivideodevicemanager_getcapability) 方法，用于获取视频采集设备支持的视频格式数量以及指定视频格式下的视频帧详细信息。在调用 `startPrimaryCameraCapture` 或 `startSecondaryCameraCapture` 方法使用摄像头采集视频时，你可以使用指定的视频格式进行采集。 SDK 会根据你在 [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/flutter/class-videoencoderconfiguration) 中的设置，自动选择选择视频采集设备的最佳视频格式进行采集。一般情况下，你不需要用到该组新增方法。 ### 改进 [#改进-147] #### 快速切换频道 [#快速切换频道-6] 该版本通过 [`leaveChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_leavechannel2) 和 [`joinChannel`](/zh-CN/api-reference/rtc/flutter/channel#api_irtcengine_joinchannel2) 切换频道即可实现和 agora_rtc_engine: ^5.x 中 `switchChannel` 一样的切换速度，无需额外调用 `switchChannel` 方法。 #### 推送外部视频帧 [#推送外部视频帧-6] 该版本新增支持推送 I422 格式的外部视频帧，你可以通过 [`pushVideoFrame`](/zh-CN/api-reference/rtc/flutter/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe) 方法将 I422 格式的外部视频帧推送至 SDK。 #### 本地人声音调 [#本地人声音调-6] 该版本在 `onAudioVolumeIndication` 的 [`AudioVolumeInfo`](/zh-CN/api-reference/rtc/flutter/class-audiovolumeinfo) 中新增 `voicePitch` 参数。你可以通过 `voicePitch` 获取本地用户的人声音调，从而实现唱歌评分等业务功能。 #### 本地视频预览 [#本地视频预览-6] 该版本优化了 [`startPreview`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_startpreview2) 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 [`startPreview`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_startpreview2) 方法来开启视频预览，无调用时序要求。 #### 订阅视频流 [#订阅视频流-6] 你可以通过 [`setRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/flutter/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="react-native" /> ### 已知问题和局限性 [#已知问题和局限性-4] **AirPods Pro 蓝牙连接问题 (iOS)** 由于 AirPods Pro 不支持在通话音量模式下使用 A2DP 协议，可能会导致该设备在该模式下无法成功连接。 ## v4.6.4 [#v464-2] 该版本于 2026 年 8 月 31 日发布。 ### 升级必看 [#升级必看-89] #### iOS 27 横屏采集画面方向适配 (iOS) [#ios-27-横屏采集画面方向适配-ios-1] 在使用 Xcode 27 编译 App 并运行于 iOS 27.0 及以上系统时，由于声网 RTC SDK 旧版本依赖的界面方向相关系统 API，如 [`UIApplicationWillChangeStatusBarOrientationNotification`](https://developer.apple.com/documentation/uikit/uiapplication/willchangestatusbarorientationnotification)，在 iOS 27 中不再支持，导致 App 在横屏界面下启用摄像头采集时出现采集画面方向异常。该版本已完成新方案适配。 更多信息请参考 Apple 的 [iOS & iPadOS 27 Release Notes](https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-27-release-notes)。 ### 新增特性 [#新增特性-128] #### 视频采集 (Android) [#视频采集-android-1] 新增两个回调事件，用于通知 Android 广角 / 超广角摄像头采集开启的成功或失败。 ### 问题修复 [#问题修复-152] 该版本修复了以下问题： - 修复了断网后 `onNetworkQuality` 回调报告的网络质量可能不准确的问题。(Android, iOS) - 修复了接收端设置音频场景为`AUDIO_SCENARIO_AI_CLIENT`，发送端频繁停止和恢复发送音频流，当接收端网络不佳时偶现无声问题。(Android, iOS) - 修复了使用有线耳机进行音视频互动时，在特定音频路由配置场景下偶现音质变差的问题。(Android, iOS) - 修复了自渲染视频帧场景下，本地预览画面偶现卡住的问题。(Android, iOS) - 修复了在 Android 模拟器上部分场景下偶现回声的问题。(Android, iOS) - 修复了启用 Google 安全加固后，音视频互通过程中偶现 App 崩溃或无响应（ANR）的问题。(Android, iOS) - 修复了 Android 手表连接蓝牙耳机时，音频路由可能切换到外放的问题。(Android) - 修复了 App 集成调用 `setExternalVideoSource` 设置推送的外部视频源类型为已编码的视频帧（`ENCODED_VIDEO_FRAME`），推送的已编码视频帧包含的 SEI 信息长度如果与编码协议规定不匹配，偶现崩溃问题。(Android, iOS) - 修复了音视频互动场景下偶现 App 崩溃的问题。(Android) - 修复了 Web 与 Native 音视频互通场景下，偶现视频编码失败、远端视频卡顿或花屏的问题。(Android) - 修复了开启媒体播放器缓存后，在断网场景下播放已缓存资源时，可能延迟约 10 秒并回调错误的问题。(Android, iOS) - 修复了使用媒体播放器播放 CDN 流时，分辨率变化后偶现花屏的问题。(Android) - 修复了 App 以通信模式（`CHANNEL_PROFILE_COMMUNICATION`）加入频道后，调用 `updateChannelMediaOptions` 更新频道媒体选项后，NCS 和 RESTful API 返回的频道信息被错误识别为互动直播模式的问题。(Android, iOS) ## v4.6.2 [#v462-7] 该版本于 2026 年 3 月 5 日发布。 ### 升级必看 [#升级必看-90] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的废弃及删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 直推 CDN 相关接口废弃 [#直推-cdn-相关接口废弃-7] 该版本废弃直推 CDN 功能的相关接口，并会在后续版本中删除，请改用[服务端旁路推流](/zh-CN/realtime-media/media-push)。 - `setDirectCdnStreamingAudioConfiguration` - `setDirectCdnStreamingVideoConfiguration` - `startDirectCdnStreaming` - `stopDirectCdnStreaming` - `DirectCdnStreamingMediaOptions` - `DirectCdnStreamingStats` - `DirectCdnStreamingState` - `DirectCdnStreamingReason` #### 虚拟节拍器接口废弃 [#虚拟节拍器接口废弃-7] 该版本废弃虚拟节拍器功能的相关接口，并会在后续版本中删除。 - [`startRhythmPlayer`](/zh-CN/api-reference/rtc/react-native/play/rhythmplayer#api_irtcengine_startrhythmplayer) - [`configRhythmPlayer`](/zh-CN/api-reference/rtc/react-native/play/rhythmplayer#api_irtcengine_configrhythmplayer) - [`onRhythmPlayerStateChanged`](/zh-CN/api-reference/rtc/react-native/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) #### 水印接口废弃 [#水印接口废弃-7] 该版本废弃水印功能的相关接口，推荐使用该版本新增的水印接口。 - [`addVideoWatermark`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2) - [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex) #### 冗余接口删除 [#冗余接口删除-7] 该版本删除了下列冗余接口及参数： - `setLocalPublishFallbackOption` - `onLocalPublishFallbackToAudioOnly` - `onDownlinkNetworkInfoUpdated` - `onWlAccStats` - `enableWirelessAccelerate` #### 美妆功能实现变更 [#美妆功能实现变更-7] 受该版本美颜重构的影响，自 v4.6.2 起，不再支持调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/react-native/extension#api_irtcengine_setextensionproperty) 启用美妆功能，改用 `STYLE_MAKEUP` 节点实现。 #### 双流模式行为变更 [#双流模式行为变更-4] - v4.6.2 之前：发送端开启小流自适应模式 (AutoSimulcastStream) 时，不会主动发送小流，仅当主播身份的接收端调用 [`setRemoteVideoStreamType`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setremotevideostreamtype) 发起小流申请后，发送端收到申请才会开始发送小流。 - v4.6.2 及之后版本：发送端开启小流自适应模式 (AutoSimulcastStream) 时，会根据订阅端用户的下行网络质量，自动决定发送或停止发送小流。若将 **mode** 设置为其他发送模式或显式配置了小流的宽、高、码率或帧率，则此自适应功能失效。 #### 新增域名白名单 [#新增域名白名单-7] 如果你由之前的版本升级到 v4.6.2 且使用了域名白名单功能（`RtcEngineConfig` 下的 `domainLimit` 为 `true`），请在白名单中添加以下域名，以确保互通顺畅： - `*.rtnsvc.com` - `*.realtimemesh.com` #### EncodedVideoFrameInfo 结构体删除参数 uid [#encodedvideoframeinfo-结构体删除参数-uid-5] 该版本删除了 [`EncodedVideoFrameInfo`](/zh-CN/api-reference/rtc/react-native/class-encodedvideoframeinfo) 结构体中的 `uid` 参数。你可以直接从 [`onEncodedVideoFrameReceived`](/zh-CN/api-reference/rtc/react-native/video/video-encoded#callback_ivideoencodedframeobserver_onencodedvideoframereceived) 回调中获取 `uid` 信息。如果你之前集成过相关代码，请相应更新集成逻辑。 ### 新增特性 [#新增特性-129] #### 多路分辨率视频流 [#多路分辨率视频流-7] 该版本新增多路分辨率视频流（Adaptive Bitrate Video Streaming，简称 ABR）功能，支持对同一视频源设置同时发送多路不同分辨率的视频流，并支持多频道场景。接收端通过自动/手动订阅目标分辨率的视频流。 启用 ABR 后，你可以配置不同分辨率的视频流，（最多四层分辨率，一个最高分辨率的主流和三层其他较低分辨率的视频流），并设置视频流的分辨率、码率、是否启用分层推流回退等选项来灵活控制流的发布。启用分层推流回退后，SDK 会在弱网环境下自动回退到低分辨率的视频流，确保流畅的观看体验。订阅端可根据实际需求选择想要接收的视频流。适用于会议场景、大班课、互动直播等多终端、多网络环境，可显著提升弱网下的观看体验。 #### 多路径网络传输 [#多路径网络传输-7] 该版本新增多路径传输功能，适用于终端支持多网卡传输(比如 5G， Wi-Fi，LAN)的设备，可以有效降低甚至消除弱网带来的体验回退，适用于弱网环境、对传输稳定性要求高的实时音视频通信场景，如车载、IoT、火车、高速公路等复杂网络环境。通过在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 中设置 `enableMultipath` 为 `true`，可开启多路径传输能力。支持两种传输模式（[`MultipathMode`](/zh-CN/api-reference/rtc/react-native/enum-multipathmode)）： - 动态模式：（默认）根据网络状况动态选择最佳路径进行传输，适用于流量敏感、对体验要求比较高的场景，如会议、教育等。动态模式下，你可以通过 `preferMultipathType` 指定首选的网络传输路径（如优先 Wi-Fi 或移动网络）。 - 全冗余模式：数据会在所有可用网络路径上同时传输，适用于流量不敏感，对体验有极致要求的场景，如户外采播、平行操控等。该模式会产生额外费用，如需使用请[联系技术支持](https://ticket.shengwang.cn/)。 上下行还可分别通过 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 中的 `uplinkMultipathMode`、`downlinkMultipathMode` 配置。启用后，SDK 会通过回调 [`onMultipathStats`](/zh-CN/api-reference/rtc/react-native/network#callback_irtcengineeventhandler_onmultipathstats) 实时上报各路径的传输统计信息，包括每一个传输路径的流量消耗，便于开发者监控和优化网络表现。 #### 视频质量评分 [#视频质量评分-7] 该版本在 [`RemoteVideoStats`](/zh-CN/api-reference/rtc/react-native/class-remotevideostats) 中新增 `mosValue` 成员，报告声网实时视频 MOS（平均主观意见分）评估系统对接收到的远端视频流的质量评分。评分共有 5 个档次，5 分表示视频画质优秀，画面清晰无噪点，1 分表示视频画质极差，画面严重模糊。你可以通过该参数实时观测远端视频流的主观画质表现，便于动态调整视频参数、优化用户体验，或用于质量监控和告警等场景。如需启用该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 #### 支持添加多个水印 [#支持添加多个水印-7] 该版本废弃了 [`addVideoWatermark`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/watermark#api_irtcengine_addvideowatermark2) 和 [`addVideoWatermarkEx`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex) 方法，新增 [`addVideoWatermarkWithConfig`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/watermark#api_irtcengine_addvideowatermark3) 和 [`addVideoWatermarkWithConfigEx`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/watermark#api_irtcengineex_addvideowatermarkex1) 方法，支持通过水印 ID 来给视频添加多个水印，并可对水印进行排序。如果你需要移除指定水印，可调用 [`removeVideoWatermark`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/watermark#api_irtcengine_removevideowatermark) 方法。 #### Token 更新结果回调 [#token-更新结果回调-7] 该版本新增 [`onRenewTokenResult`](/zh-CN/api-reference/rtc/react-native/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调及 [`RenewTokenErrorCode`](/zh-CN/api-reference/rtc/react-native/enum-renewtokenerrorcode) 错误码。当调用 `renewToken` 方法更新 Token 后，SDK 会通过 [`onRenewTokenResult`](/zh-CN/api-reference/rtc/react-native/channel#callback_irtcengineeventhandler_onrenewtokenresult) 回调通知 Token 更新的结果，并通过 [`RenewTokenErrorCode`](/zh-CN/api-reference/rtc/react-native/enum-renewtokenerrorcode) 返回详细的错误码，开发者可在回调中根据错误码及时处理 Token 更新失败的场景。 #### Android 新增支持共享单个 App [#android-新增支持共享单个-app-3] 从 Android 14 开始，系统支持用户在屏幕共享时选择共享整个屏幕或共享单个 App，以提升隐私保护和多任务处理能力。 该版本适配了该系统能力，在支持共享整个屏幕的基础上，新增支持共享单个 App。同时，为便于管理相关事件，新增 [`onLocalVideoEvent`](/zh-CN/api-reference/rtc/react-native/video/video-basic#callback_irtcengineeventhandler_onlocalvideoevent) 回调，用于报告本地视频，尤其是屏幕共享相关的事件。 #### Android 新增权限被授予回调 [#android-新增权限被授予回调-3] 为便于确认屏幕共享场景下的权限授权情况，该版本新增 [`onPermissionGranted`](/zh-CN/api-reference/rtc/react-native/network#callback_irtcengineeventhandler_onpermissiongranted) 回调。你可以通过该回调判断当前用户授予的是相机（Camera）权限还是屏幕（Screen）权限。 #### Media Player 支持获取音频缓冲延迟 [#media-player-支持获取音频缓冲延迟-7] 为解决 K 歌场景中可能会出现的主唱与伴唱伴奏不同步的问题，该版本在 Media Player 模块中新增 [`getAudioBufferDelay`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-info#api_imediaplayer_getaudiobufferdelay) 方法，用于获取播放媒体文件时毫秒级的音频缓冲延迟。 #### 画中画功能 [#画中画功能-1] 该版本新增画中画（Picture-in-Picture，PiP）功能，支持将视频通话窗口以画中画模式显示，让用户在切换应用或返回主屏幕时仍能继续观看视频通话。 该功能支持自动进入画中画模式，并提供了丰富的配置选项。在 Android 平台上，你可以配置画中画窗口的宽高比、初始位置、无缝调整大小等参数；在 iOS 平台上，你可以配置视频流的布局方式（支持流式布局，视频流从左到右、从上到下排列）、画中画窗口的尺寸、系统控制按钮样式等。同时，该功能还支持通过 [`AgoraPipStateChangedObserver`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_agorapipstatechangedobserver) 监听画中画状态变化，便于及时处理进入、退出或失败等场景。适用于视频通话、在线教育、直播等需要多任务处理的场景，提升用户的使用体验。 #### 其他 [#其他-33] - 新增 [`setPlaybackAudioFrameBeforeMixingParameters`](/zh-CN/api-reference/rtc/react-native/audio/audio-raw#api_irtcengine_setplaybackaudioframebeforemixingparameters1) 方法用于设置 [`onPlaybackAudioFrameBeforeMixing`](/zh-CN/api-reference/rtc/react-native/audio/audio-raw#callback_iaudioframeobserver_onplaybackaudioframebeforemixing) 回调中返回的音频帧格式，包括采样率、声道数以及每次回调的数据采样点数。调用此方法后，SDK 会按照设定的参数返回混音前的原始音频数据，便于开发者进行自定义处理或分析。 - 新增 [`preloadEffectEx`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengineex_preloadeffectex) 方法，用于将指定音效文件预加载到指定频道，支持本地或在线音效文件，便于后续快速播放，适合多频道场景。 - 新增 [`playEffectEx`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengineex_playeffectex) 方法，用于在指定频道播放音效文件，支持设置循环次数、音调、空间位置、音量、是否发布到频道及播放起始位置等参数，满足丰富的音效播放需求。 - 本地截图上传功能支持通过 [`ContentInspectModule`](/zh-CN/api-reference/rtc/react-native/class-contentinspectmodule) 中新增的 `position` 成员设置截图的视频观测位置，从而实现对原始视频数据或效果处理前后的视频流进行截图并上传。 - 为了提升用户使用绿幕或蓝幕开启虚拟背景功能时，人像分割的准确性和稳定性，该版本在 [`SegmentationProperty`](/zh-CN/api-reference/rtc/react-native/class-segmentationproperty) 中新增 `screenColorType` 属性，支持指定背景幕布的颜色为绿色、蓝色或自动识别。 ### 改进 [#改进-148] #### 美颜重构 [#美颜重构-7] 该版本对美颜功能进行了彻底重构和升级，不仅拓展了美颜功能，提升了美颜效果和性能，还解决了美颜参数配置复杂、集成成本高、美颜资源依赖网络易失效等痛点。主要改进包括： - **新增美颜功能**：新增白牙、去法令纹、去黑眼圈、亮眼等美肤功能；美妆特效新增卧蚕和面部高光；美型功能从 11 个增加到 29 个。 - **API 大幅简化**：将过去版本中的基础美颜、美型、美妆、滤镜功能整合为 `BEAUTY`、`STYLE_MAKEUP`、`FILTER` 三个核心节点 (node)，通过 [`IVideoEffectObject`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_ivideoeffectobject) 统一管理生命周期和参数设置，减少频繁 API 调用带来的性能负担。 - **预设模板开箱即用**：提供多套预设风格模板（如"自然美颜"、"学姐妆"、"冷白滤镜"），大幅简化集成流程，无需手动调试数十项参数。 - **美颜参数动态控制**：该版本新增实时获取美颜参数的能力，开发者可通过 key-value 方式动态读取或修改任意细粒度参数（如磨皮强度、口红类型）。同时支持：调用预设模板快速启用风格效果、保存主播自定义参数配置、随时重置参数至默认状态，极大提升了业务层状态同步的灵活性和开发效率。 - **美颜资源外置**：该版本通过美颜资源外置化设计，将所有美颜资源（特效、滤镜、妆容）均打包为本地 bundle 文件，彻底消除因网络下载失败导致美颜失效的风险。 #### playEffect 支持无缝切换 [#playeffect-支持无缝切换-7] 该版本新增支持音效文件的无缝切换。对于同一个音效文件，如果先调用 [`preloadEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_preloadeffect) 再调用 [`playEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_playeffect3)，在播放完成或通过 [`stopEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_stopeffect) 停止播放后，SDK 不会关闭该音效文件。当再次调用 [`playEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_playeffect3) 时，SDK 会直接复用已加载的文件进行播放，从而实现循环播放和无缝切换。该能力同样适用于多频道场景。 #### 屏蔽窗口支持第二屏幕 [#屏蔽窗口支持第二屏幕-4] 在 4.6.2 之前的版本中，通过屏幕 ID（`startScreenCaptureByDisplayId`）进行屏幕共享时，不支持在多屏场景下配置屏蔽窗口（`ScreenCaptureParameters` 中的 `excludeWindowList`）。为提升屏幕共享体验，该版本新增支持该配置。 同时，为便于识别屏幕共享过程中屏蔽窗口的状态，该版本在 [`LocalVideoStreamReason`](/zh-CN/api-reference/rtc/react-native/enum-localvideostreamreason) 中新增 `LocalVideoStreamReasonScreenCaptureExcludeWindowFailed`，用于报告屏幕共享屏蔽窗口失败的情况。 #### onVideoDeviceStateChanged 回调时机优化 [#onvideodevicestatechanged-回调时机优化-4] 该版本优化了 `onVideoDeviceStateChanged` 回调的触发时机。在此前版本中，该回调仅在加入频道后才能触发。从 4.6.2 起，在 [`IRtcEngine`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) 完成初始化后即可收到一次该回调，加入频道后仍可继续监听该事件。 #### onNetworkQuality 准确性提升 [#onnetworkquality-准确性提升-5] 该版本提升了 [`onNetworkQuality`](/zh-CN/api-reference/rtc/react-native/network#callback_irtcengineeventhandler_onnetworkquality) 回调中网络质量评估的准确性，使回调数据更贴近用户的主观体验。 #### onPlaybackAudioFrame 支持 24k 采样率的音频帧 [#onplaybackaudioframe-支持-24k-采样率的音频帧-6] 该版本在 [`onPlaybackAudioFrame`](/zh-CN/api-reference/rtc/react-native/audio/audio-raw#callback_iaudioframeobserverbase_onplaybackaudioframe) 中新增支持采样率为 **24000 Hz** 的音频数据。在调用 [`setPlaybackAudioFrameParameters`](/zh-CN/api-reference/rtc/react-native/audio/audio-raw#api_irtcengine_setplaybackaudioframeparameters) 设置播放音频数据格式时，可以将 `sampleRate` 设为 `24000`。 #### onEncodedVideoFrameReceived 回调支持获取频道 ID [#onencodedvideoframereceived-回调支持获取频道-id-6] 该版本在 [`onEncodedVideoFrameReceived`](/zh-CN/api-reference/rtc/react-native/video/video-encoded#callback_ivideoencodedframeobserver_onencodedvideoframereceived) 回调中新增 `channelId` 参数，方便你在获取编码后视频数据时识别其所属频道。 #### 其他改进 [#其他改进-63] - 优化了在 Windows 11 24H2 及后续版本上的权限请求，避免非必要地获取位置信息。 - 在与 Web 端互通时，新增对 g711 和 g722 音频编解码器的支持，进一步提升了跨平台音频播放的兼容性和清晰度。 - 优化了屏幕共享文档场景下的共享视频清晰度。 - 该版本新增错误码 `ErrPcmSendFormat` (200) 和 `ErrPcmSendBufferOverflow` (201)，用于报告 PCM 数据发送相关错误。 ### 问题修复 [#问题修复-153] 该合并版本修复了以下问题： - 开启导唱功能播放多音轨歌曲时，调用 [`setAudioPitch`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setaudiopitch) 方法调整歌曲音调后出现杂音。 - 主播端调用 [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/react-native/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 创建自定义音频采集轨道并将 `trackType` 设为 `AudioTrackDirect`，调用 [`pushAudioFrame`](/zh-CN/api-reference/rtc/react-native/audio/audio-custom-capturenrendering#api_imediaengine_pushaudioframe) 将自采集音频推送到频道内，然后调用 [`playEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效，频道内的观众听主播的音频有杂音。 - 集成了 SDK 的 App 在音视频互动过程中偶现主线程阻塞导致的 UI 卡顿。 - 应用程序共享外接屏幕的视频流，断开外接屏幕连接后偶现应用程序崩溃。 - 调用 [`openWithMediaSource`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 并通过 `source` 参数将 `isLiveSource` 设为 `true` 并播放纯视频流，播放失败。 - 发送端传输多声道编码音频时，接收端偶现杂音。 - App 集成媒体播放器场景下，先后两次调用 [`open`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-open#api_imediaplayer_open) 打开不同媒体资源，第二次打开时，媒体播放器信息变化回调 [`onPlayerInfoUpdated`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerinfoupdated) 返回第一次媒体资源的信息，不符合预期。 - 调用 [`enableAudioVolumeIndication`](/zh-CN/api-reference/rtc/react-native/audio/audio-basic#api_irtcengine_enableaudiovolumeindication) 启用用户音量提示本地发流用户和远端用户音量相关信息，用户音量提示回调 `onAudioVolumeIndication` 返回的本地用户音量为 0。 - 使用 21:9 的显示屏（带鱼屏）进行音视频互通和屏幕共享场景下，设置高分辨率，如 3840*2160，屏幕共享画面在本地预览和接收端显示被裁剪。 - App 调用 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 启用垫片推流功能，偶现发送端推流成功但是 [`onVideoPublishStateChanged`](/zh-CN/api-reference/rtc/react-native/video/video-basic#callback_irtcengineeventhandler_onvideopublishstatechanged) 返回当前的发布状态不是 `PublishStatePublished`，不符合预期。 - 多频道场景下，App 在调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengineex_joinchannelex) 成功前调用 `setupRemoteVideoEx` 初始化远端用户视图，偶现远端用户视图首帧图像显示延时大。 - 调用 [`open`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-open#api_imediaplayer_open) 打开在线音效文件后，调用 [`playEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_playeffect3) 开始播放，当调用 [`seek`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定播放位置后，音效文件会从头开始播放。 - 在媒体音量模式下，主播在频道中发布麦克风采集的音频流，同时调用 [`playEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_playeffect3) 播放音效文件、调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_irtcengine_startaudiomixing2) 播放音乐文件，偶现回声。 - 调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengineex_joinchannelex) 加入频道，然后调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 开始跨频道媒体流转发，下麦、退出频道后重新加入频道开始连麦，偶现 [`onChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) 回调报告 `state` 为 `RelayStateFailure`，`code` 为 `RelayErrorServerErrorResponse`。 - 部分机型的笔记本电脑开启节能模式下，发送端共享屏幕和音频，偶现接收端听到回声。 - 在线教育场景下，偶现教师端本地看多个学生端音画不同步。 - 第二次调用 `enumerateVideoDevices` 接口获取设备列表不生效。 - Windows 7 设备上共享 PPT 窗口，当 PPT 以全屏自动播放模式运行且包含大量动画时，远端看到的画面有概率出现闪烁。 ## v4.5.2(对应 Native v4.5.1) [#v452对应-native-v451-1] 该版本于 2025 年 3 月 13 日发布。 ### 新增特性 [#新增特性-130] #### AI 对话场景 [#ai-对话场景-7] 该版本新增了专为与[声网对话式 AI 引擎](/zh-CN/ai)创建的智能体互动设计的 `AudioScenarioAiClient` 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。 ### 改进 [#改进-149] 1. 优化了特定机型上 SDK 初始化的耗时。(iOS) ### 问题修复 [#问题修复-154] 该版本修复了以下问题： - 集成 SDK 的 App 设置 `targetSdkVersion` 为 34，在 Android 14 系统上首次开启屏幕共享进行授权时出现崩溃。(Android) - 同时加入两个及以上的频道，连续调用 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。 - 使用媒体播放器时，调用 [`pause`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 定位到指定播放位置、然后调用 [`play`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。 - 使用媒体播放器时，调用 [`switchSrc`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换媒体资源后，调用 [`getPlaySrc`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-info#api_imediaplayer_getplaysrc_imediaplayer) 获取当前正在播放的媒体资源的路径没有变化。 - 用户在特定机型上进行音视频互动并使用蓝牙耳机，偶现调整手机音量后改变的是媒体音量而非蓝牙音量。(Android) - 音视频互动时，偶现接收端观看发送端画面出现黑屏。(Android) - 在特定机型上，调用 [`setCameraExposureFactor`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_setcameraexposurefactor) 在设备的某个特定角度设置当前摄像头的曝光系数后，当设备移动到另一个角度时，偶现视频画面变暗。(Android) - 播放 CDN 直播流时，直播流短暂中断后恢复，偶现播放画面长时间卡住。(Android) - 在推送 i420 格式的视频帧到频道内时，使用 CVPixelBuffer 会导致崩溃。(iOS) - 设置两个视图（view）后调用 [`enableFaceDetection`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/face-detection#api_irtcengine_enablefacedetection) 开启人脸检测，后传入的视图中无法检测到人脸信息。(iOS) - 屏幕共享场景下，接收端用户看到的共享图像出现绿线。(iOS) - 在极速直播场景下，观众通过 `string` 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。 - 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。 ## v4.5.0 [#v450-7] 该版本于 2024 年 12 月 10 日发布。 ### 升级必看 [#升级必看-91] 该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 强效视频降噪实现变更 [#强效视频降噪实现变更-7] 该版本调整了强效视频降噪的实现方式，在 [`VideoDenoiserLevel`](/zh-CN/api-reference/rtc/react-native/enum-videodenoiserlevel) 中删除了 `VidoDenoiserLevelStrength`，改为调用 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 启用视频降噪后，调用 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)。 此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 [`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)。 #### 视频编码偏好变更 [#视频编码偏好变更-7] 为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好： - 在 [`CompressionPreference`](/zh-CN/api-reference/rtc/react-native/enum-compressionpreference) 枚举类中新增 `PreferCompressionAuto` (-1) 枚举，并替代原有的 `PreferQuality` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `PreferLowLatency` 或 `PreferQuality`，以获得最佳的用户体验。 - 在 [`DegradationPreference`](/zh-CN/api-reference/rtc/react-native/enum-degradationpreference) 枚举类中新增 `MaintainAuto` (-1) 枚举，并替代原有的 `MaintainQuality` (1) 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `MaintainFramerate`、`MaintainBalanced` 或 `MaintainResolution`，以获得最优的综合质量体验 (QoE)。 ### 新增特性 [#新增特性-131] #### 高级美颜 [#高级美颜-7] 该版本新增以下两种高级美颜功能： - 美型：调用 [`setFaceShapeBeautyOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 [`setFaceShapeAreaOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapeareaoptions) 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。 - 美妆：调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/react-native/extension#api_irtcengine_setextensionproperty) 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。 :::info[信息] 目前，高级美颜功能为**限时免费**，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 秀场直播场景 [#秀场直播场景-7] 该版本在 [`VideoApplicationScenarioType`](/zh-CN/api-reference/rtc/react-native/enum-videoapplicationscenariotype) 类下新增枚举 `ApplicationScenarioLiveshow`(3)（秀场直播），你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为[秀场直播](/zh-CN/solutions/showroom)。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，重点提升了首帧出图体验和画质表现，同时增强了在弱网环境和低端设备上的画质和流畅度表现。 #### 限制视频渲染帧率 [#限制视频渲染帧率-7] 该版本新增 [`setLocalRenderTargetFps`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#api_irtcengine_setlocalrendertargetfps) 和 [`setRemoteRenderTargetFps`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#api_irtcengine_setremoterendertargetfps) 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。 在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。 #### 滤镜效果 [#滤镜效果-7] 该版本新增 [`setFilterEffectOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setfiltereffectoptions) 方法，你可以在 `config` 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 `built_in_whiten_filter.cube` 文件，用于快速实现美白滤镜效果。 #### 本地音频合流 [#本地音频合流-7] 该版本新增本地音频合流功能，你可以调用 [`startLocalAudioMixer`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/audiomixer#api_irtcengine_startlocalaudiomixer) 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 [`stopLocalAudioMixer`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/audiomixer#api_irtcengine_stoplocalaudiomixer) 方法停止本地音频合流；在合流过程中，可以调用 [`updateLocalAudioMixerConfiguration`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/audiomixer#api_irtcengine_updatelocalaudiomixerconfiguration) 方法更新正在合流的音频流配置。 该功能的使用场景示例如下： - 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。 - 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。 - 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。 #### 外部 MediaProjection (Android) [#外部-mediaprojection-android-2] 该版本新增 [`setExternalMediaProjection`](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_setexternalmediaprojection) 方法，该方法支持你自行设置外部 `MediaProjection`，并取代 SDK 申请的 `MediaProjection`。 如果你具备自行申请 `MediaProjection` 的开发能力，可通过该功能实现更加灵活的屏幕采集。 #### EGL 环境上下文 (Android) [#egl-环境上下文-android-2] 该版本新增了 [`setExternalRemoteEglContext`](/zh-CN/api-reference/rtc/react-native/video/video-custom-capturenrendering#api_irtcengine_setexternalremoteeglcontext) 方法，用于设置远端视频流渲染的 EGL 环境上下文。使用 Texture 格式的视频数据进行远端视频自渲染时，你可以通过该方法替换 SDK 默认的远端 EGL 环境上下文，实现统一的 EGL 上下文管理。 #### 色彩空间设置 [#色彩空间设置-7] 该版本在 [`VideoFrame`](/zh-CN/api-reference/rtc/react-native/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/react-native/class-externalvideoframe) 中新增了 `colorSpace`，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。 #### 其他 [#其他-34] - [`MediaDeviceStateType`](/zh-CN/api-reference/rtc/react-native/enum-mediadevicestatetype) 新增 `MediaDeviceStatePluggedIn` 枚举，表示设备已插入。 ### 改进 [#改进-150] #### 虚拟背景算法优化 [#虚拟背景算法优化-14] 该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。 #### 录制本地预览视频 [#录制本地预览视频-7] 该版本在 [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/react-native/class-recorderstreaminfo) 中新增 `type` 成员。当调用 [`createMediaRecorder`](/zh-CN/api-reference/rtc/react-native/recording#api_irtcengine_createmediarecorder) 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 [`MediaRecorderConfiguration`](/zh-CN/api-reference/rtc/react-native/class-mediarecorderconfiguration) 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 [`startRecording`](/zh-CN/api-reference/rtc/react-native/recording#api_imediarecorder_startrecording) 即可开始录制本地预览的视频。 #### 指定视频观测位置截图 [#指定视频观测位置截图-7] 该版本新增 [`takeSnapshotWithConfig`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/snapshot#api_irtcengine_takesnapshot2) 和 [`takeSnapshotWithConfigEx`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex2) 方法，你可以在调用该方法时通过 `config` 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。 #### 自定义音频采集改进 [#自定义音频采集改进-7] 该版本在 [`AudioTrackConfig`](/zh-CN/api-reference/rtc/react-native/class-audiotrackconfig) 中新增了 `enableAudioProcessing` 成员参数，用于控制是否对 `AudioTrackDirect` 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 `false`，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。 #### 其他改进 [#其他改进-64] - 通过拼接视频帧和 Alpha 数据实现 Alpha 透明特效的应用场景下，提升了接收端的渲染性能，有效减少卡顿和延迟。 - 优化了调用 [`queryDeviceScore`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_querydevicescore) 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。 - 调用 [`switchSrc`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 [`onPlayerEvent`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent) 回调报告 `PlayerEventSwitchError` 事件，表示媒体资源切换时发生错误。 - 调用 [`setPlaybackSpeed`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，最低支持 0.3 倍速播放。 ### 问题修复 [#问题修复-155] 该版本修复了以下问题： - 当发送端视频源类型为 JPEG 格式时，偶现接收端帧率低于预期。 - 在播放音乐内容中心的音乐资源时，偶现杂音和卡顿。(Android) - 在 App 没有获取麦克风权限时，通过 [`IMusicPlayer`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imusicplayer) 播放伴奏音乐偶现卡顿。(Android) - 音视频互动过程中被系统来电打断后，通过 `onAudioVolumeIndication` 回调上报的用户音量错误。(Android) - 在接收端默认订阅视频小流、加入频道时不自动订阅任何视频流的前提下，加入频道后调用 `muteRemoteVideoStream(uid,false)` 恢复接收视频流，但接收到的视频流为视频大流，不符合预期。(Android) - 音视频互动过程中，偶现接收端听发送端没有声音。(iOS) - 音视频互动过程中，如果发送端设备的系统版本为 iOS 17，偶现接收端听不到来自发送端的声音。(iOS) - 直播场景下，观众端因切换网络导致断开连接，重新连接直播间花费的时间长于预期。(iOS) - App 启动后使用媒体播放器播放在线媒体资源，播放无声。(iOS) - 音视频互动过程中被系统其他 App 打断后恢复，偶现音频采集无声。(iOS) - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_irtcengine_startaudiomixing2)后，立即调用 [`pauseAudioMixing`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_irtcengine_pauseaudiomixing) 暂停播放音乐文件不生效。 - 音视频互动过程中偶现崩溃。(Android) ## v4.4.0 [#v440-8] 该版本于 2024 年 8 月 29 日发布。 ### 升级必看 [#升级必看-92] 该版本对部分功能的实现方式进行了优化，包括 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 1. 为区分不同插件回调中的上下文信息，该版本将原有的插件相关回调删除并新增可标识插件上下文信息的对应回调（见下表），你可以通过各回调中的 [`ExtensionContext`](/zh-CN/api-reference/rtc/react-native/class-extensioncontext) 了解插件的名称、使用该插件的用户 ID、和提供插件的服务商名等信息。 | 原有回调 | 现有回调 | | -------- | ------------------------------- | | `onExtensionEvent` | [`onExtensionEventWithContext`](/zh-CN/api-reference/rtc/react-native/extension#callback_irtcengineeventhandler_onextensioneventwithcontext) | | `onExtensionStarted` | [`onExtensionStartedWithContext`](/zh-CN/api-reference/rtc/react-native/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) | | `onExtensionStopped` | [`onExtensionStoppedWithContext`](/zh-CN/api-reference/rtc/react-native/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext) | | `onExtensionError` | [`onExtensionErrorWithContext`](/zh-CN/api-reference/rtc/react-native/extension#callback_irtcengineeventhandler_onextensionerrorwithcontext) | 2. 该版本修改了 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/react-native/class-externalvideoframe) 中的以下成员名称： - `d3d11_texture_2d` 更名为 `d3d11Texture2d`。 - `texture_slice_index` 更名为 `textureSliceIndex`。 - `metadata_buffer` 更名为 `metadataBuffer`。 - `metadata_size` 更名为 `metadataSize`。 ### 新增特性 [#新增特性-132] #### Alpha 透明特效 [#alpha-透明特效-5] 该版本新增 Alpha 透明特效功能，支持在 SDK 采集和自定义采集视频的场景下，在发送端发布视频帧的 Alpha 通道、在接收端对 Alpha 通道进行渲染处理，实现透明礼物特效、接收端自定义主播背景等： - [`VideoFrame`](/zh-CN/api-reference/rtc/react-native/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/react-native/class-externalvideoframe) 中新增 `alphaBuffer`：设置 Alpha 通道数据。 - [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/react-native/class-externalvideoframe) 中新增 `fillAlphaBuffer`：对于 BGRA 或 RGBA 格式的视频数据，设置是否自动提取 Alpha 通道数据并填入到 `alphaBuffer` 中。 - [`VideoFrame`](/zh-CN/api-reference/rtc/react-native/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/react-native/class-externalvideoframe) 中新增 `alphaStitchMode`：设置 `alphaBuffer` 和视频帧拼接的相对位置。 另外，[`AdvanceOptions`](/zh-CN/api-reference/rtc/react-native/class-advanceoptions) 中新增成员 `encodeAlpha`，用于设置是否将 Alpha 信息编码并发送到远端。SDK 默认不对 Alpha 信息进行编码发送；如果需要对 Alpha 信息编码发送至远端（例如开启了虚拟背景功能），请显式调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 设置视频编码属性，并将 `encodeAlpha` 设置为 `true`。 #### AI 调音器 [#ai-调音器-7] 该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 [`enableVoiceAITuner`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/audio-effect#api_irtcengine_enablevoiceaituner) 方法并传入 [`VoiceAiTunerType`](/zh-CN/api-reference/rtc/react-native/enum-voiceaitunertype) 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。 #### 1v1 视频通话场景 [#1v1-视频通话场景-7] 该版本在 [`VideoApplicationScenarioType`](/zh-CN/api-reference/rtc/react-native/enum-videoapplicationscenariotype) 类下新增枚举 `ApplicationScenario1v1`（1v1 视频通话）。你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为 1v1 视频通话，针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。 #### 版权音乐优化 [#版权音乐优化-2] - 该版本新增 [`setPlayMode`](/zh-CN/api-reference/rtc/react-native/play/drm#api_imusicplayer_setplaymode) 方法，用于设置音乐资源的播放模式。在在线 K 歌房等场景下，你可以根据需求启用伴唱、原唱或导唱模式。 - 该版本新增 [`destroyMusicPlayer`](/zh-CN/api-reference/rtc/react-native/play/drm#api_imusiccontentcenter_destroymusicplayer) 方法，用于销毁音乐播放器并释放相应的资源。 ### 改进 [#改进-151] #### 自适应硬解支持 (Android) [#自适应硬解支持-android] 该版本新增自适应硬解支持，改进了低端机的渲染流畅性，有效降低系统负载。 #### 人脸区域美颜 [#人脸区域美颜-7] 为了避免磨皮美颜程度较高时丢失非脸部区域的细节，该版本改进了磨皮美颜效果的实现算法。磨皮美颜现在会识别人脸的各个部位，应用在除嘴巴、眼睛和眉毛之外的人脸皮肤区域，且支持最多同时对两张人脸磨皮。 #### 其他改进 [#其他改进-65] 该版本还进行了如下改进： - 优化了传输策略，调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#api_irtcengine_enableinstantmediarendering) 不再对传输链路的安全性产生影响。 - 该版本在 [`Metadata`](/zh-CN/api-reference/rtc/react-native/class-metadata) 中新增 `channelId` 参数，用于获取发送 Metadata 的源频道名称。 - 废弃了 [`ClientRoleChangeFailedReason`](/zh-CN/api-reference/rtc/react-native/enum-clientrolechangefailedreason) 中的冗余枚举值 `ClientRoleChangeFailedRequestTimeOut`、`ClientRoleChangeFailedConnectionFailed`。 ### 问题修复 [#问题修复-156] 该版本修复了以下问题： - 在实时互动过程中，当多个远端同时加入频道时 App 偶现崩溃。(iOS) - App 切后台一段时间、然后返回前台时，远端视频画面偶现卡住或花屏。(iOS) - 发送端调用 `startDirectCdnStreaming` 开始直接向 CDN 推流后，频繁开关或切换网络，偶现接收端黑屏但发送端未收到推流失败回调。(iOS) - 调用 [`pushAudioFrame`](/zh-CN/api-reference/rtc/react-native/audio/audio-custom-capturenrendering#api_imediaengine_pushaudioframe) 推送外部音频数据，外部音频渲染的采样率如果不是 SDK 推荐的值时，比如 22050 Hz 和 11025 Hz，声音播放失败。 ## v4.3.2 [#v432-6] 该版本于 2024 年 6 月 6 日发布。 ### 升级必看 [#升级必看-93] 该版本修改了播放版权音乐的行为，当调用 [`IMusicPlayer`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imusicplayer) 中的 [`play`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 方法播放版权音乐媒体文件时，存在以下行为变更： - v4.3.2 以前版本：SDK 默认播放当前音频文件的第一个音轨。 - v4.3.2：SDK 默认播放伴奏。 ### 改进 [#改进-152] 提升了 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_setremotesubscribefallbackoption) 方法的易用性，取消了调用时序要求，即：在加入频道前后，均可调用 [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_setremotesubscribefallbackoption) 动态切换弱网环境下的音视频流回退选项。 ### 问题修复 [#问题修复-157] 该版本修复了以下问题： - App 长时间切后台再返回前台时，远端视频画面卡住或花屏。(iOS) - 部分 iPad 设备上的本地预览画面旋转 90°，不符合预期。(iOS) - 音视频互动过程中偶现视频流畅度不佳。 - 接收端 App 解码后的视频分辨率为奇数时偶现 App 崩溃。 - 首次安装 App 或重启系统后，打开 App 并开启屏幕共享时出现崩溃。(Android) - 接听系统电话时加入频道，挂断电话后，本地音频采集失败，远端用户听不到声音。(Android) - 在部分机型（例如：红米 Note8）上进行互动的过程中接听系统来电并挂断后，本地播放媒体文件无声、听远端无声。(Android) - 远端用户离开频道时偶现崩溃。 - 调用 播放音乐文件，音乐文件播放结束后偶现无法触发 [`onAudioMixingStateChanged`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#callback_irtcengineeventhandler_onaudiomixingstatechanged)(AudioMixingStateStopped,AudioMixingReasonAllLoopsCompleted) 回调报告音乐文件播放完毕。(iOS) - 调用 [`playEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_playeffect3) 播放时长不足 1 秒的音效文件并设置不循环播放（ `loopCount` 为 0 ）时，出现无声。(iOS) - 使用媒体播放器播放视频，暂停播放后恢复播放，偶现短暂无声。(iOS) ## v4.3.1 [#v431-6] 该版本于 2024 年 5 月 9 日发布。 ### 新增特性 [#新增特性-133] #### 隐私清单文件 (iOS) [#隐私清单文件-ios-2] 为满足 Apple 对于 App 发布的安全合规要求，SDK 自该版本起新增隐私清单文件 `PrivacyInfo.xcprivacy`，其中包含 SDK 中需要访问或使用用户数据的 API 调用说明和 SDK 采集的数据类型说明。 **注：** 如果你需要将集成 v4.3.1 之前的 SDK 版本的 App 发布到苹果应用商店，则需要在 Xcode 工程中手动添加 `PrivacyInfo.xcprivacy` 文件。详见[如何在 App 中增加隐私清单？](/zh-CN/reference/faq/other/ios_privacy_manifest) #### 人像锁定 (iOS) [#人像锁定-ios] 为提升在线会议、秀场、在线教育等场景中的主播演讲效果，该版本新增 [`enableCameraCenterStage`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) 方法开启人像锁定功能。该功能可确保主播无论移动与否，始终位于画面中心，以取得良好的演讲效果。 在开启人像锁定前，建议你先调用 [`isCameraCenterStageSupported`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) 查询当前设备性能是否支持该功能。支持的设备清单可参考 [`API 文档`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage)。 #### 摄像头防抖 (iOS) [#摄像头防抖-ios-2] 为改善在移动拍摄、暗光环境拍摄、手持拍摄等场景下的视频画面稳定性，该版本新增摄像头防抖功能。你可以调用 [`setCameraStabilizationMode`](/zh-CN/api-reference/rtc/react-native/video/camera-capture#api_irtcengine_setcamerastabilizationmode) 开启该功能并设置适合的防抖模式，以获得更加稳定、清晰的视频画面。 #### 摄像头广角和超广角 [#摄像头广角和超广角-2] 为了让用户捕捉到更宽阔的视野和更完整的画面内容，该版本新增了对广角和超广角摄像头的支持。你可以先调用 [`queryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 查询设备支持的焦距能力，然后调用 [`setCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 并将 `cameraFocalLengthType` 设置为支持的焦距类型，包括广角、超广角等。 #### 摄像头多路采集 (Android) [#摄像头多路采集-android-2] 该版本针对 Android 摄像头采集新增以下功能： 1. 支持第三个和第四个摄像头视频流的采集和发布。 - [`VideoSourceType`](/zh-CN/api-reference/rtc/react-native/enum-videosourcetype) 中的 `VideoSourceCameraThird`(11) 和 `VideoSourceCameraFourth`(12) 枚举新增对 Android 的支持，分别用于指定视频源为第三个和第四个摄像头。此项改动允许你在调用 [`startCameraCapture`](/zh-CN/api-reference/rtc/react-native/video/camera-capture#api_irtcengine_startcameracapture) 开启摄像头采集时，指定最多 4 路摄像头采集的视频流。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 中的 `publishThirdCameraTrack` 和 `publishFourthCameraTrack` 成员新增对 Android 的支持。调用 [`joinChannel`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_joinchannel2) 加入频道时，将这两个成员参数设置为 `true` 即可在频道内发布第三个和第四个摄像头采集的视频流。 2. 支持通过摄像头 ID 指定摄像头。 在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/react-native/class-cameracapturerconfiguration) 中新增 `cameraId` 成员。对于多摄像头的设备，`cameraDirection` 无法识别或访问全部可用摄像头。这种情况下，你通过系统 API 获取摄像头 ID，再调用 [`startCameraCapture`](/zh-CN/api-reference/rtc/react-native/video/camera-capture#api_irtcengine_startcameracapture) 并传入 `cameraId` 指定摄像头。 #### 数据流加密 [#数据流加密-8] 该版本在 [`EncryptionConfig`](/zh-CN/api-reference/rtc/react-native/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` 成员用于启用数据流加密。你可以在调用 [`enableEncryption`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_enableencryption) 开启加密时来进行设置。如果在数据流加密或解密的过程中遇到问题导致失败，你可以通过新增的 `EncryptionErrorDatastreamDecryptionFailure` 和 `EncryptionErrorDatastreamEncryptionFailure` 枚举得知。 #### 视频小流自适应配置 [#视频小流自适应配置-7] 该版本新增视频小流的自适应配置功能，当你调用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setdualstreammode2) 在发送端设置双流模式并设置视频小流时，SDK 的默认行为如下所示： - 将视频小流的默认编码分辨率设为原始视频编码分辨率的 50%。 - 视频小流的码率根据视频分辨率和帧率自动匹配，无需指定。 #### 其他 [#其他-35] - 新增 [`enableEncryptionEx`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengineex_enableencryptionex) 方法，用于多频道场景下开启媒体流或数据流加密。 - 新增 [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) 方法，用于设置音乐文件的播放速度。 - 新增 [`getCallIdEx`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengineex_getcallidex) 方法，用于多频道场景下获取通话 ID。 ### 改进 [#改进-153] #### 虚拟背景算法优化 [#虚拟背景算法优化-15] 为了提高纯色背景下开启虚拟背景时人像分割的精确度和稳定性，该版本优化了绿幕分割算法： - 支持识别任意纯色背景，不再局限于绿幕。 - 对背景颜色的识别更加准确，并且在分割人像时露出的背景更少。 - 分割后的人像边缘（尤其是手指边缘）更加稳定，显著减少边缘的画面闪动现象。 #### 降低耳返的 CPU 消耗 [#降低耳返的-cpu-消耗-7] 该版本在 [`EarMonitoringFilterType`](/zh-CN/api-reference/rtc/react-native/enum-earmonitoringfiltertype) 中新增 `EarMonitoringFilterReusePostProcessingFilter`(`1 << 15`) 枚举。针对复杂的音效处理场景，你可以指定该选项，复用发送端音效处理后的 Audio filter，从而降低 CPU 的消耗。需要注意的是该选项会导致耳返延迟增加，适用于对耳返延迟不敏感的使用场景。 #### 其他改进 [#其他改进-66] 该版本还进行了如下改进： - 优化了非屏幕共享场景的视频编解码策略，节省系统性能开销。(iOS) - 提升了本地合图功能的性能和稳定性，并降低了该功能对 CPU 的占用率。(Android) - 优化了媒体播放器对 WebM 格式视频的处理能力，支持渲染 Alpha 通道。 - 在 [`AudioEffectPreset`](/zh-CN/api-reference/rtc/react-native/enum-audioeffectpreset) 中新增 `RoomAcousticsChorus`（合唱音效），可使人声在合唱场景下更具空间立体感。 - 在 [`RemoteAudioStats`](/zh-CN/api-reference/rtc/react-native/class-remoteaudiostats) 中新增 `e2eDelay`，用于报告从发送端采集音频起，到接收端开始播放音频时的延时。 ### 问题修复 [#问题修复-158] 该版本修复了以下问题： - 使用媒体播放器播放包含 SEI 数据的媒体流时，SEI 数据的输出与视频渲染不同步。 - 主播使用部分型号设备在扬声器下进行音视频互动，之后切换 App 进程到后台再切回前台，偶现本地音频采集失败，远端用户听不到主播的声音。(Android) - 在 Android 8.0 系统的设备上，启用屏幕共享功能时 App 偶现崩溃。(Android) - 使用摄像头采集本地视频场景下，在 App 切后台时已调用 [`disableVideo`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_disablevideo) 或 关闭视频采集，但将 App 再切回前台时，摄像头采集被打开，不符合预期。(Android) - 当发送端用户的网络环境恶化（例如弱网）时，接收端偶现视频流畅度降低、卡顿增加。 ### API 变更 [#api-变更-79] #### 新增 [#新增-73] - [`enableCameraCenterStage`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/center-stage#api_irtcengine_enablecameracenterstage) (iOS) - [`isCameraCenterStageSupported`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/center-stage#api_irtcengine_iscameracenterstagesupported) (iOS) - [`setCameraStabilizationMode`](/zh-CN/api-reference/rtc/react-native/video/camera-capture#api_irtcengine_setcamerastabilizationmode) (iOS) - [`CameraStabilizationMode`](/zh-CN/api-reference/rtc/react-native/enum-camerastabilizationmode) (iOS) - [`EncryptionConfig`](/zh-CN/api-reference/rtc/react-native/class-encryptionconfig) 中新增 `datastreamEncryptionEnabled` - [`EncryptionErrorType`](/zh-CN/api-reference/rtc/react-native/enum-encryptionerrortype) 中新增如下枚举： - `EncryptionErrorDatastreamDecryptionFailure` - `EncryptionErrorDatastreamEncryptionFailure` - [`RemoteAudioStats`](/zh-CN/api-reference/rtc/react-native/class-remoteaudiostats) 新增 `e2eDelay` - [`ErrorCodeType`](/zh-CN/api-reference/rtc/react-native/enum-errorcodetype) 新增 `ErrDatastreamDecryptionFailed` - [`AudioEffectPreset`](/zh-CN/api-reference/rtc/react-native/enum-audioeffectpreset) 新增 `RoomAcousticsChorus` - [`getCallIdEx`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengineex_getcallidex) - [`enableEncryptionEx`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengineex_enableencryptionex) - [`setAudioMixingPlaybackSpeed`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_irtcengine_setaudiomixingplaybackspeed) - [`queryCameraFocalLengthCapability`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) - [`FocalLengthInfo`](/zh-CN/api-reference/rtc/react-native/class-focallengthinfo) - [`CameraFocalLengthType`](/zh-CN/api-reference/rtc/react-native/enum-camerafocallengthtype) - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/react-native/class-cameracapturerconfiguration) 新增成员 `cameraFocalLengthType` - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/react-native/class-cameracapturerconfiguration) 新增成员 `cameraId` (Android) - [`EarMonitoringFilterType`](/zh-CN/api-reference/rtc/react-native/enum-earmonitoringfiltertype) 新增枚举 `EarMonitoringFilterBuiltInAudioFilters`(`1 << 15`) ## v4.3.0-build.1 [#v430-build1] 该版本于 2024 年 3 月 18 日发布。 ### 问题修复 [#问题修复-159] 该版本修复了如下问题： 在未调用 [`engine.unregisterEventHandler`](/zh-CN/api-reference/rtc/react-native/initialize#api_irtcengine_removehandler) 删除已添加的所有回调事件时，直接调用 [`engine.release`](/zh-CN/api-reference/rtc/react-native/initialize#api_irtcengine_release) 销毁引擎可能导致 App 崩溃。(Android) ## v4.3.0 [#v430-7] 该版本于 2024 年 2 月 28 日发布。 ### 升级必看 [#升级必看-94] 该版本对部分功能的实现方式进行了优化，涉及一些 API 的改名、删除或行为变更，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 回调中的参数改名 [#回调中的参数改名-7] 为了使一些回调中的参数以及枚举类中的枚举命名更加便于理解，该版本进行了如下修改，请在升级到该版本后修改回调中的参数设置。 | 回调 | 原有参数名 | 现有参数名 | | --- | --- | --- | | [`onLocalAudioStateChanged`](/zh-CN/api-reference/rtc/react-native/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) | `error` | `reason` | | [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/react-native/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) | `error` | `reason` | | `onDirectCdnStreamingStateChanged` | `error` | `reason` | | [`onMusicChartsResult`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) | `errorCode` | `reason` | | [`onPreLoadEvent`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) | [release-notes-rn-html-0-5-1 details](#table-slot-release-notes-rn-html-0-5-1) | [release-notes-rn-html-0-5-2 details](#table-slot-release-notes-rn-html-0-5-2) | | [`onMusicCollectionResult`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) | `errorCode` | `reason` | | [`onLyricResult`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) | `errorCode` | `reason` | | [`onSongSimpleInfoResult`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) | `errorCode` | `reason` | | [`onRtmpStreamingStateChanged`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/media-push#callback_irtcengineeventhandler_onrtmpstreamingstatechanged) | `errCode` | `reason` | **release-notes-rn-html-0-5-1 details** - `status` - `state` **release-notes-rn-html-0-5-2 details** - `errorCode` - `reason` | 原有枚举类 | 现有枚举类 | | ------------------------------ | ----------------------------- | | `LocalAudioStreamError` | [`LocalAudioStreamReason`](/zh-CN/api-reference/rtc/react-native/enum-localaudiostreamreason) | | `LocalVideoStreamError` | [`LocalVideoStreamReason`](/zh-CN/api-reference/rtc/react-native/enum-localvideostreamreason) | | `DirectCdnStreamingError` | `DirectCdnStreamingReason` | | `MediaPlayerError` | [`MediaPlayerReason`](/zh-CN/api-reference/rtc/react-native/enum-mediaplayerreason) | | `RtmpStreamPublishErrorType` | [`RtmpStreamPublishReason`](/zh-CN/api-reference/rtc/react-native/enum-rtmpstreampublishreason) | | `MusicContentCenterStatusCode` | [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/react-native/enum-musiccontentcenterstatereason) | :::info[信息] 有关具体枚举的改名详见 [API 变更](#430-api-changes)。 ::: #### 跨频道媒体流转发 [#跨频道媒体流转发-14] 为提升接口易用性，该版本删除了部分跨频道媒体流转发的方法和回调，请改用下表中列出的替代选项： | 已删除的方法和回调 | 替代的方法和回调 | | --- | --- | | [release-notes-rn-html-1-1-0 details](#table-slot-release-notes-rn-html-1-1-0) | [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) | | [release-notes-rn-html-1-2-0 details](#table-slot-release-notes-rn-html-1-2-0) | [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) | | `onChannelMediaRelayEvent` | [`onChannelMediaRelayStateChanged`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#callback_irtcengineeventhandler_onchannelmediarelaystatechanged) | **release-notes-rn-html-1-1-0 details** - `startChannelMediaRelay` - `updateChannelMediaRelay` **release-notes-rn-html-1-2-0 details** - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` #### 音频路由 [#音频路由-4] 该版本起，[`AudioRoute`](/zh-CN/api-reference/rtc/react-native/enum-audioroute) 中的`RouteBluetooth` 更名为 `RouteBluetoothDeviceHFP`，表示音频路由为使用 HFP 协议的蓝牙设备，新增 `RouteBluetoothDeviceA2DP`(10) 表示音频路由为使用 A2DP 协议的蓝牙设备。 #### 本地视频状态改变原因 [#本地视频状态改变原因-7] 该版本对 [`LocalVideoStreamReason`](/zh-CN/api-reference/rtc/react-native/enum-localvideostreamreason) 枚举类中的枚举进行了如下修改： - `LocalVideoStreamErrorCodecNotSupport` 的枚举名变更为 `LocalVideoStreamReasonCodecNotSupport`。 #### 日志加密行为变更 [#日志加密行为变更-7] 出于安全性和性能考虑，自该版本起，SDK 对日志进行加密，并且不再支持通过控制台打印明文日志。针对不同的需求，请参考以下解决方案： - 如果需要得知 API 的调用情况，请查看 API 的日志并自行打印 SDK 回调日志。 - 如有其他特殊需求，请[联系技术支持](https://ticket.shengwang.cn/)并附上对应的加密日志。 ### 新增特性 [#新增特性-134] #### 接收端自定义合图布局 [#接收端自定义合图布局-2] 为支持接收端自定义多路合图流的布局，该版本新增了 [`onTranscodedStreamLayoutInfo`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo) 回调。当接收端收到合图服务器发送的频道内合图视频流时，该回调会被触发，上报合图视频流的布局信息、以及合图流中每一路子视频流的布局信息。接收端可以在调用 方法时，为合图视频流中的子视频流（通过 `subviewUid` 区分）设置单独的 `view` 进行渲染，从而达到自定义视频布局的效果。 当合图视频流中的子视频流布局发生变化时，该回调也会被触发，实时上报最新的布局信息。 通过该特性，接收端可以灵活调整本地的视图布局。当在多人视频场景下应用时，接收端只需接收并解码一路合图视频流，可以有效降低接收端解码多路视频时的 CPU 占用率和网络带宽。 :::info[信息] 关于该特性在多主播场景下的最佳实践，详见[多主播场景下的视频体验优化](/zh-CN/realtime-media/rtc/build/video/custom-layout)。 ::: #### 多视图本地预览 [#多视图本地预览-7] 该版本支持在本地预览同时预览多个画面、且画面中显示的视频分别处于视频链路上的不同观测位置。使用方式举例如下： 1. 创建第一个视图，在 [`VideoCanvas`](/zh-CN/api-reference/rtc/react-native/class-videocanvas) 中设置 `position` 参数为 `PositionPostCapturerOrigin`（该枚举为该版本新增），对应本地采集视频之后、前处理之前的位置，此处观测到的视频不具备前处理的效果。 2. 创建第二个视图，在 [`VideoCanvas`](/zh-CN/api-reference/rtc/react-native/class-videocanvas) 中设置 `position` 参数为 `PositionPostCapturer`，此处观测到的视频具备视频前处理的效果。 3. 观察本地预览效果：视图一为真人原始视频；视图二为经过视频前处理的虚拟人像（包括美颜、虚拟背景、水印本地预览）效果。 #### 查询设备评分等级 [#查询设备评分等级-7] 该版本新增 [`queryDeviceScore`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_querydevicescore) 方法，用于查询设备的评分等级，以保证用户设置的参数不会超出其设备能力。例如，在高清或超高清视频场景下，可以先调用该方法查询设备的等级评分，如果返回的评分较低（比如低于 60），则需要适当调低视频分辨率，以避免影响视频体验。不同业务场景要求的最低设备评分等级不同，具体评分推荐请[联系技术支持](https://ticket.shengwang.cn/)。 #### 本地播放及发布至远端的音轨控制 [#本地播放及发布至远端的音轨控制-7] 该版本新增 [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。 使用该功能前，需要通过 [`openWithMediaSource`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并通过 [`MediaSource`](/zh-CN/api-reference/rtc/react-native/class-mediasource) 中新增的 `enableMultiAudioTrack` 成员来开启音轨控制。 #### 其他 [#其他-36] 该版本通过了如下 API 的测试验证，可以应用于全系列 RTC 4.x SDK。 - [`setRemoteSubscribeFallbackOption`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_setremotesubscribefallbackoption)：设置弱网环境下订阅的音视频流回退选项。 - [`onRemoteSubscribeFallbackToAudioOnly`](/zh-CN/api-reference/rtc/react-native/network#callback_irtcengineeventhandler_onremotesubscribefallbacktoaudioonly)：订阅流已回退为音频流或恢复为音视频流回调。 - [`setPlayerOptionInInt`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption) 和 [`setPlayerOptionInString`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplayeroption2)：设置媒体播放器选项，用于提供技术预览或特别定制功能。 - [`enableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/react-native/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback)：设置是否在本地播放外部音频源。 ### 改进 [#改进-154] #### SDK 任务处理调度优化 [#sdk-任务处理调度优化-7] 该版本对 SDK 内部任务的调度机制进行了优化，具体表现在以下方面： - 远端及本地的首帧出图与出声速度均有明显提升。 - API 的调用耗时和响应耗时缩短 50% 以上。 - SDK 的并行处理能力有明显提升，在较低端的设备上也能体验到较高的视频质量 (720P，24 fps)；并且在高分辨率和高帧率视频场景下的图像处理更加稳定。 - SDK 的稳定性进一步增强，在各种特定场景下崩溃率有明显下降。 #### 耳返音量提升 [#耳返音量提升-7] 该版本为用户提供更灵活的耳返音频调整选项，支持调用 [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/react-native/audio/audio-capture#api_irtcengine_setinearmonitoringvolume) 将耳返音量设置为原始音量的 4 倍。 #### 空间音频易用性提升 [#空间音频易用性提升-7] - 该版本优化了 [`setZones`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 方法的设计，支持将 `zones` 参数设置为 `NULL`，表示清除所有隔声区域。 - 自该版本起，在调用 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_ilocalspatialaudioengine) 中的方法之前，无需先取消订阅频道内所有远端用户的音频流。 #### 其他改进 [#其他改进-67] 该版本还进行了如下改进： - 优化视频模块的算法、减小视频传输时对带宽的要求，在网络环境保持不变的情况下，为用户提供了更好的视频体验。 - 该版本优化了 SDK 的域名解析策略，提高了复杂网络环境下调用 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_setlocalaccesspoint) 解析域名时的稳定性。 - 传入含透明背景的图片作为虚拟背景的自定义背景图时，支持自定义图片透明背景的填充色。 - [`LocalAudioStats`](/zh-CN/api-reference/rtc/react-native/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员，分别用于报告耳返延迟和回声消除 (Acoustic Echo Cancellation, AEC) 延迟。 - 新增 [`onPlayerCacheStats`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) 回调，当媒体资源开始缓存后，SDK 会每秒触发一次该回调，报告当前缓存的媒体资源的相关数据。 - 新增 [`onPlayerPlaybackStats`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) 回调，当媒体资源开始播放后，SDK 会每秒触发一次该回调，报告媒体当前播放的媒体资源的相关信息。你可以通过 [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/react-native/class-playerplaybackstats) 来获取当前音、视频的码率等信息。 - [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/react-native/enum-musiccontentcenterstatereason) 中新增状态码 `kMusicContentCenterReasonHttpInternalError` 表示 HTTP 内部发生错误，请稍后重试。 ### 问题修复 [#问题修复-160] 该版本修复了以下问题： - 当同时共享两路屏幕共享视频流时，[`onLocalVideoStats`](/zh-CN/api-reference/rtc/react-native/video/video-basic#callback_irtcengineeventhandler_onlocalvideostats) 回调上报的 `captureFrameRate` 为 0，不符合预期。 ### API 变更 [#api-变更-80] #### 新增 [#新增-74] - [`onTranscodedStreamLayoutInfo`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#callback_irtcengineeventhandler_ontranscodedstreamlayoutinfo) - [`VideoLayout`](/zh-CN/api-reference/rtc/react-native/class-videolayout) - [`VideoCanvas`](/zh-CN/api-reference/rtc/react-native/class-videocanvas) 新增 `subviewUid` 和 `uid` 成员 - [`enableCustomAudioLocalPlayback`](/zh-CN/api-reference/rtc/react-native/audio/audio-custom-capturenrendering#api_irtcengine_enablecustomaudiolocalplayback) - [`queryDeviceScore`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_querydevicescore) - [`MediaSourceType`](/zh-CN/api-reference/rtc/react-native/enum-mediasourcetype) 中新增 `CustomVideoSource` 枚举 - [`AudioRoute`](/zh-CN/api-reference/rtc/react-native/enum-audioroute) 中新增 `RouteBluetoothDeviceA2DP` 枚举 - [`LocalAudioStats`](/zh-CN/api-reference/rtc/react-native/class-localaudiostats) 新增 `earMonitorDelay` 和 `aecEstimatedDelay` 成员 - [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) - [`onPlayerCacheStats`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-cache#callback_imediaplayersourceobserver_onplayercachestats) - [`onPlayerPlaybackStats`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-info#callback_imediaplayersourceobserver_onplayerplaybackstats) - [`PlayerPlaybackStats`](/zh-CN/api-reference/rtc/react-native/class-playerplaybackstats) - [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/react-native/enum-musiccontentcenterstatereason) 中新增 `kMusicContentCenterReasonHttpInternalError` #### 修改 [#修改-22] - `RouteBluetooth` 枚举名变更为 `RouteBluetoothDeviceHFP` - 以下枚举名中的 `error` 字段全部修改为 `reason`： - `LocalAudioStreamErrorOk` - `LocalAudioStreamErrorFailure` - `LocalAudioStreamErrorDeviceNoPermission` - `LocalAudioStreamErrorDeviceBusy` - `LocalAudioStreamErrorRecordFailure` - `LocalAudioStreamErrorEncodeFailure` - `LocalVideoStreamErrorOk` - `LocalVideoStreamErrorFailure` - `LocalVideoStreamErrorDeviceNoPermission` - `LocalVideoStreamErrorDeviceBusy` - `LocalVideoStreamErrorCaptureFailure` - `LocalVideoStreamErrorCodecNotSupport` - `LocalVideoStreamErrorCaptureInbackground` (iOS) - `LocalVideoStreamErrorCaptureMultipleForegroundApps` (iOS) - `LocalVideoStreamErrorDeviceNotFound` - `LocalVideoStreamErrorDeviceDisconnected` - `LocalVideoStreamErrorDeviceInvalidId` - `DirectCdnStreamingErrorOk` - `DirectCdnStreamingErrorFailed` - `DirectCdnStreamingErrorAudioPublication` - `DirectCdnStreamingErrorVideoPublication` - `DirectCdnStreamingErrorNetConnect` - `DirectCdnStreamingErrorBadName` - `PlayerErrorNone` - `PlayerErrorInvalidArguments` - `PlayerErrorInternal` - `PlayerErrorNoResource` - `PlayerErrorInvalidMediaSource` - `PlayerErrorUnknownStreamType` - `PlayerErrorObjNotInitialized` - `PlayerErrorCodecNotSupported` - `PlayerErrorVideoRenderFailed` - `PlayerErrorInvalidState` - `PlayerErrorUrlNotFound` - `PlayerErrorInvalidConnectionState` - `PlayerErrorSrcBufferUnderflow` - `PlayerErrorInterrupted` - `PlayerErrorNotSupported` - `PlayerErrorTokenExpired` - `PlayerErrorUnknown` - `RtmpStreamPublishErrorOk` - `RtmpStreamPublishErrorInvalidArgument` - `RtmpStreamPublishErrorEncryptedStreamNotAllowed` - `RtmpStreamPublishErrorConnectionTimeout` - `RtmpStreamPublishErrorInternalServerError` - `RtmpStreamPublishErrorRtmpServerError` - `RtmpStreamPublishErrorTooOften` - `RtmpStreamPublishErrorReachLimit` - `RtmpStreamPublishErrorNotAuthorized` - `RtmpStreamPublishErrorStreamNotFound` - `RtmpStreamPublishErrorFormatNotSupported` - `RtmpStreamPublishErrorNotBroadcaster` - `RtmpStreamPublishErrorTranscodingNoMixStream` - `RtmpStreamPublishErrorNetDown` - `RtmpStreamPublishErrorInvalidPrivilege` - `RtmpStreamUnpublishErrorOk` - `MusicContentCenterStatusCode` 修改为 [`MusicContentCenterStateReason`](/zh-CN/api-reference/rtc/react-native/enum-musiccontentcenterstatereason)，其中的枚举名的 `StatusErr` 字段全部修改为 `Reason`： - `kMusicContentCenterStatusErrGateway` - `kMusicContentCenterStatusErrPermissionAndResource` - `kMusicContentCenterStatusErrInternalDataParse` - `kMusicContentCenterStatusErrMusicLoading` - `kMusicContentCenterStatusErrMusicDecryption` - `KMusicContentCenterStatusErr`修改为 `KMusicContentCenterReasonError` #### 删除 [#删除-32] - `startChannelMediaRelay` - `updateChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - `onChannelMediaRelayEvent` - `ChannelMediaRelayEvent` ## v4.2.6 [#v426-6] 该版本于 2023 年 11 月 21 日发布。 ### 问题修复 [#问题修复-161] 该版本修复了在使用 Android 14 系统版本时可能出现的问题： - 在屏幕共享过程中切换横竖屏模式导致当前屏幕共享进程中断，需要在弹出窗口中点击确认录制屏幕才可重新开始屏幕共享。(Android) - 在集成 SDK 时，如果将 Android `targetSdkVersion` 设置为 34，导致屏幕共享不可用甚至 App 崩溃。(Android) - 先调用 `startScreenCapture `但不共享视频（设置 `captureVideo` 为 `false`）、后调用 `updateScreenCaptureParameters `共享视频（设置 `captureVideo` 为 `true`）时，接收端看到的屏幕共享画面冻结。(Android) - 采用横屏模式进行屏幕共享时，观众端看到的共享画面被拆分成两部分：一侧的画面被压缩；另一侧为黑屏。(Android) 该版本还修复了以下问题： - 使用 iOS 16 版本或以上设备在加入频道前连接了蓝牙耳机，在加入频道后的音频路由不符合预期：音频从扬声器播放、而非蓝牙耳机。(iOS) - 在直播场景下，观众端看到的画面偶现变形。(Android) - 在特定场景（网络丢包率较高、主播在不销毁引擎时退出频道然后重新进入频道）下，接收端的视频出现卡顿或冻结。 ## v4.2.5 [#v425] 该版本于 2023 年 10 月 30 日发布。 ### 问题修复 [#问题修复-162] 该版本修复了如下问题： 因 `package.json` 中 `types` 字段定义的路径有误，导致集成 SDK 到 Typescript 项目时报错：`Could not find a declaration file for module 'react-native-agora'`。 ## v4.2.4 [#v424-2] 该版本于 2023 年 10 月 24 日发布。 ### 问题修复 [#问题修复-163] 该版本修复了如下问题： `AgoraRtcWrapper` 中的 `CFBundleShortVersionString` 版本号错误，导致 App 无法被提交至 App Store。(iOS) ## v4.2.3 [#v423-6] 该版本于 2023 年 10 月 17 日发布。 ### 升级必看 [#升级必看-95] #### 兼容性变更 [#兼容性变更-5] - 该版本删除了 [`IMusicContentCenter`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imusiccontentcenter) 类下的 `preload` 方法中的 `jsonOption` 参数，请在升级到该版本后更新 App 代码。 - 该版本优化了 SDK 采集和自定义视频采集场景下 Texture Buffer 的管理方式，有效消除丢帧和崩溃隐患。自该版本起，TextureBuffer 类型的纹理格式不再包括 OES 格式，仅为 RGB 格式。你需要在处理视频数据时增加对 I420、RGB 纹理格式的适配。(Android) ### 新增特性 [#新增特性-135] #### 本地截图上传更新 [#本地截图上传更新-7] 为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动： - [`ContentInspectType`](/zh-CN/api-reference/rtc/react-native/enum-contentinspecttype) 中新增 `ContentInspectImageModeration` 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。 - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/react-native/class-contentinspectconfig) 中新增的 `serverConfig` 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请[联系技术支持](https://ticket.shengwang.cn/)。 此外，该版本还新增了 [`enableContentInspectEx`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) 方法，支持同时对多条视频流截图并上传。 #### 进阶功能查询 [#进阶功能查询-7] 该版本新增了 [`isFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_isfeatureavailableondevice) 方法，用于查询设备能力是否满足虚拟背景、美颜等进阶功能的使用要求。 在使用进阶功能前，你可以根据查询结果判断当前设备是否支持这些功能，从而避免在低端设备上开启进阶功能导致性能下降或功能不可用的问题。你可以根据该方法的返回值，决定是否显示或启用相应的功能按钮，或者在设备能力不足时，为用户提示相应信息。 此外，自该版本起，调用 [`enableVirtualBackground`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 和 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 时，SDK 会自动对当前设备能力进行检查，并在设备能力不足时，通过返回错误码 `-4: ErrNotSupported` 表示该设备不支持开启该功能。 #### 通配 Token [#通配-token-7] 该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 :::warning[注意] 声网 4.x RTC SDK 均支持使用通配 Token。 ::: #### 预加载频道 [#预加载频道-8] 该版本新增 [`preloadChannel`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_preloadchannel) 和 [`preloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_preloadchannelwithuseraccount) 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。 在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 #### 自定义视频画布背景颜色 [#自定义视频画布背景颜色-7] 该版本在 [`VideoCanvas`](/zh-CN/api-reference/rtc/react-native/class-videocanvas) 中增加了 `backgroundColor` 成员，支持你在设置本地或远端视频显示属性时，自定义视频画布的背景颜色。 #### 支持仅播放副歌片段 [#支持仅播放副歌片段-2] 该版本新增 [`getInternalSongCode`](/zh-CN/api-reference/rtc/react-native/play/drm#api_imusiccontentcenter_getinternalsongcode) 方法，如果你仅需要播放某一音乐资源的副歌片段，在播放前你需要调用该方法来为该副歌片段创建一个内部歌曲编号，作为该资源的唯一标识。你可以查看[在线 K 歌房文档](/zh-CN/solutions/online-ktv)了解更多 K 歌场景方案。 ### 改进 [#改进-155] #### 摄像头采集效果提升 [#摄像头采集效果提升-2] 该版本从以下几个方面提升了摄像头采集效果： 1. 支持摄像头采集曝光调节 新增 [`isCameraExposureSupported`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_iscameraexposuresupported) 和 [`setCameraExposureFactor`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_setcameraexposurefactor) 方法，用于查询当前设备是否支持曝光调节和设置摄像头的曝光增益。 2. 优化默认摄像头选择 (iOS) 自该版本起，SDK 的默认摄像头选择对齐 iOS 系统相机行为。如果设备拥有多个后置摄像头，则在视频采集时可以获得更好的拍摄视野、变焦能力、低光性能和深度感应，从而提高视频采集的质量。 #### 虚拟背景算法升级 [#虚拟背景算法升级-7] 该版本升级了虚拟背景的人像分割算法，全面提升了人像分割的准确度、人像边缘与虚拟背景间的平滑度以及人物移动时边缘的贴合度，同时优化了虚拟背景在会议、办公、居家等场景下，以及逆光、弱光等条件下的人物边缘精度。 此外，该版本还降低了虚拟背景功能的内存占用。相比之前的版本，在低端机上使用虚拟背景功能时 App 运行占用的内存降低了约 4% 到 10%（具体数值取决于设备型号和平台）。 #### 屏幕共享场景优化 [#屏幕共享场景优化-5] 该版本优化了屏幕共享场景下的视频编码配置。当用户自定义视频的 `width` 和 `height` 属性时，SDK 会在保持视频与屏幕的宽高比一致的前提下，对实际的编码分辨率进行向下取整，确保最终编码分辨率不超过用户自定义的编码分辨率，从而提升了对屏幕共享流的计费准确性。 #### 跨频道连麦优化 [#跨频道连麦优化-7] 该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 时，你可以指定最多 6 个目标频道。 #### 视频编解码查询能力增强 [#视频编解码查询能力增强-7] 为提升设备编解码能力查询功能，该版本在 [`CodecCapInfo`](/zh-CN/api-reference/rtc/react-native/class-codeccapinfo) 中新增 `codecLevels` 成员。当成功调用 [`queryCodecCapability`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_querycodeccapability) 后，可通过 `codecLevels` 得知当前设备对于 H.264 和 H.265 格式的视频的硬件和软件解码能力等级。 #### 其他改进 [#其他改进-68] 该版本还进行了如下改进： - 当调用 [`setPlaybackSpeed`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，传入非法参数后会返回错误码 `-2`，表示方法中设置了无效的参数，需要重新设置参数。 - 优化了 Token 解析时的逻辑，避免传入非法 Token 后 App 发生崩溃。 - 为了提升多种音频路由之间的切换体验，该版本新增了 [`setRouteInCommunicationMode`](/zh-CN/api-reference/rtc/react-native/device-management/audio-route#api_irtcengine_setrouteincommunicationmode) 方法，用于在通话音量模式 ([`MODE_IN_COMMUNICATION`](https://developer.android.google.cn/reference/kotlin/android/media/AudioManager?hl=en#mode_in_communication)) 下，将音频路由从蓝牙耳机切换为听筒、有线耳机或扬声器。 (Android) - 在屏幕共享场景下，SDK 根据共享的场景自动调节发送端的帧率。尤其是在共享文档场景下，避免发送端的视频码率超出预期的情况，以提高传输效率、减小网络负担。 - 为帮助用户了解更多类型的远端视频状态改变的原因，[`onRemoteVideoStateChanged`](/zh-CN/api-reference/rtc/react-native/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调中新增了 `remoteVideoStateReasonCodecNotSupport` 枚举，表示本地的视频解码器不支持对收到的远端视频流进行解码。 - 版权音乐新增 [`getSongSimpleInfo`](/zh-CN/api-reference/rtc/react-native/play/drm#api_imusiccontentcenter_getsongsimpleinfo) 方法，可用于获取某一指定歌曲的详细信息，你可以通过触发的 [`onSongSimpleInfoResult`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) 回调来获取歌曲信息。 ### 问题修复 [#问题修复-164] 该版本修复了以下问题： - 本地系统时间不正确时，偶现加入频道失败。 - 调用 [`playEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_playeffect3) 使用相同的 `soundId` 播放两个不同的音效文件，偶现第一个音效文件播放完毕后会重复播放。 - 主播调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_irtcengine_startaudiomixing2) 播放音乐文件时，偶现主播本地无法听见音乐，远端用户可以正常听见。(Android) - 合唱场景下，调用 `preload` 加载音乐，偶现加载失败。 - 在特定机型上开启 AI 降噪偶现崩溃。(Android) - 当本地系统时间不准确时，歌曲榜单加载失败。 - 调用一次 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 获取视频截图会收到多次 [`onSnapshotTaken`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 视频截图结果回调。 - 在仅调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengineex_joinchannelex) 加入的频道中，调用 [`setEnableSpeakerphone`](/zh-CN/api-reference/rtc/react-native/device-management/audio-route#api_irtcengine_setenablespeakerphone) 无法将音频路由从扬声器切换至听筒。(Android) - 网络异常导致频道连接断开后，频道连接恢复较慢。 - 在屏幕共享场景下，部分机型偶现屏幕共享画面出图延迟高于预期。 - 自采集场景下，[`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions)、[`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)、[`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 和 [`setColorEnhanceOptions`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/video-enhance-option#api_irtcengine_setcolorenhanceoptions) 无法自动加载插件。 ### API 变更 [#api-变更-81] #### 新增 [#新增-75] - [`enableContentInspectEx`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) - [`ContentInspectType`](/zh-CN/api-reference/rtc/react-native/enum-contentinspecttype) 新增 `ContentInspectImageModeration` - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/react-native/class-contentinspectconfig) 中新增 `serverConfig` 可选参数 - [`isFeatureAvailableOnDevice`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_isfeatureavailableondevice) - `FeatureType` - [`setCameraExposureFactor`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_setcameraexposurefactor) - [`isCameraExposureSupported`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_iscameraexposuresupported) - [`preloadChannel`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_preloadchannel) - [`preloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_preloadchannelwithuseraccount) - [`updatePreloadChannelToken`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_updatepreloadchanneltoken) - [`getSongSimpleInfo`](/zh-CN/api-reference/rtc/react-native/play/drm#api_imusiccontentcenter_getsongsimpleinfo) - [`onSongSimpleInfoResult`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) - [`getInternalSongCode`](/zh-CN/api-reference/rtc/react-native/play/drm#api_imusiccontentcenter_getinternalsongcode) - [`onLyricResult`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 中增加 `songCode` - [`onPreLoadEvent`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 中增加 `requestId` - [`setRouteInCommunicationMode`](/zh-CN/api-reference/rtc/react-native/device-management/audio-route#api_irtcengine_setrouteincommunicationmode) (Android) - [`CodecCapLevels`](/zh-CN/api-reference/rtc/react-native/class-codeccaplevels) - `VideoCodecCapabilityLevel` - [`VideoCanvas`](/zh-CN/api-reference/rtc/react-native/class-videocanvas) 中增加 `backgroundColor` 成员 - [`CodecCapInfo`](/zh-CN/api-reference/rtc/react-native/class-codeccapinfo) 中增加 `codecLevels` 成员 - [`RemoteVideoStateReason`](/zh-CN/api-reference/rtc/react-native/enum-remotevideostatereason) 中增加 `remoteVideoStateReasonCodecNotSupport` 枚举 #### 删除 [#删除-33] - [`IMusicContentCenter`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imusiccontentcenter) 类下的 `preload` 方法中的 `jsonOption` 参数 ## v4.2.1 [#v421-8] 该版本于 2023 年 6 月 21 日发布。 ### 改进 [#改进-156] 该版本改进了网络传输策略，提升了音视频交互的流畅度。 ### 问题修复 [#问题修复-165] 该版本修复了以下问题： - SDK 不兼容部分旧版本 AccessToken 导致无法加入频道。 - 发送端调用 [`setAINSMode`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 开启 AI 降噪功能后，接收端用户偶现回声。 - 使用媒体播放器播放媒体文件时出现短暂杂音。 - 调用 [`destroyMediaPlayer`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-initialize#api_irtcengine_destroymediaplayer) 销毁媒体播放器时偶现崩溃。 (iOS) - 屏幕共享场景下，部分机型必现接收端看到共享的画面卡顿。 (Android) ## v4.2.0 [#v420-8] 该版本于 2023 年 5 月 26 日发布。 ### 升级必看 [#升级必看-96] 该版本对部分功能的实现方式进行了优化，请在升级到该版本后更新 App 代码。 #### 视频采集 (iOS) [#视频采集-ios] 原有用于摄像头和屏幕采集的方法已删除，请改用下表中列出的替代方法，并通过设置 `sourceType` 来指定视频源。 | 已删除方法 | 替代方法 | | :------------------------------------------------------- | :------------------------------- | | `startSecondaryCameraCapture` | [`startCameraCapture`](/zh-CN/api-reference/rtc/react-native/video/camera-capture#api_irtcengine_startcameracapture) | | `stopSecondaryCameraCapture` | [`stopCameraCapture`](/zh-CN/api-reference/rtc/react-native/video/camera-capture#api_irtcengine_stopcameracapture) | #### 视频数据获取 [#视频数据获取-7] [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/react-native/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/react-native/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调中新增了 `sourceType` 参数，用于表示具体的视频源类型。 #### 媒体发布选项 [#媒体发布选项-7] - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` 已删除，请改用 `publishCustomAudioTrack`。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 中的成员 `publishTrancodedVideoTrack` 变更为 `publishTranscodedVideoTrack。` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 中的成员 `publishCustomAudioSourceId` 变更为 `publishCustomAudioTrackId`。 #### 音视频录制 [#音视频录制-7] - 删除 `getMediaRecorder` 方法，可通过该版本新增的 [`createMediaRecorder`](/zh-CN/api-reference/rtc/react-native/recording#api_irtcengine_createmediarecorder) 方法来创建录制对象。 - 删除 [`startRecording`](/zh-CN/api-reference/rtc/react-native/recording#api_imediarecorder_startrecording) 、[`stopRecording`](/zh-CN/api-reference/rtc/react-native/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/react-native/recording#api_imediarecorder_setmediarecorderobserver) 中的 `connection` 参数。 - 删除 [`IMediaRecorder`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imediarecorder) 类中的 `release` 方法，你可直接调用该版本新增的 [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/react-native/recording#api_irtcengine_destroymediarecorder) 方法来销毁录制对象以释放资源。 #### 默认分辨率提升 [#默认分辨率提升-1] 自该版本起，SDK 对视频编码的算法进行了优化，将默认的视频编码分辨率从 640 × 360 提升为 960 × 540，以适应设备性能和网络带宽的提升，在各种音视频互动场景下，为用户提供全链路的高清体验。 如果你想自定义视频编码分辨率，可调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法，重新设置视频编码参数配置中的视频编码分辨率。 :::note 由于默认分辨率的提升，会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 其他兼容性变更 [#其他兼容性变更-7] - `onApiCallExecuted` 已删除，请改用相关频道和媒体的事件通知得知 API 的执行结果。 - `startChannelMediaRelay`、`updateChannelMediaRelay`、`startChannelMediaRelayEx` 和 `updateChannelMediaRelayEx` 已废弃，请改用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex)。 ### 新增特性 [#新增特性-136] #### AI 降噪 [#ai-降噪-7] 该版本新增 AI 降噪功能。开启该功能后，SDK 会智能识别和消除背景噪音，无论是在嘈杂的公共场所，还是在需要保持低延迟的实时竞技场景，都能够确保声音传输的清晰度，为用户提供更高质量的音频体验。你可以通过该版本新增的 [`setAINSMode`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) 方法开启 AI 降噪，并根据实际场景，将降噪模式设置为均衡模式、强降噪模式或低延时模式。 #### 增强虚拟背景 [#增强虚拟背景-7] 为了增加实时视频通话的趣味性、保护用户隐私，该版本增强了虚拟背景功能。你可以在调用 [`enableVirtualBackground`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/virtualbackground#api_irtcengine_enablevirtualbackground) 方法时，将自定义背景设置为更多类型： - 将背景处理为 Alpha 信息，不作替换，仅分割人像和背景，可结合本地合图功能实现人像画中画效果。 - 将背景替换为多种格式的本地视频。 #### 视频场景化设置 [#视频场景化设置-7] 该版本新增 [`setVideoScenario`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_setvideoscenario) 方法用于设置视频业务场景，SDK 会根据不同场景自动启用最佳实践策略，调整关键性能指标，进而优化视频质量，提升用户体验。无论是正式的商务会议还是轻松的在线聚会，该功能都能确保视频质量满足需求。目前，该特性主要为实时视频会议场景提供了以下针对性的优化： - 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。 - 实时监测接收端大小流的订阅人数，根据订阅人数动态调节大流配置、动态开启和关闭小流，以节省上行带宽和消耗。 #### 本地录制远端音视频 (Beta) [#本地录制远端音视频-beta-7] 该版本新增本地录制远端音视频功能。本地用户可以录制远端用户的音频视频流，便于将来回放、分析或分享，适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态，该版本在 [`onRecorderStateChanged`](/zh-CN/api-reference/rtc/react-native/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`onRecorderInfoUpdated`](/zh-CN/api-reference/rtc/react-native/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数，用于表示录制的音视频流的具体信息，并新增 [`createMediaRecorder`](/zh-CN/api-reference/rtc/react-native/recording#api_irtcengine_createmediarecorder) 方法，用于创建本地或远端的录制对象。 你可以通过如下方法体验本地录制远端音视频功能： - [`createMediaRecorder`](/zh-CN/api-reference/rtc/react-native/recording#api_irtcengine_createmediarecorder)：创建录制对象。如需同时录制本地和远端的音视频，可以多次调用该方法创建多个录制对象。 - [`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/react-native/recording#api_imediarecorder_setmediarecorderobserver)：设置录制回调对象。 - [`startRecording`](/zh-CN/api-reference/rtc/react-native/recording#api_imediarecorder_startrecording)：开始录制。 - [`stopRecording`](/zh-CN/api-reference/rtc/react-native/recording#api_imediarecorder_stoprecording)：停止录制。 - [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/react-native/recording#api_irtcengine_destroymediarecorder)：销毁录制对象。 #### 本地合图 [#本地合图-12] 该版本新增本地合图功能，用户可以调用 [`startLocalVideoTranscoder`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) 方法，在本地将多路视频流（例如：摄像头采集的视频、屏幕共享流、视频文件、图片等）混合和渲染，以实现自定义布局和效果。通过这项功能，你可以轻松创建个性化的视频显示效果，满足各种场景需求，如远程会议、直播、在线教育场景，同时支持人像画中画等功能。 另外，SDK 还提供了[`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 方法和 [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调。当你在开启本地合图后，可以调用 [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) 更新合图的配置；当你在开启本地合图或者更新本地合图配置失败时，可通过 [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) 回调得知合图失败的原因。 :::warning[注意] 本地合图对 CPU 的消耗较高，声网建议你在性能较高的设备上开启该功能。 ::: #### 多端同步 [#多端同步-7] 在实时合唱的场景中，可能会出现网络原因导致各接收端下行链路不一致的情况，该版本新增 [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_getntpwalltimeinms) 方法获取当前的 NTP (网络时间协议) 时间，用于对齐多个接收端的歌词和音乐，实现合唱同步、歌词进度同步等，为用户提供更佳的协同体验。 #### 快速出图出声 [#快速出图出声-7] 该版本新增 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#api_irtcengine_enableinstantmediarendering) 方法，用于开启音视频帧的加速渲染模式，可加快用户加入频道后的首帧出图与出声速度。 #### 视频渲染数据打点 [#视频渲染数据打点-7] 该版本新增 [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#api_irtcengine_startmediarenderingtracing) 和 [`startMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) 方法，SDK 以调用该方法的时刻作为起点，开始跟踪频道内视频帧的渲染状态，并通过 [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告相关事件的信息。 声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用。例如：在终端用户点击“加入频道”按钮的时刻调用该方法进行打点，然后通过 [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调获取视频帧渲染过程中的指标，从而方便开发者针对指标进行专项优化，以提高出图效率。 ### 改进 [#改进-157] #### 优化变声 [#优化变声-7] 该版本新增了 [`setLocalVoiceFormant`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoiceformant) 方法，用于设置共振峰比率以改变语音的音色。该方法还可以和 [`setLocalVoicePitch`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/audio-effect#api_irtcengine_setlocalvoicepitch) 方法一起使用，同时调节音调和音色，实现更多样化的变声效果。 #### 增强屏幕共享 [#增强屏幕共享-2] 该版本新增 [`queryScreenCaptureCapability`](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_queryscreencapturecapability) 方法，用于查询当前设备的屏幕捕获能力。如果你想在屏幕共享时启用高帧率（如 60 fps）、但不确定设备是否支持时，可以调用该方法、然后从返回值中得知设备支持的最高帧率是否满足需求。 该版本新增 [`setScreenCaptureScenario`](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_setscreencapturescenario) 方法，用于设置屏幕共享的场景类型，SDK 会根据场景类型自动调整共享画面的的流畅度和清晰度。 #### 提升音频文件类型兼容性 (Android) [#提升音频文件类型兼容性-android-2] 该版本提升了音频文件类型兼容性，你可以通过 [`startAudioMixing`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_irtcengine_startaudiomixing2)、[`playEffect`](/zh-CN/api-reference/rtc/react-native/play/audio-effect-file#api_irtcengine_playeffect3)、[`openWithMediaSource`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 方法来打开以 `content://` 开头的 URI 文件。 #### 提升音视频同步能力 [#提升音视频同步能力-7] 针对自定义视频和音频采集场景，该版本新增 [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_getcurrentmonotonictimeinms) 方法用于获取当前的 Monotonic Time，将该值传入视频帧和音频帧的时间戳，可以精确控制音视频时序，确保音视频同步。 #### 优化多路摄像头采集 [#优化多路摄像头采集-2] 该版本新增 [`startCameraCapture`](/zh-CN/api-reference/rtc/react-native/video/camera-capture#api_irtcengine_startcameracapture) 方法，通过多次调用并指定 `sourceType` 参数可以同时开启多路摄像头采集的视频流，用于本地合图或多频道发布。适用于如远程医疗、远程教育等连接多个摄像头的场景。 #### 优化版权音乐 [#优化版权音乐-2] 针对在线 K 歌房场景，该版本新增 [`getCaches`](/zh-CN/api-reference/rtc/react-native/play/drm#api_imusiccontentcenter_getcaches) 和 [`removeCache`](/zh-CN/api-reference/rtc/react-native/play/drm#api_imusiccontentcenter_removecache) 方法，用于获取、删除音乐资源缓存，并新增状态码和错误码，可方便用户排查问题。 #### 优化跨频道连麦 [#优化跨频道连麦-7] 该版本新增 `startOrUpdatechannelMediaRelay` 和 `startOrUpdatechannelMediaRelayEx` 方法，通过一个方法实现开始跨频道转发和更新转发的目标频道，提升了接口易用性；同时，优化内部交互次数，有效降低调用了延迟。在降低开发难度的同时，为开发者提供更顺畅的使用体验。 #### 多路音频自采集 [#多路音频自采集-7] 为更好地满足音频自采集的场景需求，该版本新增了 [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/react-native/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) 和 [`destroyCustomAudioTrack`](/zh-CN/api-reference/rtc/react-native/audio/audio-custom-capturenrendering#api_imediaengine_destroycustomaudiotrack) 方法用于创建和销毁自定义音频轨道，并提供了两种音频轨道类型供用户选择，进一步提升了自采集音频处理的灵活性和易用性： - 可混音的音频轨道：支持将多路外部音频源混合发布到同一频道中，适用于多路音频源的自采集场景。 - 非混音的音频轨道：仅支持将一路外部音频源发布到单个频道中，适用于实时低延迟的自采集场景。 #### 视频观测器 [#视频观测器-7] 自该版本起，SDK 对 [`onRenderVideoFrame`](/zh-CN/api-reference/rtc/react-native/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 回调进行了优化，在不同的视频处理模式下返回值的意义不同： - 当视频处理模式为 `ProcessModeReadOnly` 时，返回值无实际含义。 - 当视频处理模式为 `ProcessModeReadWrite` 时，返回 `true` 代表设置 SDK 接收视频帧；返回 `false` 代表设置 SDK 丢弃视频帧。 #### 超分辨率 [#超分辨率-2] 该版本提升了超分辨率的性能表现。为提升超分辨率易用性，该版本删除了 `enableRemoteSuperResolution`，超分辨率不再需要手动开启，SDK 将自动根据用户设备性能优化远端视频的分辨率。 ### 问题修复 [#问题修复-166] 该版本修复了以下问题： - 加入或退出频道时，安卓设备端偶现的崩溃。 (Android) - 当快速切换身份角色时，观众端听不到声音。 - 偶现耳返开启无效。(Android) - 跨频道连麦时 `firstRemoteVideoFrameOfUid` 回调偶现丢失。(iOS) - 接收端主动订阅大流但是异常接收小流。(iOS) - 偶现回声。(Android) - 由于 [`onRemoteAudioStateChanged`](/zh-CN/api-reference/rtc/react-native/audio/audio-basic#callback_irtcengineeventhandler_onremoteaudiostatechanged) 回调异常造成客户端状态异常。 - 使用媒体播放器播放采样率超过 48 kHz 的音频时，播放失败。 - 在红米 9A 上进行 CDN 推流，将推流的视频分辨率设置为 3840 × 2160 必现崩溃。 (Android) - 合唱模式下，OPPO R11 设备外放加入频道后，对端听到明显杂声和回音。(Android) - 本地音乐文件结束播放时，未能触发 onAudioMixingFinished 回调。(Android) - 接收端通过视频观测器接收的第一帧视频帧偶现丢包。(Android) - 在多频道场景下开启屏幕共享，偶现远端看到的本地屏幕共享画面为黑屏。(Android) - 开启虚拟背景时切换至后置摄像头会导致背景倒置。 (Android) - 当频道内有多路视频流时，调用部分视频增强插件相关 API 偶现失败。 - 客户端主动退出频道时未向服务端发起请求，导致服务端判定为退出频道超时。 ### API 变更 [#api-变更-82] #### 新增 [#新增-76] - [`startCameraCapture`](/zh-CN/api-reference/rtc/react-native/video/camera-capture#api_irtcengine_startcameracapture) - [`stopCameraCapture`](/zh-CN/api-reference/rtc/react-native/video/camera-capture#api_irtcengine_stopcameracapture) - [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) - [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) - [`getNtpWallTimeInMs`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_getntpwalltimeinms) - [`setVideoScenario`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_setvideoscenario) - [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_getcurrentmonotonictimeinms) - [`onLocalVideoTranscoderError`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/local-transcoder#callback_irtcengineeventhandler_onlocalvideotranscodererror) - [`startLocalVideoTranscoder`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/local-transcoder#api_irtcengine_startlocalvideotranscoder) - [`updateLocalTranscoderConfiguration`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/local-transcoder#api_irtcengine_updatelocaltranscoderconfiguration) - [`queryScreenCaptureCapability`](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_queryscreencapturecapability) - [`setScreenCaptureScenario`](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_setscreencapturescenario) - [`setAINSMode`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/audio-effect#api_irtcengine_setainsmode) - [`createCustomAudioTrack`](/zh-CN/api-reference/rtc/react-native/audio/audio-custom-capturenrendering#api_imediaengine_createcustomaudiotrack) - [`destroyCustomAudioTrack`](/zh-CN/api-reference/rtc/react-native/audio/audio-custom-capturenrendering#api_imediaengine_destroycustomaudiotrack) - [`createMediaRecorder`](/zh-CN/api-reference/rtc/react-native/recording#api_irtcengine_createmediarecorder) - [`destroyMediaRecorder`](/zh-CN/api-reference/rtc/react-native/recording#api_irtcengine_destroymediarecorder) - [`IMusicContentCenter`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imusiccontentcenter) 中新增如下方法 - [`removeCache`](/zh-CN/api-reference/rtc/react-native/play/drm#api_imusiccontentcenter_removecache) - [`getCaches`](/zh-CN/api-reference/rtc/react-native/play/drm#api_imusiccontentcenter_getcaches) - [`AudioTrackConfig`](/zh-CN/api-reference/rtc/react-native/class-audiotrackconfig) - [`MusicCacheInfo`](/zh-CN/api-reference/rtc/react-native/class-musiccacheinfo) - [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/react-native/class-recorderstreaminfo) - [`AudioAinsMode`](/zh-CN/api-reference/rtc/react-native/enum-audioainsmode) - [`AudioTrackType`](/zh-CN/api-reference/rtc/react-native/enum-audiotracktype) - [`MusicCacheStatusType`](/zh-CN/api-reference/rtc/react-native/enum-musiccachestatustype) - [`VideoApplicationScenarioType`](/zh-CN/api-reference/rtc/react-native/enum-videoapplicationscenariotype) - [`ScreenCaptureFramerateCapability`](/zh-CN/api-reference/rtc/react-native/enum-screencaptureframeratecapability) - [`RtcEngineContext`](/zh-CN/api-reference/rtc/react-native/class-rtcengineconfig) 中新增 `domainLimit` 和 `autoRegisterAgoraExtensions` 属性 - [`onRecorderStateChanged`](/zh-CN/api-reference/rtc/react-native/recording#callback_imediarecorderobserver_onrecorderstatechanged)、[`onRecorderInfoUpdated`](/zh-CN/api-reference/rtc/react-native/recording#callback_imediarecorderobserver_onrecorderinfoupdated) 中新增 `channelId` 和 `uid` 参数 - [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/react-native/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 和 [`onPreEncodeVideoFrame`](/zh-CN/api-reference/rtc/react-native/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 中增加 `sourceType` 参数 - [`BackgroundSourceType`](/zh-CN/api-reference/rtc/react-native/enum-backgroundsourcetype) 中新增 `BackgourndNone` 和 `BackgroundVideo` - `PreloadStatusCode` 中增加 `KPreloadStatusRemoved` - `MusicContentCenterStatusCode` 中增加如下枚举： - `KMusicContentCenterStatusErrGateway` - `KMusicContentCenterStatusErrPermissionAndResource` - `KMusicContentCenterStatusErrInternalDataParse` - `KMusicContentCenterStatusErrMusicLoading` - `KMusicContentCenterStatusErrMusicDecryption` - [`MusicContentCenterConfiguration`](/zh-CN/api-reference/rtc/react-native/class-musiccontentcenterconfiguration) 中新增 `maxCacheSize ` - [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#api_irtcengine_enableinstantmediarendering) - [`startMediaRenderingTracing`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#api_irtcengine_startmediarenderingtracing) - [`startMediaRenderingTracingEx`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#api_irtcengineex_startmediarenderingtracingex) - [`onVideoRenderingTracingResult`](/zh-CN/api-reference/rtc/react-native/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) - [`MediaTraceEvent`](/zh-CN/api-reference/rtc/react-native/enum-mediatraceevent) - [`VideoRenderingTracingInfo`](/zh-CN/api-reference/rtc/react-native/class-videorenderingtracinginfo) #### 修改 [#修改-23] - [`onMusicChartsResult`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 中的 `status` 修改为 `errorCode` - [`onMusicCollectionResult`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 中的 `status` 修改为 `errorCode` - [`onLyricResult`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 中的 `status` 修改为 `errorCode` - [`onPreLoadEvent`](/zh-CN/api-reference/rtc/react-native/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 中的 `msg` 修改为 `errorCode ` #### 废弃 [#废弃-27] - `startChannelMediaRelay` - `startChannelMediaRelayEx` - `updateChannelMediaRelay` - `updateChannelMediaRelayEx` - `onChannelMediaRelayEvent` - `ChannelMediaRelayEvent` #### 删除 [#删除-34] - `onApiCallExecuted` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 中的 `publishCustomAudioTrackEnableAec` - `getMediaRecorder` - [`IMediaRecorder`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imediarecorder) 类中的 `release` - [`startRecording`](/zh-CN/api-reference/rtc/react-native/recording#api_imediarecorder_startrecording)、[`stopRecording`](/zh-CN/api-reference/rtc/react-native/recording#api_imediarecorder_stoprecording)、[`setMediaRecorderObserver`](/zh-CN/api-reference/rtc/react-native/recording#api_imediarecorder_setmediarecorderobserver) 中删除 `connection` 参数 - `enableRemoteSuperResolution` - [`RemoteVideoStats`](/zh-CN/api-reference/rtc/react-native/class-remotevideostats) 中删除 `superResolutionType` ## v4.1.0 [#v410-7] 该版本于 2022 年 12 月 20 日发布。 ### 升级必看 [#升级必看-97] 如果你已经使用了以下类或方法，请在升级到该版本后重新调用方法并更新参数设置： 删除了 [`enableDualStreamMode`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_enabledualstreammode3) 中的 `sourceType` 参数，因为 SDK 支持对自定义采集或 SDK 采集的各种视频源开启双流模式，不再需要指定视频源类型。 ### 新增特性 [#新增特性-137] #### 耳返 [#耳返-7] 该版本新增耳返功能。你可以调用 [`enableInEarMonitoring`](/zh-CN/api-reference/rtc/react-native/audio/audio-capture#api_irtcengine_enableinearmonitoring2) 开启耳返功能。 如需调节耳返音量，你可以调用 [`setInEarMonitoringVolume`](/zh-CN/api-reference/rtc/react-native/audio/audio-capture#api_irtcengine_setinearmonitoringvolume)。 #### 音频采集设备测试 (Android) [#音频采集设备测试-android-2] 该版本支持加入频道前测试本地音频采集设备。你可以调用 `startRecordingDeviceTest` 开启音频采集设备测试，测试完成后，调用 [`stopPlaybackDeviceTest`](/zh-CN/api-reference/rtc/react-native/device-management/audio-device#api_iaudiodevicemanager_stopplaybackdevicetest) 方法停止音频采集设备测试。 #### 本地网络连接类型 [#本地网络连接类型-7] 为方便用户在任何阶段知悉本地网络的连接类型，该版本新增 [`getNetworkType`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_getnetworktype) 方法。你可以通过该方法获取正在使用的网络连接的类型，包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时，SDK 会触发 [`onNetworkTypeChanged`](/zh-CN/api-reference/rtc/react-native/network#callback_irtcengineeventhandler_onnetworktypechanged) 回调，报告当前的网络连接类型。 #### 音强选流 [#音强选流-7] 声网服务器会根据音量大小对音频流进行筛选，选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路，如需自定义设置 N，请联系技术支持。 同时，声网还支持发流端自定义设置是否参与音强选流，不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下，开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗，详见[音强选流](/zh-CN/realtime-media/rtc/build/audio/audio-stream-filter)。 该版本新增音强选流功能，如需开启该功能，请联系[技术支持](https://ticket.shengwang.cn/)。 #### 双流模式 [#双流模式-8] 该版本对双流模式做了优化，在加入频道前后均可调用 [`enableDualStreamMode`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_enabledualstreammode3) 和 [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_enabledualstreammodeex)。 扩展了订阅视频小流的实现方式，SDK 默认在发送端开启小流 auto 模式 (即：默认不主动发送小流)，可通过以下步骤开启发送小流： 1. 接收端主播调用 [`setRemoteVideoStreamType`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setremotevideostreamtype) 或 [`setRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 发起接收小流申请。 2. 发送端收到申请后自动切换为发送小流模式。 如果你想修改上述发送端的默认行为，可以调用 [`setDualStreamMode`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setdualstreammode2) 方法，将 `mode` 参数设置为 `disableSimulcastStream` (始终不发送小流) 或 `enableSimulcastStream` (始终发送小流)。 #### 空间音频 [#空间音频-13] 该版本新增了如下适用于空间音频场景的特性，在虚拟互动场景下可以有效提升用户的临场感体验。 - 隔声区域：你可以通过调用 [`setZones`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 设置隔声区域和声音衰减系数。当音源 (可以为用户或媒体播放器) 跟听声者分属于音障区域内部和外部时，会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用 [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) 和 [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) 方法分别针对媒体播放器和用户设置声音衰减属性，并指定是否使用该设置强制覆盖 [`setZones`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) 中的声音衰减系数。 - 多普勒音效：你可以通过设置 [`SpatialAudioParams`](/zh-CN/api-reference/rtc/react-native/class-spatialaudioparams) 中的 `enableDoppler` 参数开启多普勒音效，在声源和接收方发生高速相对位移的情况下 (比如赛车游戏场景)，接收方会体验到明显的音调变化。 - 耳机均衡器：你可以通过调用 [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 方法使用预设的耳机均衡效果，以改善耳机的听感。 #### 多路摄像头 (iOS) [#多路摄像头-ios-2] 该版本新增多路摄像头视频采集功能，你可以通过调用 [`enableMultiCamera`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_enablemulticamera) 开启多路摄像头采集模式，再调用 `startSecondaryCameraCapture` 通过第二个摄像头采集视频，然后将采集到的视频发布到多频道中。 如需停止多路摄像头采集，需要先调用 `stopSecondaryCameraCapture` 停止第二个摄像头采集，然后调用 [`enableMultiCamera`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_enablemulticamera) 并将 `enabled` 设置为 `false`。 #### 版权音乐 [#版权音乐-3] 为解决直播、语聊房、在线 K 歌房等场景下歌曲的应用版权问题，该版本新增版权音乐相关 API。你可以通过调用 `MusicContentCenter` 类、[`IMusicPlayer`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imusicplayer) 类、`MusicContentCenterEventHandler` 类下的相关 API 实现在实时互动场景中播放版权音乐以及相关功能，例如检索音乐资源、获取音乐榜单及榜单详情、预加载及播放音乐资源、下载歌词及海报等功能。你还可以参考[在线 K 歌房](/zh-CN/solutions/online-ktv)来体验搭配了演唱评分、美声音效等一系列功能的线上 K 歌场景化解决方案。 #### 耳机均衡器 [#耳机均衡器-5] 该版本新增 [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) 方法，用于调节耳机均衡器的低频和高频参数，主要应用于空间音频场景。如果在调用 [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) 后仍未达到预期的耳机均衡效果，你可以调用该方法进行调节。 #### MPUDP (MultiPath UDP) [#mpudp-multipath-udp-7] 自该版本起，SDK 支持 MPUDP 协议，在 UDP 协议的基础上，允许连接并使用多个路径来最大化信道资源的使用。你可以同时在不同终端使用不同的物理网卡并将其聚合，达到有效对抗网络抖动、提升传输质量的效果。 如果你希望体验该功能，请联系 sales@shengwang.cn。 #### 摄像头采集选项 [#摄像头采集选项-7] 该版本在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/react-native/class-cameracapturerconfiguration) 中增加了 `followEncodeDimensionRatio` 成员参数，你可以在使用摄像头采集视频时，通过该成员参数设置是否跟随 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 中已经设置的视频宽高比。 #### 多频道管理 [#多频道管理-7] 该版本增加了一系列多频道相关的方法，你可以通过调用这些方法，实现对多频道中音视频流的管理。 - 新增 [`muteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) 和 [`muteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) 方法，分别用于取消或恢复发布本地音频流和视频流。 - 新增 [`muteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) 和 [`muteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) 方法，分别用于取消或恢复订阅所有远端用户的音频流和视频流。 - 新增 [`startRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex)、`startRtmpStreamWithTranscodingEx、updateRtmpTranscodingEx` 和 [`stopRtmpStreamEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) 方法，用于实现多频道场景下的旁路推流。 - 新增 `startChannelMediaRelayEx`、`updateChannelMediaRelayEx`、[`pauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex)、[`resumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) 和 [`stopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) 方法，用于实现多频道场景下的跨频道媒体流转发。 - [`leaveChannelEx`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengineex_leavechannelex2) 方法新增 `options` 参数，用于在多频道场景下离开频道时，选择是否停止麦克风采集。 #### 视频编码偏好 [#视频编码偏好-7] 一般场景下，声网默认的视频编码配置能满足需求。对于特定场景，该版本在 [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/react-native/class-videoencoderconfiguration) 中新增 `advanceOptions` 成员参数，用于视频编码属性的进阶设置： - `compressionPreference`：视频编码的压缩偏好设置，用于选择视频的低延时或高质量偏好。 - `encodingPreference`：视频编码器偏好设置，用于进阶设置视频编码属性，视频编码器偏好设置，用于选择视频的自适应偏好、软件编码偏好或硬件编码偏好。 #### 日志上传 [#日志上传-7] 使用声网私有媒体服务器的场景下，为支持用户在调用 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_setlocalaccesspoint) 方法时的进阶设置，该版本在 [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/react-native/class-localaccesspointconfiguration) 中新增 `advancedConfig` 成员参数，该参数支持如下设置： - `logUploadServer`：默认情况下，SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。 #### 用户角色切换 [#用户角色切换-7] 为方便用户分辨切换后的用户角色属于互动直播还是极速直播，该版本在 [`onClientRoleChanged`](/zh-CN/api-reference/rtc/react-native/channel#callback_irtcengineeventhandler_onclientrolechanged) 回调中新增 `newRoleOptions` 参数，该参数取值如下： - `audienceLatencyLevelLowLatency`(1): 低延时，属于极速直播。 - `audienceLatencyLevelUltraLowLatency`(2): 超低延时，属于互动直播。 ### 改进 [#改进-158] #### 视频信息发生改变回调 [#视频信息发生改变回调-7] 该版本优化了 [`onVideoSizeChanged`](/zh-CN/api-reference/rtc/react-native/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged) 的触发逻辑，当单独调用 [`startPreview`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_startpreview2) 时，也可触发该回调并上报本地视频大小发生改变。 #### 蓝牙权限 (Android) [#蓝牙权限-android-2] 为简化集成步骤，自该版本起，SDK 支持你在不添加 `BLUETOOTH_CONNECT` 权限的情况下，也能让 Android 用户正常使用蓝牙。 #### CDN 推流 [#cdn-推流-7] 为提升 CDN 推流的用户体验，当设置的视频分辨率超出摄像头设备支持的范围时，SDK 会根据你的设置进行自适应，取最接近、且长宽比与你设置的分辨率一致的值进行采集、编码、推流，同时通过 `onDirectCdnStreamingStats` 回调报告推送的视频流的实际分辨率。 #### 跨频道媒体流转发 [#跨频道媒体流转发-15] 该版本对 `updateChannelMediaRelay` 方法做了如下优化： - 4.1.0 版本前：如果服务器内部原因导致目标频道更新失败，SDK 返回错误码 `relayEventPacketUpdateDestChannelRefused `(8)，你需要重新调用 `updateChannelMediaRelay` 方法。 - 4.1.0 版本及之后：如果服务器内部原因导致目标频道更新失败，SDK 会重新尝试更新直到目标频道更新成功。 #### AIAEC [#aiaec-7] 该版本基于 AI 方法重构了 AEC 算法，相比传统 AEC 算法，新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声，显著提高系统的回声消除和双讲性能，带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。 #### 虚拟背景 [#虚拟背景-7] 该版本对虚拟背景算法做了如下优化： - 在处理虚拟背景的边界时更加细腻，抠图精细程度达到发丝级别。 - 在人像静止或移动时都能确保虚拟背景的稳定性，有效解决背景闪烁、超出画面范围的问题。 - 支持更多应用场景，无论在黑夜、白天、室内、室外等各种环境下都能获得良好的虚拟背景效果。 - 支持识别多种姿态，包括半身静态、身体晃动、手部摆动，并支持精细识别手指动作，在不同手势下均能达到良好的虚拟背景效果。 #### 其他改进 [#其他改进-69] - 降低了推送外部音频源时的上行延迟。 - 提升了会议场景 (`audioScenarioMeeting`) 默认参数配置下的回声消除性能。 - 提升了 SDK 视频渲染的流畅度。 - 增强对不同网络协议栈的识别能力，在多种运营商网络场景下提升 SDK 的接入能力。 ### 问题修复 [#问题修复-167] 该版本修复了以下问题： 所有平台 Android iOS - 在频道内调用 [`setVideoEncoderConfigurationEx`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengineex_setvideoencoderconfigurationex) 将视频的分辨率调高时，偶现失效。 - 使用媒体播放器播放视频，先调用 [`play`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 再调用 [`pause`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 指定一个新的播放位置，偶现视频画面依然是暂停播放时的画面；调用 [`resume`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_resume) 恢复播放后，偶现视频画面出现快进。 - 在直播场景下，主播在扬声器和听筒之间进行切换后，观众听主播的声音会听到滋啦杂声。 - 调用 [`getExtensionProperty`](/zh-CN/api-reference/rtc/react-native/extension#api_irtcengine_getextensionproperty2) 失败，返回空字符串。 - 当以观众身份进入一个已播放较长时间的直播间，首帧出图时间缩短。 - 在多人会议场景下，本地用户接听并挂断电话后，偶现本地用户和远端用户无法听见对方的声音。 - 调用 [`setCloudProxy`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_setcloudproxy) 设置云代理后，调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengineex_joinchannelex) 加入多频道失败。 - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/react-native/play/audio-mixing#api_irtcengine_startaudiomixing2) 播放 `ipod-library://item` 路径的音乐文件失败。 - 同时通过 [`onRecordAudioFrame`](/zh-CN/api-reference/rtc/react-native/audio/audio-raw#callback_iaudioframeobserverbase_onrecordaudioframe) 和 [`onCaptureVideoFrame`](/zh-CN/api-reference/rtc/react-native/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 回调分别获取的音频和视频数据时间戳不同。 ### API 变更 [#api-变更-83] #### 新增 [#新增-77] - [`getNativeHandle`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_getnativehandle) - [`getMusicContentCenter`](/zh-CN/api-reference/rtc/react-native/play/drm#api_irtcengine_getmusiccontentcenter) - `getPlaybackDefaultDevice` - `getRecordingDefaultDevice` - [`enableDualStreamModeEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_enabledualstreammodeex) - [`setDualStreamMode`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setdualstreammode2) - [`setDualStreamModeEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_setdualstreammodeex) - [`SimulcastStreamMode`](/zh-CN/api-reference/rtc/react-native/enum-simulcaststreammode) - [`getNetworkType`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_getnetworktype) - [`setZones`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setzones) - [`setPlayerAttenuation`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_setplayerattenuation) - [`setRemoteAudioAttenuation`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_setremoteaudioattenuation) - [`setHeadphoneEQPreset`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqpreset) - [`setHeadphoneEQParameters`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_irtcengine_setheadphoneeqparameters) - [`HeadphoneEqualizerPreset`](/zh-CN/api-reference/rtc/react-native/enum-headphoneequalizerpreset) - [`enableMultiCamera`](/zh-CN/api-reference/rtc/react-native/device-management/video-device#api_irtcengine_enablemulticamera) (iOS) - [`setRemoteVideoSubscriptionOptions`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setremotevideosubscriptionoptions) - [`setRemoteVideoSubscriptionOptionsEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_setremotevideosubscriptionoptionsex) - [`VideoSubscriptionOptions`](/zh-CN/api-reference/rtc/react-native/class-videosubscriptionoptions) - `AdvancedOptions` - [`EncodingPreference`](/zh-CN/api-reference/rtc/react-native/enum-encodingpreference) - [`CompressionPreference`](/zh-CN/api-reference/rtc/react-native/enum-compressionpreference) - [`adjustUserPlaybackSignalVolumeEx`](/zh-CN/api-reference/rtc/react-native/audio/audio-basic#api_irtcengineex_adjustuserplaybacksignalvolumeex) - [`onRhythmPlayerStateChanged`](/zh-CN/api-reference/rtc/react-native/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) - [`RhythmPlayerStateType`](/zh-CN/api-reference/rtc/react-native/enum-rhythmplayerstatetype) - `RhythmPlayerErrorType` - [`enableAudioVolumeIndicationEx`](/zh-CN/api-reference/rtc/react-native/audio/audio-basic#api_irtcengineex_enableaudiovolumeindicationex) - [`muteLocalAudioStreamEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_mutelocalaudiostreamex) - [`muteLocalVideoStreamEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_mutelocalvideostreamex) - [`muteAllRemoteAudioStreamsEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_muteallremoteaudiostreamsex) - [`muteAllRemoteVideoStreamsEx`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengineex_muteallremotevideostreamsex) - [`startRtmpStreamWithoutTranscodingEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithouttranscodingex) - [`startRtmpStreamWithTranscodingEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/media-push#api_irtcengineex_startrtmpstreamwithtranscodingex) - [`updateRtmpTranscodingEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/media-push#api_irtcengineex_updatertmptranscodingex) - [`stopRtmpStreamEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/media-push#api_irtcengineex_stoprtmpstreamex) - `startChannelMediaRelayEx` - `updateChannelMediaRelayEx` - [`pauseAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengineex_pauseallchannelmediarelayex) - [`resumeAllChannelMediaRelayEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengineex_resumeallchannelmediarelayex) - [`stopChannelMediaRelayEx`](/zh-CN/api-reference/rtc/react-native/cloud-media-relay/channel-media-relay#api_irtcengineex_stopchannelmediarelayex) - [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/react-native/class-localaccesspointconfiguration) - [`AdvancedConfigInfo`](/zh-CN/api-reference/rtc/react-native/class-advancedconfiginfo) - [`LogUploadServerInfo`](/zh-CN/api-reference/rtc/react-native/class-loguploadserverinfo) - [`IMusicContentCenter`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imusiccontentcenter) 接口类及其中方法 - [`IMusicPlayer`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imusicplayer) 接口类及其中方法 - [`IMusicContentCenterEventHandler`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imusiccontentcentereventhandler) 接口类及其中回调 - [`MusicChartInfo`](/zh-CN/api-reference/rtc/react-native/class-musicchartinfo) 类 - [`ClimaxSegment`](/zh-CN/api-reference/rtc/react-native/class-climaxsegment) 类 - [`Music`](/zh-CN/api-reference/rtc/react-native/class-music) 类 - [`MusicContentCenterConfiguration`](/zh-CN/api-reference/rtc/react-native/class-musiccontentcenterconfiguration) 类 - [`MusicChartCollection`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_musicchartcollection) 类 (iOS) - [`MusicCollection`](/zh-CN/api-reference/rtc/react-native/class-musiccollection) 类 (iOS) - `PreloadStatusCode` (iOS) - `MusicContentCenterStatusCode` (iOS) #### 修改 [#修改-24] - [`enableDualStreamMode`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_enabledualstreammode3)：删除 `sourceType` - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions)：新增 `isAudioFilterable` - [`SpatialAudioParams`](/zh-CN/api-reference/rtc/react-native/class-spatialaudioparams)：新增 `enableDoppler` - `ScreenCaptureSourceInfo`：新增 `minimizeWindow` - [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/react-native/class-cameracapturerconfiguration)：新增 `followEncodeDimensionRatio` - [`leaveChannelEx`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengineex_leavechannelex2)：新增 `options` - [`VideoEncoderConfiguration`](/zh-CN/api-reference/rtc/react-native/class-videoencoderconfiguration)：新增 `advanceOptions` - [`LocalAccessPointConfiguration`](/zh-CN/api-reference/rtc/react-native/class-localaccesspointconfiguration)：新增 `advancedConfig` - [`onClientRoleChanged`](/zh-CN/api-reference/rtc/react-native/channel#callback_irtcengineeventhandler_onclientrolechanged)：新增 `newRoleOptions` - [`VideoCanvas`](/zh-CN/api-reference/rtc/react-native/class-videocanvas)：新增 `setupMode`、`mediaPlayerId` 和 `cropArea` - [`LocalVideoStats`](/zh-CN/api-reference/rtc/react-native/class-localvideostats)：新增 `hwEncoderAccelerating` #### 废弃 [#废弃-28] - `onApiCallExecuted` - `ChannelMediaRelayEvent`：废弃 `relayEventPacketUpdateDestChannelRefused `(8) ## v4.0.0 [#v400-7] 该版本于 2022 年 9 月 29 日发布。 ### 升级必看 [#升级必看-98] #### 兼容性变更 [#兼容性变更-6] v4.0.0 SDK 包名由 `react-native-agora-rtc-ng` 变更为 `react-native-agora`，且对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。如下为存在兼容性变更的主要功能： - 多频道 - 媒体流发布控制 - 警告码 升级 SDK 后，你需要结合实际业务场景更新 App 代码，详见[迁移指南](/zh-CN/realtime-media/rtc/reference/migration-guide)。 ### 新增特性 [#新增特性-138] #### 多路媒体流 [#多路媒体流-7] 该版本支持通过设置 `RtcEngineEx` 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions)，实现一个 [`IRtcEngine`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengine) 实例同时采集多路音视频源并发布到远端，适应各种业务场景。例如： - 调用 [`joinChannel`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_joinchannel2) 加入首个频道后，多次调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengineex_joinchannelex) 加入多个频道，通过不同的用户 ID 和 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 设置发布指定的流到不同的频道。 - 支持通过设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 中的 `publishSecondaryCameraTrack` 和 `publishSecondaryScreenTrack` 同时发布多路摄像头采集或者屏幕共享的视频流。 同时，该版本支持通过 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/react-native/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流： 1. 创建自采集视频轨道：调用 [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/react-native/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法创建一个自定义视频轨道，并获得视频轨道 ID。 2. 设置频道中待发布的自采集视频轨道：在每个频道的 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 中，将 `customVideoTrackId` 参数设置为你想要发布的视频轨道 ID，并将 `publishCustomVideoTrack` 设置为 `true`。 3. 推送外部视频源：调用 [`pushVideoFrame`](/zh-CN/api-reference/rtc/react-native/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe)，并将 `videoTrackId` 指定为你想要发布的自定义视频轨道 ID，即可根据步骤 2 的设置，实现在多个频道中发布对应的自定义视频源。 结合多频道能力，你还可以体验如下功能： - 将多组音视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路音频流混音后通过一个用户 ID (`uid`) 发布到远端。 - 将多组视频流通过不同的用户 ID (`uid`) 发布到远端。 - 将多路视频流合图后通过一个用户 ID (`uid`) 发布到远端。 #### 全高清和超高清分辨率 [#全高清和超高清分辨率-2] 为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持全高清 (FHD) 和超高清 (UHD) 视频分辨率。你可以在调用 [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法时，将 `dimensions` 参数设置为 1920 × 1080 或更高的分辨率。如果你的设备不支持高分辨率，SDK 支持自动回退到适合的分辨率。 :::info[信息] - 超高清分辨率（4K，60 fps）目前为 Beta 功能，且对设备性能和网络带宽有一定要求，如需体验该功能，请[联系技术支持](https://ticket.shengwang.cn/)。 - 高分辨率通常需要更高的性能消耗，为避免设备性能不足导致体验下降，声网建议你在性能较好的设备上开启全高清和超高清视频分辨率。 - 高分辨率可能会影响集合分辨率从而导致费用变更。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 内置媒体播放器 [#内置媒体播放器-7] 为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 [`createMediaPlayer`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer) 创建媒体播放器后，你可以通过 [`IMediaPlayer`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_imediaplayer) 类的一系列方法体验内置媒体播放器的各类功能： - 自动播放本地、在线、自定义的媒体资源。 - 预先加载待播放的媒体资源。 - 根据网络情况切换媒体资源的播放线路。 - 将媒体播放器的音视频流推送到任意频道、分享给远端用户。 - 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。 #### 新版 AI 降噪 [#新版-ai-降噪-7] 自该版本起，SDK 支持新版 AI 降噪（相对于 v3.7.0 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响 (Dereverberation) 能力。 如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。 #### 超高音质 [#超高音质-7] 为还原音频的细节、提升音频的清晰度，该版本新增 `UltraHighQualityVoice`。在语聊、歌唱等以人声为主的场景中，你可以调用 [`setVoiceBeautifierPreset`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/audio-effect#api_irtcengine_setvoicebeautifierpreset) 并使用该枚举体验超高音质。 #### 空间音频 [#空间音频-14] :::warning[注意] 空间音频功能当前处于实验阶段，请联系 sales@shengwang.cn 开通空间音频功能，如果需要技术支持，请[提交工单](https://ticket.shengwang.cn/)。 ::: 该版本提供本地直角坐标系计算方案实现空间音频： - 使用 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_ilocalspatialaudioengine) 类实现空间音频，通过 SDK 计算远端用户的空间坐标。你需要分别调用 [`updateSelfPosition`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`updateRemotePosition`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ilocalspatialaudioengine_updateremoteposition) 更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音频。 ![](https://web-cdn.agora.io/docs-files/1663038259399) - 通过 SDK 计算媒体播放器的空间坐标。你需要在 [`ILocalSpatialAudioEngine`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_ilocalspatialaudioengine) 类中分别调用 [`updateSelfPosition`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateselfposition) 和 [`updatePlayerPositionInfo`](/zh-CN/api-reference/rtc/react-native/audio/audio-prenpost/spatial-audio#api_ibasespatialaudioengine_updateplayerpositioninfo) 更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音频。 ![](https://web-cdn.agora.io/docs-files/1663038287220) #### 实时合唱 [#实时合唱-7] 该版本为实时合唱赋予了如下能力： - 支持两人及两人以上合唱。 - 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。 - 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。 该版本新增 `AudioScenarioChorus` 枚举来设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。 #### 增强的频道管理 [#增强的频道管理-7] 为满足各类业务场景对频道管理的需求，该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 结构体中新增了如下功能： - 设置或切换多种音视频源的发布 - 设置或切换频道场景、用户角色 - 设置或切换订阅视频的大小流类型 - 控制音频发布时延 在调用 [`joinChannel`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_joinchannel2) 或 [`joinChannelEx`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengineex_joinchannelex) 时设置 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions)，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_updatechannelmediaoptions) 随时更新 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/class-channelmediaoptions) 中的设置，例如，切换发布的音视频源。 #### 屏幕共享 [#屏幕共享-13] 该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享： - - 在加入频道**前**调用 [`startScreenCapture`](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_startscreencapture) ，然后调用 `joinChannel`[2/2] 加入频道并设置 `publishScreenCaptureVideo` 为 `true`，即可开始屏幕共享。 - 在加入频道**后**调用 [`startScreenCapture`](/zh-CN/api-reference/rtc/react-native/video/screencapture#api_irtcengine_startscreencapture) ，然后调用 [`updateChannelMediaOptions`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_updatechannelmediaoptions) 设置 `publishScreenCaptureVideo` 为 `true`，即可开始屏幕共享。 #### 设置音视频流订阅黑/白名单 [#设置音视频流订阅黑白名单-7] 该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通过 [`IRtcEngineEx`](/zh-CN/api-reference/rtc/react-native/rtc-interface-class#class_irtcengineex) 类下的同名方法来实现该功能。 - [`setSubscribeAudioBlocklist`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setsubscribeaudioblocklist)：设置音频订阅黑名单。 - [`setSubscribeAudioAllowlist`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setsubscribeaudioallowlist)：设置音频订阅白名单。 - [`setSubscribeVideoBlocklist`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setsubscribevideoblocklist)：设置视频订阅黑名单。 - [`setSubscribeVideoAllowlist`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setsubscribevideoallowlist)：设置视频订阅白名单。 如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。 #### 设置音频场景 [#设置音频场景-7] 为方便用户灵活修改音频场景，该版本新增 [`setAudioScenario`](/zh-CN/api-reference/rtc/react-native/audio/audio-basic#api_irtcengine_setaudioscenario) 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 (`AudioScenarioDefault`) 切换为高音质场景 (`AudioScenarioGameStreaming`)，你可以调用该方法。 #### 设置本地代理 [#设置本地代理-7] 该版本新增 [`setLocalAccessPoint`](/zh-CN/api-reference/rtc/react-native/network#api_irtcengine_setlocalaccesspoint) 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@shengwang.cn 了解和部署声网混合云或声网私有化平台。 #### 垫片推流 [#垫片推流-8] 该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 [`enableVideoImageSource`](/zh-CN/api-reference/rtc/react-native/video/video-prenpro/image-source#api_irtcengine_enablevideoimagesource) 来开启该功能，并通过 `options` 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。 ### 改进 [#改进-159] #### 快速切换频道 [#快速切换频道-7] 该版本通过 [`leaveChannel`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_leavechannel2) 和 [`joinChannel`](/zh-CN/api-reference/rtc/react-native/channel#api_irtcengine_joinchannel2) 切换频道即可实现和 v3.7.0 中 `switchChannel` 一样的切换速度，无需额外调用 `switchChannel` 方法。 #### 推送外部视频帧 [#推送外部视频帧-7] 该版本新增支持推送 I422 格式的外部视频帧，你可以通过 `pushVideoFrame`[1/2] 方法将 I422 格式的外部视频帧推送至 SDK。 #### 本地人声音调 [#本地人声音调-7] 该版本在 `onAudioVolumeIndication` 的 [`AudioVolumeInfo`](/zh-CN/api-reference/rtc/react-native/class-audiovolumeinfo) 中新增 `voicePitch` 参数。你可以通过 `voicePitch` 获取本地用户的人声音调，从而实现唱歌评分等业务功能。 #### 本地视频预览 [#本地视频预览-7] 该版本优化了 [`startPreview`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_startpreview2) 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 [`startPreview`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_startpreview2) 方法来开启视频预览，无调用时序要求。 #### 订阅视频流 [#订阅视频流-7] 你可以通过 [`setRemoteDefaultVideoStreamType`](/zh-CN/api-reference/rtc/react-native/publishnsubscribe#api_irtcengine_setremotedefaultvideostreamtype) 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。 #### 设备权限管理 [#设备权限管理-2] 该版本新增 [`onPermissionError`](/zh-CN/api-reference/rtc/react-native/network#callback_irtcengineeventhandler_onpermissionerror) 方法，当获取音频采集设备或摄像头权限失败时自动上报，用户可根据该回调的提示开启相应的设备权限。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="unreal" /> ### 已知问题和局限性 [#已知问题和局限性-5] **音频模块不兼容 (iOS)** 声网 Unreal SDK 的音频模块与 Unreal Engine 5.3、5.4 的 AudioMixer 模块不兼容。如果你使用 Unreal Engine 5.3 或 5.4，需要在项目的 `/Config/IOS/IOSEngine.ini` 文件中添加以下代码，关闭 Unreal Engine 的 AudioMixer 模块，以避免冲突。 ```ini [Audio] AudioMixerModuleName= ``` ## v4.5.1 [#v451-5] 该版本于 2025 年 3 月 13 日发布。 ### 新增特性 [#新增特性-139] #### AI 对话场景 [#ai-对话场景-8] 该版本新增了专为与[声网对话式 AI 引擎](/zh-CN/ai)创建的智能体互动设计的 `AUDIO_SCENARIO_AI_CLIENT` 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。 ### 改进 [#改进-160] 优化了特定机型上 SDK 初始化的耗时。（iOS） ### 问题修复 [#问题修复-168] 该版本修复了以下问题： - 集成 SDK 的 App 设置 `targetSdkVersion` 为 34，在 Android 14 系统上首次开启屏幕共享进行授权时出现崩溃。(Android) - 同时加入两个及以上的频道，连续调用 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。 - 使用媒体播放器时，调用 [`pause`](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`seek`](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 定位到指定播放位置、然后调用 [`play`](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。 - 使用媒体播放器时，调用 [`switchSrc`](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换媒体资源后，调用 [`getPlaySrc`](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-info#api_imediaplayer_getplaysrc) 获取当前正在播放的媒体资源的路径没有变化。 - 用户在特定机型上进行音视频互动并使用蓝牙耳机，偶现调整手机音量后改变的是媒体音量而非蓝牙音量。(Android) - 音视频互动时，偶现接收端观看发送端画面出现黑屏。(Android) - 在特定机型上，调用 [`setCameraExposureFactor`](/zh-CN/api-reference/rtc/unreal-cpp/device-management/video-device#api_irtcengine_setcameraexposurefactor) 在设备的某个特定角度设置当前摄像头的曝光系数后，当设备移动到另一个角度时，偶现视频画面变暗。(Android) - 播放 CDN 直播流时，直播流短暂中断后恢复，偶现播放画面长时间卡住。(Android) - 在推送 i420 格式的视频帧到频道内时，使用 CVPixelBuffer 会导致崩溃。(iOS) - 调用 [`setupLocalVideo`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-rendering#api_irtcengine_setuplocalvideo) 设置两个视图（view），然后调用 [`enableFaceDetection`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/face-detection#api_irtcengine_enablefacedetection) 开启人脸检测，后传入的视图中无法检测到人脸信息。(iOS) - 屏幕共享场景下，接收端用户看到的共享图像出现绿线。(iOS) - 在极速直播场景下，观众通过 `string` 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。 - 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。 ## v4.5.0 [#v450-8] 该版本于 2024 年 12 月 10 日发布。 ### 升级必看 [#升级必看-99] 该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 强效视频降噪实现变更 [#强效视频降噪实现变更-8] 该版本调整了强效视频降噪的实现方式，在 [`VIDEO_DENOISER_LEVEL`](/zh-CN/api-reference/rtc/unreal-cpp/enum-videodenoiserlevel) 中删除了 `VIDEO_DENOISER_LEVEL_STRENGTH`，改为调用 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 启用视频降噪后，调用 [`setBeautyEffectOptions`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 [`setVideoDenoiserOptions`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)。 此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 [`setLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)。 #### 摄像头插拔状态变更 (macOS, Windows) [#摄像头插拔状态变更-macos-windows-3] 在之前版本中，当摄像头拔出并重新插入时，[`onVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/unreal-cpp/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) 回调会将设备状态报告为 `MEDIA_DEVICE_STATE_ACTIVE(1)`（设备正在使用）。该版本起，摄像头重新插入后，设备状态将改为 `MEDIA_DEVICE_STATE_IDLE(0)`（设备就绪）。 #### 视频编码偏好变更 [#视频编码偏好变更-8] 为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好： - 在 [`COMPRESSION_PREFERENCE`](/zh-CN/api-reference/rtc/unreal-cpp/enum-compressionpreference) 枚举类中新增 `PREFER_COMPRESSION_AUTO (-1)` 枚举，并替代原有的 `PREFER_QUALITY (1)` 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `PREFER_LOW_LATENCY` 或 `PREFER_QUALITY`，以获得最佳的用户体验。 - 在 [`DEGRADATION_PREFERENCE`](/zh-CN/api-reference/rtc/unreal-cpp/enum-degradationpreference) 枚举类中新增 `MAINTAIN_AUTO (-1)` 枚举，并替代原有的 `MAINTAIN_QUALITY (1)` 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `MAINTAIN_FRAMERATE`、`MAINTAIN_BALANCED` 或 `MAINTAIN_RESOLUTION`，以获得最优的综合质量体验 (QoE)。 #### 16 KB 内存页大小 (Android) [#16-kb-内存页大小-android] 自 Android 15 起，系统新增了对 16 KB 内存页大小的支持，详见 [Support 16 KB page sizes](https://developer.android.com/guide/practices/page-sizes?hl=zh-cn)。为了保证 App 的稳定性和性能表现，自该版本起，SDK 支持 16 KB 内存页大小，确保可以在使用 4 KB 和 16 KB 内存页大小的设备上无缝运行，提升兼容性并避免崩溃。 ### 新增特性 [#新增特性-140] #### 高级美颜 [#高级美颜-8] 该版本新增以下两种高级美颜功能： - 美型：调用 [`setFaceShapeBeautyOptions`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 [`setFaceShapeAreaOptions`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapeareaoptions) 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。 - 美妆：调用 [`setExtensionProperty`](/zh-CN/api-reference/rtc/unreal-cpp/extension#api_irtcengine_setextensionproperty) 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。 :::info[信息] 目前，高级美颜功能为**限时免费**，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 秀场直播场景 [#秀场直播场景-8] 该版本在 [`VIDEO_APPLICATION_SCENARIO_TYPE`](/zh-CN/api-reference/rtc/unreal-cpp/enum-videoapplicationscenariotype) 类下新增枚举 `APPLICATION_SCENARIO_LIVESHOW(3)`（秀场直播），你可以调用 [`setVideoScenario`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为秀场直播。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，例如，默认开启音视频加速渲染来提升首帧出图体验，无需再额外调用 [`enableInstantMediaRendering`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-rendering#api_irtcengine_enableinstantmediarendering)，同时增强了在弱网环境和低端设备上的画质和流畅度表现。 #### 限制视频渲染帧率 [#限制视频渲染帧率-8] 该版本新增 [`setLocalRenderTargetFps`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-rendering#api_irtcengine_setlocalrendertargetfps) 和 [`setRemoteRenderTargetFps`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-rendering#api_irtcengine_setremoterendertargetfps) 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。 在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。 #### 滤镜效果 [#滤镜效果-8] 该版本新增 [`setFilterEffectOptions`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/video-enhance-option#api_irtcengine_setfiltereffectoptions) 方法，你可以在 `config` 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 `built_in_whiten_filter.cube` 文件，用于快速实现美白滤镜效果。 #### 本地音频合流 [#本地音频合流-8] 该版本新增本地音频合流功能，你可以调用 [`startLocalAudioMixer`](/zh-CN/api-reference/rtc/unreal-cpp/audio/audiomixer#api_irtcengine_startlocalaudiomixer) 方法，将本地麦克风采集的音频流、媒体播放器中的音频流、声卡采集的音频流、远端音频流等合并为一路音频流，你可以将合并后的音频流发布到频道中。不再需要音频合流时，你可以调用 [`stopLocalAudioMixer`](/zh-CN/api-reference/rtc/unreal-cpp/audio/audiomixer#api_irtcengine_stoplocalaudiomixer) 方法停止本地音频合流；在合流过程中，可以调用 [`updateLocalAudioMixerConfiguration`](/zh-CN/api-reference/rtc/unreal-cpp/audio/audiomixer#api_irtcengine_updatelocalaudiomixerconfiguration) 方法更新正在合流的音频流配置。 该功能的使用场景示例如下： - 结合本地合图功能一起使用，可将合图视频流相关的音频流同步采集和发布。 - 在直播场景下，用户接收频道内的音频流，在本地进行多路音频流合流后转发到其他频道。 - 在教育场景下，老师可将跟学生连麦互动的音频在本地进行合流，然后将合并的音频流转发到其他频道。 #### 外部 MediaProjection (Android) [#外部-mediaprojection-android-3] 该版本新增 [`setExternalMediaProjection`](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_setexternalmediaprojection) 方法，该方法支持你自行设置外部 `Medi aProjection`，并取代 SDK 申请的 `MediaProjection`。 如果你具备自行申请 `MediaProjection` 的开发能力，可通过该功能实现更加灵活的屏幕采集。 #### EGL 环境上下文 (Android) [#egl-环境上下文-android-3] 该版本新增了 [`setExternalRemoteEglContext`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-custom-capturenrendering#api_irtcengine_setexternalremoteeglcontext) 方法，用于设置远端视频流渲染的 EGL 环境上下文。使用 Texture 格式的视频数据进行远端视频自渲染时，你可以通过该方法替换 SDK 默认的远端 EGL 环境上下文，实现统一的 EGL 上下文管理。 #### 色彩空间设置 [#色彩空间设置-8] 该版本在 [`VideoFrame`](/zh-CN/api-reference/rtc/unreal-cpp/class-videoframe) 和 [`ExternalVideoFrame`](/zh-CN/api-reference/rtc/unreal-cpp/class-externalvideoframe) 中新增了 `colorSpace`，你可以通过该参数设置视频帧的色彩空间属性。默认情况下，色彩空间采用 Full Range 和 BT.709 标准配置，你可以根据自采集或自渲染的需求灵活调整，进一步提升视频处理的定制化能力。 #### 其他 [#其他-37] - [`onLocalVideoStateChanged`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调新增 `LOCAL_VIDEO_STREAM_REASON_DEVICE_DISCONNECTED` 枚举，表示当前正在使用的视频采集设备已经断开连接（例如，被拔出）。(Windows) - [`MEDIA_DEVICE_STATE_TYPE`](/zh-CN/api-reference/rtc/unreal-cpp/enum-mediadevicestatetype) 新增 `MEDIA_DEVICE_STATE_PLUGGED_IN` 枚举，表示设备已插入。(Windows) ### 改进 [#改进-161] #### 虚拟背景算法优化 [#虚拟背景算法优化-16] 该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。 #### 录制本地预览视频 [#录制本地预览视频-8] 该版本在 [`RecorderStreamInfo`](/zh-CN/api-reference/rtc/unreal-cpp/class-recorderstreaminfo) 中新增 `type` 成员。当调用 [`createMediaRecorder`](/zh-CN/api-reference/rtc/unreal-cpp/recording#api_irtcengine_createmediarecorder) 时，可通过该成员指定录制的视频流类型为本地预览视频流，并在 [`MediaRecorderConfiguration`](/zh-CN/api-reference/rtc/unreal-cpp/class-mediarecorderconfiguration) 中设置录制预览视频的高、宽、帧率、采样率等参数，之后调用 [`startRecording`](/zh-CN/api-reference/rtc/unreal-cpp/recording#api_imediarecorder_startrecording) 即可开始录制本地预览的视频。 #### 指定视频观测位置截图 [#指定视频观测位置截图-8] 该版本新增 [`takeSnapshot`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/snapshot#api_irtcengine_takesnapshot2)[2/2] 和 [`takeSnapshotEx`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex2)[2/2] 方法，你可以在调用该方法时通过 `config` 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。 #### 自定义音频采集改进 [#自定义音频采集改进-8] 该版本在 [`AudioTrackConfig`](/zh-CN/api-reference/rtc/unreal-cpp/class-audiotrackconfig) 中新增了 `enableAudioProcessing` 成员参数，用于控制是否对 `AUDIO_TRACK_DIRECT` 类型的自定义音频采集轨道启用 3A 音频处理。该参数默认值为 `false`，即不启用音频处理，用户可以按需开启，此项改动提升了自定义音频处理的灵活性。 #### 其他改进 [#其他改进-70] - 通过拼接视频帧和 Alpha 数据实现 Alpha 透明特效的应用场景下，提升了接收端的渲染性能，有效减少卡顿和延迟。（Android, iOS） - 优化了调用 [`queryDeviceScore`](/zh-CN/api-reference/rtc/unreal-cpp/network#api_irtcengine_querydevicescore) 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。 - 支持使用 YV 12 格式的虚拟摄像头作为视频采集设备。(Windows) - 频道内调用 [`enableLocalAudio`](/zh-CN/api-reference/rtc/unreal-cpp/audio/audio-capture#api_irtcengine_enablelocalaudio) 关闭本地采集后，支持通过手机静音侧键把 App 播放的背景音效设置为静音状态。(iOS) - 调用 [`switchSrc`](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 [`onPlayerEvent`](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent) 回调报告 `PLAYER_EVENT_SWITCH_ERROR` 事件，表示媒体资源切换时发生错误。 - 调用 [`setPlaybackSpeed`](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，最低支持 0.3 倍速播放。 ### 问题修复 [#问题修复-169] 该版本修复了以下问题： - 调用 [`startScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/unreal-cpp/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享屏幕时，通过 `regionRect` 指定的窗口采集区域不准确，导致接收端看到的屏幕共享窗口宽高错误。（Windows） - 当发送端视频源类型为 JPEG 格式时，偶现接收端帧率低于预期。(Android、iOS) - 在播放音乐内容中心的音乐资源时，偶现杂音和卡顿。(Android) - 在 App 没有获取麦克风权限时，通过 [`IMusicPlayer`](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusicplayer) 播放伴奏音乐偶现卡顿。(Android) - 音视频互动过程中被系统来电打断后，通过 `onAudioVolumeIndication` 回调上报的用户音量错误。(Android) - 在接收端默认订阅视频小流、加入频道时不自动订阅任何视频流的前提下，加入频道后调用 `muteRemoteVideoStream(uid,false)` 恢复接收视频流，但接收到的视频流为视频大流，不符合预期。(Android) - Windows 7 系统下进行音视频互动，偶现找不到系统文件的报错。(Windows) - 调用 [`followSystemRecordingDevice`](/zh-CN/api-reference/rtc/unreal-cpp/device-management/audio-device#api_iaudiodevicemanager_followsystemrecordingdevice) 或 [`followSystemPlaybackDevice`](/zh-CN/api-reference/rtc/unreal-cpp/device-management/audio-device#api_iaudiodevicemanager_followsystemplaybackdevice) 设置 SDK 使用的音频采集或播放设备不跟随系统默认的音频播放设备，当音频设备被移除时，本地音频状态回调 [`onLocalAudioStateChanged`](/zh-CN/api-reference/rtc/unreal-cpp/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) 没有被触发，不符合预期。(Windows) - 音视频互动过程中，偶现接收端听发送端没有声音。(iOS) - 音视频互动过程中，如果发送端设备的系统版本为 iOS 17，偶现接收端听不到来自发送端的声音。(iOS) - 直播场景下，观众端因切换网络导致断开连接，重新连接直播间花费的时间长于预期。(iOS) - App 启动后使用媒体播放器播放在线媒体资源，播放无声。(iOS) - 音视频互动过程中被系统其他 App 打断后恢复，偶现音频采集无声。(iOS) - 调用 [`startAudioMixing`](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-mixing#api_irtcengine_startaudiomixing)[1/2] 后，立即调用 [`pauseAudioMixing`](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-mixing#api_irtcengine_pauseaudiomixing) 暂停播放音乐文件不生效。 ## v4.4.0 [#v440-9] 该版本于 2024 年 8 月 29 日发布。 ### 升级必看 [#升级必看-100] #### 调用方式变更 [#调用方式变更] 该版本引擎实例的创建和销毁操作改为使用 [`Get`](/zh-CN/api-reference/rtc/unreal-cpp/initialize#api_createagorartcengine) 和 [`Release`](/zh-CN/api-reference/rtc/unreal-cpp/initialize#api_irtcengine_release) 方法，取代了之前的 `createAgoraRtcEngine` 和 `release`，这一改动简化了实例管理。详情如下： - 创建引擎实例：调用 [`Get`](/zh-CN/api-reference/rtc/unreal-cpp/initialize#api_createagorartcengine) 创建一个 [`IRtcEngine`](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) 实例并返回一个指向 `AgoraUERtcEngine` 的指针，你可以直接通过该指针调用 [`IRtcEngine`](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) 下的方法。 ```cpp // 以调用 joinChannel 加入频道为例 AgoraUERtcEngine::Get()->joinChannel(TCHAR_TO_UTF8(*Token), TCHAR_TO_UTF8(*ChannelName), 0, ChannelMediaOptions); ``` - 销毁引擎实例：调用 [`Get`](/zh-CN/api-reference/rtc/unreal-cpp/initialize#api_createagorartcengine) 创建实例后，如无需再使用该实例，务必调用 [`Release`](/zh-CN/api-reference/rtc/unreal-cpp/initialize#api_irtcengine_release) 以销毁引擎实例并释放相关资源。 ```cpp AgoraUERtcEngine::Release(); ``` ### 新增特性 [#新增特性-141] #### AI 调音器 [#ai-调音器-8] 该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 [`enableVoiceAITuner`](/zh-CN/api-reference/rtc/unreal-cpp/audio/audio-prenpost/audio-effect#api_irtcengine_enablevoiceaituner) 方法并传入 [`VOICE_AI_TUNER_TYPE`](/zh-CN/api-reference/rtc/unreal-cpp/enum-voiceaitunertype) 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。 #### 隐私清单文件 (iOS) [#隐私清单文件-ios-3] 为满足 Apple 对于 App 发布的安全合规要求，SDK 自该版本起新增隐私清单文件 `PrivacyInfo.xcprivacy`，其中包含 SDK 中需要访问或使用用户数据的 API 调用说明和 SDK 采集的数据类型说明。 :::warning[注意] 如果你需要将集成该版本之前的 SDK 版本的 App 发布到苹果应用商店，则需要在 Xcode 工程中手动添加 `PrivacyInfo.xcprivacy` 文件。详见[如何在 App 中增加隐私清单？](/zh-CN/reference/faq/other/ios_privacy_manifest) ::: #### 摄像头多路采集 (Android) [#摄像头多路采集-android-3] 该版本针对 Android 摄像头采集新增以下功能： 1. 支持第三个和第四个摄像头视频流的采集和发布。 - [`VIDEO_SOURCE_TYPE`](/zh-CN/api-reference/rtc/unreal-cpp/enum-videosourcetype) 中的 `VIDEO_SOURCE_CAMERA_THIRD`(11) 和 `VIDEO_SOURCE_CAMERA_FOURTH`(12) 枚举新增对 Android 的支持，分别用于指定视频源为第三个和第四个摄像头。此项改动允许你在调用 [`startCameraCapture`](/zh-CN/api-reference/rtc/unreal-cpp/video/camera-capture#api_irtcengine_startcameracapture) 开启摄像头采集时，指定最多 4 路摄像头采集的视频流。 - [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unreal-cpp/class-channelmediaoptions) 中的 `publishThirdCameraTrack` 和 `publishFourthCameraTrack` 成员新增对 Android 的支持。调用 [`joinChannel`](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_joinchannel2)[2/2] 加入频道时，将这两个成员参数设置为 `true` 即可在频道内发布第三个和第四个摄像头采集的视频流。 2. 支持通过摄像头 ID 指定摄像头。 在 [`CameraCapturerConfiguration`](/zh-CN/api-reference/rtc/unreal-cpp/class-cameracapturerconfiguration) 中新增 `cameraId` 成员。对于多摄像头的设备，`cameraDirection` 无法识别或访问全部可用摄像头。这种情况下，你通过系统 API 获取摄像头 ID，再调用 [`startCameraCapture`](/zh-CN/api-reference/rtc/unreal-cpp/video/camera-capture#api_irtcengine_startcameracapture) 并传入 `cameraId` 指定摄像头。 #### 本地播放及发布至远端的音轨控制 [#本地播放及发布至远端的音轨控制-8] 该版本新增 [`selectMultiAudioTrack`](/zh-CN/api-reference/rtc/unreal-cpp/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。使用该功能前，需要通过 [`openWithMediaSource`](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并通过 [`MediaSource`](/zh-CN/api-reference/rtc/unreal-cpp/class-mediasource) 中新增的 `enableMultiAudioTrack` 成员来开启音轨控制。 #### 本地截图上传更新 [#本地截图上传更新-8] 为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动： - [`CONTENT_INSPECT_TYPE`](/zh-CN/api-reference/rtc/unreal-cpp/enum-contentinspecttype) 中新增 `CONTENT_INSPECT_IMAGE_MODERATION` 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。 - [`ContentInspectConfig`](/zh-CN/api-reference/rtc/unreal-cpp/class-contentinspectconfig) 中新增的 `serverConfig` 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请[联系技术支持](https://ticket.shengwang.cn/)。 此外，该版本还新增了 [`enableContentInspectEx`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) 方法，支持同时对多条视频流截图并上传。 #### 支持 ID3D11Texture2D 渲染 (Windows) [#支持-id3d11texture2d-渲染-windows-2] 自该版本起，SDK 支持 ID3D11Texture2D 类型的视频格式，提升了游戏场景中视频帧的渲染效果。你可以在调用 [`pushVideoFrame`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe) 方法将外部原始视频帧推送到 SDK 时，设置 `format` 为 `VIDEO_TEXTURE_ID3D11TEXTURE2D`；并通过设置 `textureSliceIndex` 属性，来确定要使用的 ID3D11Texture2D 纹理对象。 #### 通配 Token [#通配-token-8] 该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 :::warning[注意] 声网 4.x RTC SDK 均支持使用通配 Token。 ::: #### 预加载频道 [#预加载频道-9] 该版本新增 [`preloadChannel`](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_preloadchannel) 和 [`preloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/unreal-cpp/channel#api_irtcengine_preloadchannelwithuseraccount) 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。 在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 #### 发布多源采集的视频流 (Windows, macOS) [#发布多源采集的视频流-windows-macos-2] 该版本在 [`ChannelMediaOptions`](/zh-CN/api-reference/rtc/unreal-cpp/class-channelmediaoptions) 中新增下列成员，支持你发布第三个、第四个摄像头和屏幕采集到的视频流： - `publishThirdCameraTrack`：发布第三个摄像头采集的视频。 - `publishFourthCameraTrack`：发布第四个摄像头采集的视频。 - `publishThirdScreenTrack`：发布第三个屏幕采集的视频。 - `publishFourthScreenTrack`：发布第四个屏幕采集的视频。 :::warning[注意] 目前 SDK 支持在同一时间、同一 `RtcConnection` 中发布多路音频流、一路视频流。 ::: ### 改进 [#改进-162] #### 头文件管理简化 [#头文件管理简化] 如需引用其他头文件，你可以将它们统一添加到 `AgoraHeaderBase.h` 中，以简化项目中头文件的管理、便于后续维护。 #### 跨频道连麦优化 [#跨频道连麦优化-8] 该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 [`startOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/unreal-cpp/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`startOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unreal-cpp/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 时，你可以指定最多 6 个目标频道。 ### 问题修复 [#问题修复-170] 在 Unreal Engine 5.3 和 5.4 版本中，当你在项目的 `/Source/xxx.Target.cs` 文件添加以下代码以解决 iOS 内存分配问题时，可能会导致 iOS 编译符号缺失。为解决这一问题，该版本在 `UnrealMemory.cpp` 文件中添加了 3 个与标准库相关的函数定义 (`StdMalloc`、`StdRealloc` 和 `StdFree`)，确保在使用标准内存分配器时能够正确处理内存管理需求。(iOS) ```csharp if (Target.Platform == UnrealTargetPlatform.IOS) { bOverrideBuildEnvironment = true; GlobalDefinitions.Add("FORCE_ANSI_ALLOCATOR=1"); } ``` ## v4.2.1 [#v421-9] 该版本于 2023 年 11 月 16 日发布，该版本为声网 RTC Unreal SDK 的首个版本。 #### 功能简介 [#功能简介-1] 该 SDK 由声网为使用 Unreal 的开发者而设计，旨在为 Unreal Engine 用户提供简单且用户友好的实时互动解决方案。 SDK 提供了一套强大的 C++ API，使开发者可以轻松构建具备实时互动功能的游戏或者 App，并可以借助 Unreal Engine 强大的图形引擎功能，为 App 添加各种视觉效果和交互性能，为用户提供更加沉浸式的体验。 #### 参考文档 [#参考文档-1] 你可以参考以下文档集成 SDK，实现相应的实时音视频功能： - [跑通 API 示例项目](/zh-CN/realtime-media/rtc/get-started/run-demo) - [实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start) - [实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start) - [实现纯语音互动](/zh-CN/realtime-media/rtc/build/audio/audio-quick-start) - [API 参考](/zh-CN/api-reference/rtc/unreal-cpp/rtc-api-overview) 声网提供了开源的[示例项目](https://github.com/AgoraIO-Extensions/Agora-Unreal-RTC-SDK/tree/main/Agora-Unreal-SDK-CPP-Example)，你可以前往下载并体验。 :::note[信息] 如果你已经集成了 3.x 版本的 SDK、想要升级至该版本，请参考[迁移指南](https://github.com/AgoraIO-Extensions/Agora-Unreal-RTC-SDK/blob/main/Migration%20Guide.md)了解升级。 ::: <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="blueprint" /> ### 已知问题和局限性 [#已知问题和局限性-6] **音频模块不兼容 (iOS)** 声网 Unreal SDK 的音频模块与 Unreal Engine 5.3、5.4 的 AudioMixer 模块不兼容。如果你使用 Unreal Engine 5.3 或 5.4，需要在项目的 `/Config/IOS/IOSEngine.ini` 文件中添加以下代码，关闭 Unreal Engine 的 AudioMixer 模块，以避免冲突。 ```ini [Audio] AudioMixerModuleName= ``` ## v4.5.1 [#v451-6] 该版本于 2025 年 3 月 13 日发布。 ### 新增特性 [#新增特性-142] #### AI 对话场景 [#ai-对话场景-9] 该版本新增了专为与[声网对话式 AI 引擎](/zh-CN/ai)创建的智能体互动设计的 `AUDIO_SCENARIO_AI_CLIENT` 音频场景。该场景根据 AI 智能体生成语音的特点，针对优化了音频传输算法，能够在弱网环境下（例如 80% 丢包率）稳定传输语音数据，确保对话的连续性和可靠性，适应多样化的复杂网络条件。 ### 改进 [#改进-163] 1. 优化了特定机型上 SDK 初始化的耗时。(iOS) ### 问题修复 [#问题修复-171] 该版本修复了以下问题： - 集成 SDK 的 App 设置 `targetSdkVersion` 为 34，在 Android 14 系统上首次开启屏幕共享进行授权时出现崩溃。(Android) - 同时加入两个及以上的频道，连续调用 [`TakeSnapshotEx`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex) 分别对频道中的本地视频流进行截图，在先调用的频道截图会失败。 - 使用媒体播放器时，调用 [`Pause`](/zh-CN/api-reference/rtc/unreal-blueprint/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause) 暂停播放后，调用 [`Seek`](/zh-CN/api-reference/rtc/unreal-blueprint/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 定位到指定播放位置、然后调用 [`Play`](/zh-CN/api-reference/rtc/unreal-blueprint/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 继续播放，播放时会先从暂停播放的位置播放，然后再从新的位置播放。 - 使用媒体播放器时，调用 [`SwitchSrc`](/zh-CN/api-reference/rtc/unreal-blueprint/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换媒体资源后，调用 [`GetPlaySrc`](/zh-CN/api-reference/rtc/unreal-blueprint/play/mediaplayer/mediaplayer-info#api_imediaplayer_getplaysrc) 获取当前正在播放的媒体资源的路径没有变化。 - 用户在特定机型上进行音视频互动并使用蓝牙耳机，偶现调整手机音量后改变的是媒体音量而非蓝牙音量。(Android) - 音视频互动时，偶现接收端观看发送端画面出现黑屏。(Android) - 在特定机型上，调用 [`SetCameraExposureFactor`](/zh-CN/api-reference/rtc/unreal-blueprint/device-management/video-device#api_irtcengine_setcameraexposurefactor) 在设备的某个特定角度设置当前摄像头的曝光系数后，当设备移动到另一个角度时，偶现视频画面变暗。(Android) - 播放 CDN 直播流时，直播流短暂中断后恢复，偶现播放画面长时间卡住。(Android) - 在推送 i420 格式的视频帧到频道内时，使用 CVPixelBuffer 会导致崩溃。(iOS) - 调用 [`SetupLocalVideo`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-rendering#api_irtcengine_setuplocalvideo) 设置两个视图（view），然后调用 [`EnableFaceDetection`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/face-detection#api_irtcengine_enablefacedetection) 开启人脸检测，后传入的视图中无法检测到人脸信息。(iOS) - 屏幕共享场景下，接收端用户看到的共享图像出现绿线。(iOS) - 在极速直播场景下，观众通过 `string` 型的用户 ID 加入频道观看直播，偶现音频和画面不同步。 - 在同时使用 AI 降噪、AI 回声消除插件时，偶现插件不生效。 ## v4.5.0 [#v450-9] 该版本于 2024 年 12 月 10 日发布。 ### 升级必看 [#升级必看-101] 该版本对部分功能的实现方式进行了优化，涉及 SDK 的行为变更、API 的改名或删除，为确保项目的正常运行，你需要在升级到该版本后更新 App 中的代码。 #### 强效视频降噪实现变更 [#强效视频降噪实现变更-9] 该版本调整了强效视频降噪的实现方式，在 [`EUABT_VIDEO_DENOISER_LEVEL`](/zh-CN/api-reference/rtc/unreal-blueprint/enum-videodenoiserlevel) 中删除了 `VIDEO_DENOISER_LEVEL_STRENGTH`，改为调用 [`SetVideoDenoiserOptions`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions) 启用视频降噪后，调用 [`SetBeautyEffectOptions`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/video-enhance-option#api_irtcengine_setbeautyeffectoptions) 方法启用美颜磨皮功能，二者搭配使用以获得更好的视频降噪效果。实现强效降噪时，推荐磨皮参数设置详见 [`SetVideoDenoiserOptions`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/video-enhance-option#api_irtcengine_setvideodenoiseroptions)。 此外，受该调整影响，实现画质优先的暗光增强效果时，需要先开启视频降噪并采用特定设置，详见 [`SetLowlightEnhanceOptions`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/video-enhance-option#api_irtcengine_setlowlightenhanceoptions)。 #### 摄像头插拔状态变更 (macOS, Windows) [#摄像头插拔状态变更-macos-windows-4] 在之前版本中，当摄像头拔出并重新插入时，[`OnVideoDeviceStateChanged`](/zh-CN/api-reference/rtc/unreal-blueprint/device-management/video-device#callback_irtcengineeventhandler_onvideodevicestatechanged) 回调会将设备状态报告为 `MEDIA_DEVICE_STATE_ACTIVE(1)`（设备正在使用）。该版本起，摄像头重新插入后，设备状态将改为 `MEDIA_DEVICE_STATE_IDLE(0)`（设备就绪）。 #### 视频编码偏好变更 [#视频编码偏好变更-9] 为提升用户的视频互动体验，该版本优化了视频编码时的默认偏好： - 在 [`ECOMPRESSION_PREFERENCE`](/zh-CN/api-reference/rtc/unreal-blueprint/enum-compressionpreference) 枚举类中新增 `PREFER_COMPRESSION_AUTO (-1)` 枚举，并替代原有的 `PREFER_QUALITY (1)` 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `PREFER_LOW_LATENCY` 或 `PREFER_QUALITY`，以获得最佳的用户体验。 - 在 [`EUABT_DEGRADATION_PREFERENCE`](/zh-CN/api-reference/rtc/unreal-blueprint/enum-degradationpreference) 枚举类中新增 `MAINTAIN_AUTO (-1)` 枚举，并替代原有的 `MAINTAIN_QUALITY (1)` 作为默认值。在该模式下，SDK 会根据你设置的视频场景，自动选择 `MAINTAIN_FRAMERATE`、`MAINTAIN_BALANCED` 或 `MAINTAIN_RESOLUTION`，以获得最优的综合质量体验 (QoE)。 #### 16 KB 内存页大小 (Android) [#16-kb-内存页大小-android-1] 自 Android 15 起，系统新增了对 16 KB 内存页大小的支持，详见 [Support 16 KB page sizes](https://developer.android.com/guide/practices/page-sizes?hl=zh-cn)。为了保证 App 的稳定性和性能表现，自该版本起，SDK 支持 16 KB 内存页大小，确保可以在使用 4 KB 和 16 KB 内存页大小的设备上无缝运行，提升兼容性并避免崩溃。 ### 新增特性 [#新增特性-143] #### 高级美颜 [#高级美颜-9] 该版本新增以下两种高级美颜功能： - 美型：调用 [`SetFaceShapeBeautyOptions`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapebeautyoptions) 方法，可对人脸各部位进行修饰，你可以使用预设的模板一次性实现瘦脸、大眼、瘦鼻等微整形效果，并微调整体的修饰力度。如果预设的美型效果不能满足你的需求，你可以调用 [`SetFaceShapeAreaOptions`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/video-enhance-option#api_irtcengine_setfaceshapeareaoptions) 方法设置美型部位选项，对人脸的各个部位单独微调，实现更加精细的美型效果。 - 美妆：调用 [`SetExtensionProperty`](/zh-CN/api-reference/rtc/unreal-blueprint/extension#api_irtcengine_setextensionproperty) 方法，传入指定参数，可实现眼影、美瞳、眼线、美眉、唇彩、腮红等美妆特效。 :::info[信息] 目前，高级美颜功能为**限时免费**，详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ::: #### 秀场直播场景 [#秀场直播场景-9] 该版本在 [`EVIDEO_APPLICATION_SCENARIO_TYPE`](/zh-CN/api-reference/rtc/unreal-blueprint/enum-videoapplicationscenariotype) 类下新增枚举 `APPLICATION_SCENARIO_LIVESHOW(3)`（秀场直播），你可以调用 [`SetVideoScenario`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-basic#api_irtcengine_setvideoscenario) 将视频业务场景设置为秀场直播。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，例如，默认开启音视频加速渲染来提升首帧出图体验，无需再额外调用 `enableInstantMediaRendering`，同时增强了在弱网环境和低端设备上的画质和流畅度表现。 #### 限制视频渲染帧率 [#限制视频渲染帧率-9] 该版本新增 [`SetLocalRenderTargetFps`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-rendering#api_irtcengine_setlocalrendertargetfps) 和 [`SetRemoteRenderTargetFps`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-rendering#api_irtcengine_setremoterendertargetfps) 方法，支持设置视频在本地和远端渲染时的最大帧率，SDK 进行视频渲染的实际帧率会尽量接近该值。 在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以通过这一组方法限制视频渲染帧率，从而减小 CPU 消耗、提升系统性能。 #### 滤镜效果 [#滤镜效果-9] 该版本新增 [`SetFilterEffectOptions`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/video-enhance-option#api_irtcengine_setfiltereffectoptions) 方法，你可以在 `config` 参数中传入指定格式的立方体贴图文件 (.cube)，从而实现美白、鲜艳、冷色、黑白等自定义滤镜效果。此外，SDK 提供了一个内置的 `built_in_whiten_filter.cube` 文件，用于快速实现美白滤镜效果。 #### 其他 [#其他-38] - [`OnLocalVideoStateChanged`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调新增 `LOCAL_VIDEO_STREAM_REASON_DEVICE_DISCONNECTED` 枚举，表示当前正在使用的视频采集设备已经断开连接（例如，被拔出）。(Windows) - [`EMEDIA_DEVICE_STATE_TYPE`](/zh-CN/api-reference/rtc/unreal-blueprint/enum-mediadevicestatetype) 新增 `MEDIA_DEVICE_STATE_PLUGGED_IN` 枚举，表示设备已插入。(Windows) ### 改进 [#改进-164] #### 虚拟背景算法优化 [#虚拟背景算法优化-17] 该版本升级了虚拟背景的算法，分割人像主体部分与背景时更加准确，背景无露出，人像身体轮廓无缺块，手指细节辨识显著提高。同时，人像与背景的边缘更加稳定，减少了连续视频帧中人像边缘的跳变和闪烁现象。 #### 指定视频观测位置截图 [#指定视频观测位置截图-9] 该版本新增 [`TakeSnapshotWithConfig`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/snapshot#api_irtcengine_takesnapshot2) 和 [`TakeSnapshotWithConfigEx`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/snapshot#api_irtcengineex_takesnapshotex2) 方法，你可以在调用该方法时通过 `config` 参数，在指定的视频观测点进行截图，比如：编码前、编码后或渲染前的数据，以实现更加灵活的截图效果。 #### 其他改进 [#其他改进-71] - 通过拼接视频帧和 Alpha 数据实现 Alpha 透明特效的应用场景下，提升了接收端的渲染性能，有效减少卡顿和延迟。（Android, iOS） - 优化了调用 [`QueryDeviceScore`](/zh-CN/api-reference/rtc/unreal-blueprint/network#api_irtcengine_querydevicescore) 获取设备评分等级的设计逻辑，提升了等级评分结果的准确性。 - 支持使用 YV 12 格式的虚拟摄像头作为视频采集设备。(Windows) - 频道内调用 [`EnableLocalAudio`](/zh-CN/api-reference/rtc/unreal-blueprint/audio/audio-capture#api_irtcengine_enablelocalaudio) 关闭本地采集后，支持通过手机静音侧键把 App 播放的背景音效设置为静音状态。(iOS) - 调用 [`SwitchSrc`](/zh-CN/api-reference/rtc/unreal-blueprint/play/mediaplayer/mediaplayer-open#api_imediaplayer_switchsrc) 切换不同分辨率的直播流或点播流时，可以实现平滑且无感知的切换效果，并在切换失败时新增自动重试机制。SDK 会在切换失败后自动重试 3 次，如果依旧失败，会通过 [`OnPlayerEvent`](/zh-CN/api-reference/rtc/unreal-blueprint/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent) 回调报告 `PLAYER_EVENT_SWITCH_ERROR` 事件，表示媒体资源切换时发生错误。 - 调用 [`SetPlaybackSpeed`](/zh-CN/api-reference/rtc/unreal-blueprint/play/mediaplayer/mediaplayer-playnrender#api_imediaplayer_setplaybackspeed) 设置音频文件的播放速度时，最低支持 0.3 倍速播放。 ### 问题修复 [#问题修复-172] 该版本修复了以下问题： - 调用 [`StartScreenCaptureByWindowId`](/zh-CN/api-reference/rtc/unreal-blueprint/video/screencapture#api_irtcengine_startscreencapturebywindowid) 共享屏幕时，通过 `regionRect` 指定的窗口采集区域不准确，导致接收端看到的屏幕共享窗口宽高错误。（Windows） - 当发送端视频源类型为 JPEG 格式时，偶现接收端帧率低于预期。(Android、iOS) - 在播放音乐内容中心的音乐资源时，偶现杂音和卡顿。(Android) - 在 App 没有获取麦克风权限时，通过 播放伴奏音乐偶现卡顿。(Android) - 音视频互动过程中被系统来电打断后，通过 `OnAudioVolumeIndication` 回调上报的用户音量错误。(Android) - 在接收端默认订阅视频小流、加入频道时不自动订阅任何视频流的前提下，加入频道后调用 `MuteRemoteVideoStream(uid,false)` 恢复接收视频流，但接收到的视频流为视频大流，不符合预期。(Android) - Windows 7 系统下进行音视频互动，偶现找不到系统文件的报错。(Windows) - 调用 [`FollowSystemRecordingDevice`](/zh-CN/api-reference/rtc/unreal-blueprint/device-management/audio-device#api_iaudiodevicemanager_followsystemrecordingdevice) 或 [`FollowSystemPlaybackDevice`](/zh-CN/api-reference/rtc/unreal-blueprint/device-management/audio-device#api_iaudiodevicemanager_followsystemplaybackdevice) 设置 SDK 使用的音频采集或播放设备不跟随系统默认的音频播放设备，当音频设备被移除时，本地音频状态回调 [`OnLocalAudioStateChanged`](/zh-CN/api-reference/rtc/unreal-blueprint/audio/audio-basic#callback_irtcengineeventhandler_onlocalaudiostatechanged) 没有被触发，不符合预期。(Windows) - 音视频互动过程中，偶现接收端听发送端没有声音。(iOS) - 音视频互动过程中，如果发送端设备的系统版本为 iOS 17，偶现接收端听不到来自发送端的声音。(iOS) - 直播场景下，观众端因切换网络导致断开连接，重新连接直播间花费的时间长于预期。(iOS) - App 启动后使用媒体播放器播放在线媒体资源，播放无声。(iOS) - 音视频互动过程中被系统其他 App 打断后恢复，偶现音频采集无声。(iOS) - 调用 [`PauseAudioMixing`](/zh-CN/api-reference/rtc/unreal-blueprint/play/audio-mixing#api_irtcengine_pauseaudiomixing) 暂停播放音乐文件不生效。(iOS) - 音视频互动过程中偶现崩溃。(Android) ## v4.4.0 [#v440-10] 该版本于 2024 年 8 月 29 日发布。 ### 升级必看 [#升级必看-102] 该版本简化了在蓝图中调用方法和实现回调的方式。 #### 方法调用 [#方法调用] 该版本无需手动维护实例的变量。你可以在蓝图中的任意位置，通过 `Get` 节点直接获取所需的类，并连接相应的函数节点来完成调用。这一改进使得在蓝图中调用方法更加便捷，简化了开发流程。 下图演示通过 [`GetAgoraRtcEngine`](/zh-CN/api-reference/rtc/unreal-blueprint/initialize#api_createagorartcengine) 创建 [`IRtcEngine`](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine) 实例，并连接 [`Initialize`](/zh-CN/api-reference/rtc/unreal-blueprint/initialize#api_irtcengine_initialize) 节点进行初始化操作。 #### 回调实现 [#回调实现] 该版本引入了 `CallbackExecutor` 的概念。你可以在蓝图中通过 `EventHandler` 绑定对应的 `CallbackExecutor`，从而执行回调。这一改进带来以下优势： - 回调的实现更加便捷。 - 提升安全性，绑定即可执行回调，销毁也不会导致崩溃。 - 易于复用和代码管理。 下图演示通过 [`GetEventHandler`](/zh-CN/api-reference/rtc/unreal-blueprint/initialize#api_irtcengine_geteventhandler) 节点获取 `EventHandler`，并连接 [`AddBlueprintCallbackExecutor`](/zh-CN/api-reference/rtc/unreal-blueprint/initialize#api_irtcengine_addblueprintcallbackexecutor) 节点绑定指定的 `CallbackExecutor`，从而执行 [`IRtcEngineEventHandler`](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengineeventhandler) 接口类下的相关回调。 ![CBExecutor 示例](https://web-cdn.agora.io/docs-portal/img/rtc/ue-bp-release440-04.png) ### 新增特性 [#新增特性-144] #### AI 调音器 [#ai-调音器-9] 该版本新增 AI 调音器功能，可以实现类似物理声卡对音质和音色的提升。你可以通过调用 [`EnableVoiceAITuner`](/zh-CN/api-reference/rtc/unreal-blueprint/audio/audio-prenpost/audio-effect#api_irtcengine_enablevoiceaituner) 方法并传入 [`EVOICE_AI_TUNER_TYPE`](/zh-CN/api-reference/rtc/unreal-blueprint/enum-voiceaitunertype) 枚举中支持的音效类型来启用 AI 调音器功能，实现大叔音、萝莉音、烟嗓歌声等声音效果。 #### 隐私清单文件 (iOS) [#隐私清单文件-ios-4] 为满足 Apple 对于 App 发布的安全合规要求，SDK 自该版本起新增隐私清单文件 `PrivacyInfo.xcprivacy`，其中包含 SDK 中需要访问或使用用户数据的 API 调用说明和 SDK 采集的数据类型说明。 :::warning[注意] 如果你需要将集成该版本之前的 SDK 版本的 App 发布到苹果应用商店，则需要在 Xcode 工程中手动添加 `PrivacyInfo.xcprivacy` 文件。详见[如何在 App 中增加隐私清单？](/zh-CN/reference/faq/other/ios_privacy_manifest) ::: #### 摄像头多路采集 (Android) [#摄像头多路采集-android-4] 该版本针对 Android 摄像头采集新增以下功能： 1. 支持第三个和第四个摄像头视频流的采集和发布。 - `EVIDEO_SOURCE_TYPE` 中的 `VIDEO_SOURCE_CAMERA_THIRD`(11) 和 `VIDEO_SOURCE_CAMERA_FOURTH`(12) 枚举新增对 Android 的支持，分别用于指定视频源为第三个和第四个摄像头。此项改动允许你在调用 [`StartCameraCapture`](/zh-CN/api-reference/rtc/unreal-blueprint/video/camera-capture#api_irtcengine_startcameracapture) 开启摄像头采集时，指定最多 4 路摄像头采集的视频流。 - [`FChannelMediaOptions`](/zh-CN/api-reference/rtc/unreal-blueprint/class-channelmediaoptions) 中的 `publishThirdCameraTrack` 和 `publishFourthCameraTrack` 成员新增对 Android 的支持。调用 [`JoinChannelWithOptions`](/zh-CN/api-reference/rtc/unreal-blueprint/channel#api_irtcengine_joinchannel2) 加入频道时，将这两个成员参数设置为 `true` 即可在频道内发布第三个和第四个摄像头采集的视频流。 2. 支持通过摄像头 ID 指定摄像头。 在 [`FCameraCapturerConfiguration`](/zh-CN/api-reference/rtc/unreal-blueprint/class-cameracapturerconfiguration) 中新增 `cameraId` 成员。对于多摄像头的设备，`cameraDirection` 无法识别或访问全部可用摄像头。这种情况下，你通过系统 API 获取摄像头 ID，再调用 [`StartCameraCapture`](/zh-CN/api-reference/rtc/unreal-blueprint/video/camera-capture#api_irtcengine_startcameracapture) 并传入 `cameraId` 指定摄像头。 #### 本地播放及发布至远端的音轨控制 [#本地播放及发布至远端的音轨控制-9] 该版本新增 [`SelectMultiAudioTrack`](/zh-CN/api-reference/rtc/unreal-blueprint/play/audio-mixing#api_imediaplayer_selectmultiaudiotrack) 方法，支持分别设置本地播放和发送至远端的音轨。在 K 歌等场景下，主播可以根据需求选择在本地播放一路音轨（如原声），然后发送另一路音轨至远端（如伴奏）以提升听众体验。使用该功能前，需要通过 [`OpenWithMediaSource`](/zh-CN/api-reference/rtc/unreal-blueprint/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 打开媒体文件，并通过 [`FAgoraMediaSource`](/zh-CN/api-reference/rtc/unreal-blueprint/class-mediasource) 中新增的 `enableMultiAudioTrack` 成员来开启音轨控制。 #### 本地截图上传更新 [#本地截图上传更新-9] 为方便接入声网云市场提供的第三方视频审核服务，该版本有以下改动： - [`ECONTENT_INSPECT_TYPE`](/zh-CN/api-reference/rtc/unreal-blueprint/enum-contentinspecttype) 中新增 `CONTENT_INSPECT_IMAGE_MODERATION` 枚举值，代表使用声网云市场视频审核插件对视频截图并上传。 - [`FContentInspectConfig`](/zh-CN/api-reference/rtc/unreal-blueprint/class-contentinspectconfig) 中新增的 `serverConfig` 可选参数用于云市场视频审核相关服务端配置，配置后可同时接入多个云市场审核插件并实现灵活控制插件开关等功能，详情请[联系技术支持](https://ticket.shengwang.cn/)。 此外，该版本还新增了 [`EnableContentInspectEx`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-prenpro/snapshot#api_irtcengineex_enablecontentinspectex) 方法，支持同时对多条视频流截图并上传。 #### 通配 Token [#通配-token-9] 该版本新增通配 Token。生成 Token 时，在用户 ID 不为 0 的情况下，声网支持你将频道名设为通配符，从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下，使用通配 Token 可以避免 Token 的重复配置，有助于提升开发效率，减少你的 Token 服务端的压力。详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 :::warning[注意] 声网 4.x RTC SDK 均支持使用通配 Token。 ::: #### 预加载频道 [#预加载频道-10] 该版本新增 [`PreloadChannel`](/zh-CN/api-reference/rtc/unreal-blueprint/channel#api_irtcengine_preloadchannel) 和 [`PreloadChannelWithUserAccount`](/zh-CN/api-reference/rtc/unreal-blueprint/channel#api_irtcengine_preloadchannelwithuseraccount) 方法，支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的音视频体验。 在同时预加载多个频道时，为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长，因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时，进一步加快切换频道的速度，详见[使用通配 Token](/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token)。 #### 发布多源采集的视频流 (Windows, macOS) [#发布多源采集的视频流-windows-macos-3] 该版本在 [`FChannelMediaOptions`](/zh-CN/api-reference/rtc/unreal-blueprint/class-channelmediaoptions) 中新增下列成员，支持你发布第三个、第四个摄像头和屏幕采集到的视频流： - `publishThirdCameraTrack`：发布第三个摄像头采集的视频。 - `publishFourthCameraTrack`：发布第四个摄像头采集的视频。 - `publishThirdScreenTrack`：发布第三个屏幕采集的视频。 - `publishFourthScreenTrack`：发布第四个屏幕采集的视频。 :::warning[注意] 目前 SDK 支持在同一时间、同一 `RtcConnection` 中发布多路音频流、一路视频流。 ::: ### 改进 [#改进-165] #### 渲染易用性提升 [#渲染易用性提升] 使用 UImage 控件时，可以通过设置 Brush 的属性来控制图像显示的大小。自该版本起，支持启用 **Size To Content** 选项，让 UImage 自动适配远端传入的视频帧大小，此项改进提升了图像渲染的易用性。 #### 跨频道连麦优化 [#跨频道连麦优化-9] 该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个，在调用 [`StartOrUpdateChannelMediaRelay`](/zh-CN/api-reference/rtc/unreal-blueprint/cloud-media-relay/channel-media-relay#api_irtcengine_startorupdatechannelmediarelay) 和 [`StartOrUpdateChannelMediaRelayEx`](/zh-CN/api-reference/rtc/unreal-blueprint/cloud-media-relay/channel-media-relay#api_irtcengineex_startorupdatechannelmediarelayex) 时，你可以指定最多 6 个目标频道。 ### 问题修复 [#问题修复-173] 在 Unreal Engine 5.3 和 5.4 版本中，当你在项目的 `/Source/xxx.Target.cs` 文件添加以下代码以解决 iOS 内存分配问题时，可能会导致 iOS 编译符号缺失。为解决这一问题，该版本在 `UnrealMemory.cpp` 文件中添加了 3 个与标准库相关的函数定义 (`StdMalloc`、`StdRealloc` 和 `StdFree`)，确保在使用标准内存分配器时能够正确处理内存管理需求。 ```csharp if (Target.Platform == UnrealTargetPlatform.IOS) { bOverrideBuildEnvironment = true; GlobalDefinitions.Add("FORCE_ANSI_ALLOCATOR=1"); } ``` ## v4.2.1 [#v421-10] 该版本于 2023 年 11 月 16 日发布，该版本为声网 RTC Unreal SDK 的首个版本。 #### 功能简介 [#功能简介-2] 该 SDK 由声网为使用 Unreal Blueprint 的开发者而设计，旨在为 Unreal Engine 用户提供简单且用户友好的实时互动解决方案。 SDK 提供可视化界面和一系列直观易用的节点，开发者可在 Unreal 项目中通过节点的拖放、连接以及配置，就可轻松实现具备实时互动功能的游戏或 App ，无需深入学习复杂的 C++ 编程知识。 #### 参考文档 [#参考文档-2] 你可以参考以下文档集成 SDK，实现相应的实时音视频功能： - [跑通 API 示例项目](/zh-CN/realtime-media/rtc/get-started/run-demo) - [实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start) - [实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start) - [实现纯语音互动](/zh-CN/realtime-media/rtc/build/audio/audio-quick-start) - [API 参考](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-api-overview) 声网提供了开源的[示例项目](https://github.com/AgoraIO-Extensions/Agora-Unreal-RTC-SDK/tree/main/Agora-Unreal-SDK-Blueprint-Example)，你可以前往下载并体验。 <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="react" /> ## v2.5.1 [#v251] 该版本于 2025 年 12 月 17 日发布。 该版本将 React SDK 中内置的 Web SDK 更新为 4.24.2 版本。相关改动可以查看 [Web SDK 发版说明](/zh-CN/realtime-media/rtc/reference/release-notes/web#v4.24.2)。 ## v2.5.0 [#v250] 该版本于 2025 年 8 月 13 日发布。 该版本将 React SDK 中内置的 Web SDK 更新为 4.24.0 版本。相关改动可以查看 [Web SDK 发版说明](/zh-CN/realtime-media/rtc/reference/release-notes/web#v4.24.0)。 ## v2.4.0 [#v240-1] 该版本于 2025 年 3 月 18 日发布。主要改动点如下： - 为支持[声网对话式 AI 引擎](/zh-CN/ai)作了一些内部改进。 - 将 React SDK 中内置的 Web SDK 更新为 4.23.2 版本。相关改动可以查看 [Web SDK 发版说明](/zh-CN/realtime-media/rtc/reference/release-notes/web)。 - 修复了网络状态发生改变可能意外创建新 Track 的问题。 ## v2.3.0 [#v230] 该版本于 2024 年 8 月 21 日发布。 该版本将 React SDK 中内置的 Web SDK 更新为 4.22.0 版本。相关改动可以查看 [Web SDK 发版说明](/zh-CN/realtime-media/rtc/reference/release-notes/web#v4.22.0)。 ## v2.2.0 [#v220] 该版本于 2024 年 6 月 13 日发布。 此版本对 React SDK 进行了升级，将内置的 Web SDK 更新至 4.21.0 版本。如需了解 Web SDK 4.20.0 到 4.21.0 版本间的变更详情，可以查看 [Web SDK 发版说明](/zh-CN/realtime-media/rtc/reference/release-notes/web)。 ## v2.1.0 [#v210] 该版本于 2023 年 12 月 27 日发布。 该版本将 React SDK 中内置的 Web SDK 更新为 4.20.0 版本。相关改动可以查看 [Web SDK 发版说明](/zh-CN/realtime-media/rtc/reference/release-notes/web#v4.20.0)。 ## v2.0.0 [#v200] 该版本于 2023 年 12 月 7 日发布。 ### 升级必看 [#升级必看-103] #### SDK 优化结构 [#sdk-优化结构] React SDK 基于 Web SDK 4.x 开发。为进一步提升易用性，该版本在 React SDK 中内置了 Web SDK 提供的所有 API，你不需要再单独集成 Web SDK。 升级到该版本后，你需要进行以下修改： - 重新集成 React SDK，以 npm 集成为例： ```shell # 移除已有依赖 npm uninstall agora-rtc-react agora-rtc-sdk-ng # 重新安装依赖 npm install agora-rtc-react ``` - 修改 Web SDK 提供的 `AgoraRTC` 接口类的引入方式，以同时引入 `AgoraRTC` 和 `AgoraRTCProvider` 为例： ```jsx // 该版本之前 import AgoraRTC from "agora-rtc-sdk-ng"; import { AgoraRTCProvider } from "agora-rtc-react"; // highlight-start // 升级到该版本后 import AgoraRTC, { AgoraRTCProvider } from "agora-rtc-react" // highlight-end ``` #### NetworkQuality 更名 [#networkquality-更名] 为避免与 Web SDK 的 API 产生冗余，该版本对 React SDK 的 `NetworkQuality` 接口类进行了以下改动： - `NetworkQuality` 改名为 `NetworkQualityEx` 并且继承 Web SDK 的 `NetworkQuality` 接口类 - `uplink`、`downlink` 属性分别改名为 `uplinkNetworkQuality`、`downlinkNetworkQuality` 如果你使用了 React SDK 的 `NetworkQuality` 接口类，升级到该版本后请修改相关代码。 ### 改进 [#改进-166] 该版本在 `useLocalCameraTrack` 中新增 `cameraVideoTrackConfig` 参数，方便你在创建摄像头视频轨道时进行视频采集的配置，包括采集设备、编码配置等。 ### 问题修复 [#问题修复-174] 该版本修复了 SDK 在 Firefox 的开发者模式下报错 `CAN_NOT_PUBLISH_MULTIPLE_VIDEO_TRACKS` 的问题。 ### API 变更 [#api-变更-84] #### 修改 [#修改-25] - `NetworkQuality` 改为 `NetworkQualityEx` - `uplink` 属性改为 `uplinkNetworkQuality` - `downlink` 属性改为 `downlinkNetworkQuality` - `useLocalCameraTrack` 中新增 `cameraVideoTrackConfig` 参数 ## v2.0.0-beta.0 [#v200-beta0] 该版本于 2023 年 8 月 8 日发布。这是 RTC React SDK 的第一个版本。 该版本提供了用于实时音视频基础功能的组件和 Hook，可以简化 UI 和状态管理。 :::warning[注意] RTC React SDK 目前处于 Public Beta 阶段，某些功能细节可能会在随后的版本中发生改变，以提升用户体验。 ::: <_PlatformProcessedMarker close="true" />