# 发版说明 (/zh-CN/realtime-media/rtc/reference/release-notes/electron) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 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` 节点实现。 #### 新增域名白名单 [#新增域名白名单-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。