文档中心
互动直播 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

发版说明

更新时间 2023/08/21 08:05:20

本文提供声网 RTC SDK for Electron 的发版说明。

声网 SDK for Electron 基于声网 RTC SDK for macOS 和声网 RTC SDK for Windows，使用 Node.js C++ 插件开发。

已知问题

macOS Monterey 12 兼容性

自 3.4.5 版本起，SDK 对 macOS Monterey 12 进行了兼容性适配。3.2.0（含）及 3.4.2（含）之间的 SDK 版本在 macOS Monterey 12 上高概率会发生崩溃。为避免该问题，请务必将 SDK 升级至 3.4.5 或之后版本。

USB 设备驱动问题 (macOS)

在 macOS 上连接 USB 耳麦，可能会出现听不见声音或者声音显示异常等问题，通常为 USB 设备驱动的问题。macOS 对普通的 USB 支持不太友好，建议购买更优质的 USB 耳麦。

Rosetta 转译问题 (macOS)

如果你在 app 中集成的 SDK 版本低于 3.3.1，在搭载 M1 芯片的 Mac 设备上只能使用 Rosetta 转译的方式运行 app，该方式会导致用户频繁进出频道时产生内存泄漏。

如果你希望避免该问题，请升级至 3.3.1 或之后版本，并将 app 适配 x86-64 和 arm64 架构。

3.7.0 版

该版本于 2022 年 5 月 7 日发布。

新增特性

1. 空间音效

该版本新增空间音效功能，用于塑造远端用户声音的方位感和模拟声音在真实世界中的传播过程，实现本地用户听远端用户时的空间音效。

如有需要，请联系 sales@shengwang.cn。

2. 屏幕共享

该版本新增 setScreenCaptureScenario 方法，用于设置屏幕共享场景，如共享文档、视频等。SDK 支持根据你设置的场景调整共享的画质与体验。

3. 本地语音音调

该版本新增 enableLocalVoicePitchCallback 方法和 localVoicePitchInHz 回调，允许 SDK 按设置的时间间隔向 app 报告本地用户的语音音调。

4. 远端首帧出图回调

该版本在 AgoraRtcChannel 类中新增 firstRemoteVideoFrame 回调，以在多频道场景下向本地用户报告远端用户的首帧视频已渲染。你还可以从该回调中获取远端用户 ID、视频宽度 (px)、高度 (px)、首帧出图时间 (ms)。

5. 切换用户角色失败回调

该版本新增 clientRoleChangeFailed 回调，用于报告直播场景下用户切换角色失败的原因和当前的用户角色。

6. 网络连接发生改变的原因

为方便用户了解网络连接发生改变的原因，该版本在 CONNECTION_CHANGED_REASON_TYPE 中新增如下枚举：

  • CONNECTION_CHANGED_SAME_UID_LOGIN(19)：使用相同的 UID 从不同的设备加入同一频道。
  • CONNECTION_CHANGED_TOO_MANY_BROADCASTERS(20)：频道内主播人数已达上限。该枚举仅在开启 128 人功能后报告。

7. 视频增强

继基础美颜后，声网新增支持更多视频增强功能：

  • 视频降噪：该功能可以降低视频噪声，提升视频画质。你可以通过 setVideoDenoiserOptions 方法设置开/关视频降噪和视频降噪效果选项。
  • 暗光增强：该功能可在光线亮度偏低（如背光、阴天、暗场景）和亮度不均匀的环境下自适应调整视频画面的亮度值，恢复或凸显图像的细节信息，提升视频图像的整体视觉效果。你可以通过 setLowLightEnhanceOptions 方法设置开/关暗光增强和暗光增强效果选项。
  • 色彩增强：该功能可智能调节饱和度和对比度等视频特性，提升视频色彩丰富度和色彩还原度，使视频画面更生动。你可以通过 setColorEnhanceOptions 方法设置开/关色彩增强和色彩增强效果选项。
  • 使用上述视频增强功能前，请确保已集成 libagora_video_process_extension.dll 动态库。
  • 视频增强功能对设备性能有一定要求。开启视频增强后，如果设备出现严重发烫等问题，请将视频增强效果选项修改为消耗性能较少的等级或关闭视频增强功能。

8. Wi-Fi 加速

该版本新增支持并默认开启 Wi-Fi 加速功能。当 SDK 发现集成加速插件的 Wi-Fi 路由器后，该功能会正式生效，使路由器合理分配 Wi-Fi 频谱资源，以降低丢包率和时延，从而减少音视频卡顿。

当路由器提供加速服务后，SDK 会周期性触发 wlAccStats 回调，报告 Wi-Fi 加速效果，并在 Wi-Fi 连接质量不佳时触发 wlAccMessage 回调，报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

如果你不需要使用 Wi-Fi 加速功能，可以在加入频道前调用 enableWirelessAccelerate(false) 关闭该功能。

声网提供的 Wi-Fi 加速功能除应用于音视频流，还可以应用于其他第三方业务流，如私有信令、课件、RTMP 协议等。如有需要，请联系 sales@shengwang.cn。

9. 视频截图上传

为满足对视频内容监管的需求，该版本新增 enableContentInspect 方法，支持开启视频截图上传。成功开启视频截图上传后，SDK 会根据你在 ContentInspectConfig 中设置的视频截图上传模块和频率对本地用户发送的视频进行截图、上传。截图完成后，声网服务器会以 HTTPS 请求的形式通知你的服务器，并将所有截图发送至你指定的第三方云存储。

开启视频截图上传前，请确保已开通声网视频截图上传服务并集成相关的动态库。

改进

1. 频道能力提升

自该版本起，单个频道可支持最多 128 位主播同时在线并同时发布音视频流，观众人数无限制，每位主播或观众最多可同时订阅 50 位主播。

如有需要，请联系 sales@shengwang.cn。

2. 虚拟背景

测试结果和用户反馈显示，虚拟背景功能在多种复杂背景环境和多种人物姿态下均提升了实际效果。因此，自该版本起，虚拟背景由 Beta 功能转变为正式功能。

3. 新版 AI 降噪

自该版本起，声网在原版 AI 降噪功能的基础上增加了新版 AI 降噪功能，拥有更好的降噪效果。如果你希望体验新版 AI 降噪，请联系 sales@shengwang.cn。

4. playEffect 优化

为避免阻塞，该版本优化了 playEffect 的内部实现逻辑，以减少播放音效文件时的卡顿。

5. 音频体验优化

该版本改善了网络突发抖动和高丢包情况下的音频卡顿问题。

6. 传输升级

该版本升级了传输协议和算法，增强了弱网对抗能力。同时，优化了多人视频场景的可伸缩视频编码能力，提升了视频体验。

7. 云代理

为丰富云代理的适用场景，该版本对云代理类型（CLOUD_PROXY_TYPE）进行了如下改进：

  • NONE_PROXY(0) 由不使用云代理变更为自动模式。在该模式下，SDK 优先连接 SD-RTN™，如果连接失败，自动切换到 TLS 443。自 v3.7.0 起，SDK 默认开启该模式。
  • 新增 TCP_PROXY(2)，表示 TCP（加密）代理模式。在该模式下，SDK 始终通过 TLS 443 传输数据。

同时，该版本新增 proxyConnected 回调，报告 SDK 连接代理的状态。例如，当用户调用 setCloudProxy 设置代理并成功加入频道后，SDK 会触发该回调，报告用户 ID，连接的代理类型和从调用 joinChannel 到 SDK 触发该回调的经过的时间。

8. 音频设备检测

为支持在频道内进行音频设备检测，该版本对音频检测相关方法和回调作如下改进：

  • 在 AgoraRtcChannel 类新增 audioDeviceTestVolumeIndication 回调，专门用于报告被检测音频设备的音量信息。

  • startAudioDeviceLoopbackTest 方法由只能在加入频道前调用改为在加入频道前后均可调用，并触发如下回调：

    • 加入频道前调用，SDK 触发 audioVolumeIndication 和 audioDeviceTestVolumeIndication 回调。两种回调报告的音量信息相同。如果你将 SDK 升级到 3.7.0 或之后版本，建议你使用 audioDeviceTestVolumeIndication 回调。
    • 加入频道后调用，SDK 触发 audioDeviceTestVolumeIndication 回调。
加入频道后调用 startAudioDeviceLoopbackTest 方法，只能检测当前正在使用的音频设备。

9. 音频录制

该版本扩展了 startAudioRecording 的功能，支持设置录制双声道和更高的音质：

  • 通过在 AudioRecordingConfiguration 中新增 recordingChannel，允许用户设置录制的音频声道为单声道或双声道。因为实际录制的音频声道与采集的音频声道有关，集成方案也会影响最终录制的音频声道，所以如需通过 startAudioRecording 录制立体声，请联系技术支持协助。
  • 通过在 AudioRecordingConfiguration.recordingQuality 中新增 AUDIO_RECORDING_QUALITY_ULTRA_HIGH(3)，允许用户设置录制的音质为超高音质。超高音质是 recordingQuality 中提供的最高音质。当采样率为 32000 Hz，以超高音质录制 10 分钟的 AAC 音频文件时，文件大小约为 7.5 M。

10. 播放音乐文件优化

该版本优化了调用 startAudioMixing 播放音频文件的体验，具体如下：

如果你希望体验这些优化，请确保已集成 libagora-full-audio-format-extension.dll 动态库。考虑到该库的体积较大，如果你对 app 体积有限制且不需要体验这些优化，你可以在集成 SDK 时自行删除该动态库。详见减少 App 体积。

问题修复

该版本修复了如下问题：

  • 使用 Push 方式自定义视频源时，偶现用户画面的分辨率持续变化。
  • 本地用户处于特定的混响环境下，远端用户可能听本地用户有回声。

API 变更

新增

  • setScreenCaptureScenario
  • enableLocalVoicePitchCallback
  • localVoicePitchInHz
  • AgoraRtcChannel 类中新增 firstRemoteVideoFrame
  • clientRoleChangeFailed
  • CONNECTION_CHANGED_REASON_TYPE 中新增 CONNECTION_CHANGED_SAME_UID_LOGIN(19) 和 CONNECTION_CHANGED_TOO_MANY_BROADCASTERS(20)
  • setVideoDenoiserOptions
  • setLowLightEnhanceOptions
  • setColorEnhanceOptions
  • enableWirelessAccelerate
  • wlAccMessage
  • wlAccStats
  • enableContentInspect
  • contentInspectResult
  • AgoraRtcChannel 中audioDeviceTestVolumeIndication
  • AudioRecordingConfiguration 中新增 recordingChannel
  • AudioRecordingConfiguration.recordingQuality 中新增 AUDIO_RECORDING_QUALITY_ULTRA_HIGH(3)
  • proxyConnected
  • CLOUD_PROXY_TYPE 中新增 TCP_PROXY(2)

修改

  • startAudioDeviceLoopbackTest 的调用时序限制
  • CLOUD_PROXY_TYPE 中的 NONE_PROXY(0) 的行为

废弃

LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_NOT_SUPPORTED(20)

3.6.1.4 版

该版本于 2022 年 3 月 29 日发布。

升级必看

1. 旁路推流

为降低旁路推流集成难度，该版本优化了推流 API 设计，并改善了推流客户端和服务端内部对网络问题的处理机制。你可以通过该版本新增的如下方法体验优化后的旁路推流功能：

  • startRtmpStreamWithoutTranscoding: 开始非转码推流。与旧推流方法 addPublishStreamUrl(false) 作用相同。
  • startRtmpStreamWithTranscoding: 开始 CDN 直播推流并设置转码属性。与依次调用旧推流方法 setLiveTranscoding、addPublishStreamUrl(true) 的作用相同。
  • updateRtmpTranscoding: 更新转码属性。与非首次调用旧推流方法 setLiveTranscoding 的作用相同。
  • stopRtmpStream: 结束 CDN 直播推流。与旧推流方法 removePublishStreamUrl 作用相同。
该版本废弃 addPublishStreamUrl、setLiveTranscoding、removePublishStreamUrl 这三个旧推流方法，声网推荐你使用新的推流方法，并参考旁路推流更新你的业务代码逻辑。

同时，自该版本起，不管你使用新推流方法还是旧推流方法，你都可以体验如下改进：

  • 推流状态、错误、事件透明：
    • 在 RtmpStreamingStateChanged 回调的 state 参数中新增状态 5：SDK 正在与声网推流服务器和 CDN 服务器断开连接。当你调用 remove 或 stop 方法正常结束推流时，SDK 会依次报告推流状态为 DISCONNECTING、IDLE。
    • 在 RtmpStreamingStateChanged 回调的 code 参数中新增如下错误码：
      • 11：用户角色不是主播，该用户无法使用推流功能。请检查你的应用代码逻辑。
      • 13：非转码推流情况下，调用了 update 或 setLiveTranscoding 方法更新转码属性。请检查你的应用代码逻辑。
      • 14：主播的网络出错。
      • 15：你的 App ID 没有使用声网推流服务的权限。请参考前提条件开启推流服务。
    • 在 RTMP_STREAMING_EVENT 事件码中新增如下：
      • RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT(3)：功能不支持。
      • RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN(4)：预留参数。
        为保障推流质量，请务必根据推流状态码、错误码、事件码对业务逻辑进行处理。
  • 转码推流时，设置每张水印、背景图片的图层编号和透明度：通过在 RtcImage 结构体中新增 zOrder 和 alpha 实现。
  • 转码推流时，使用 HE-AAC v2 音频编解码器：通过在 AUDIO_CODEC_PROFILE_TYPE 中新增 AUDIO_CODEC_PROFILE_HE_AAC_V2(2) 实现。

2. 跟随系统默认音频设备

为方便开发者灵活控制音频设备的切换，该版本新增如下方法：

  • getDefaultAudioPlaybackDevice：获取系统默认的音频播放设备。
  • getDefaultAudioRecordingDevice：获取系统默认的音频采集设备。
  • followSystemPlaybackDevice：设置 SDK 使用的音频播放设备跟随系统默认的音频播放设备。
  • followSystemRecordingDevice：设置 SDK 使用的音频采集设备跟随系统默认的音频采集设备。

在 Windows 平台，SDK 初始化后默认使用系统默认的音频设备来播放和采集音频。该版本优化了系统默认音频设备发生变化时，SDK 的默认处理逻辑，具体如下：

  • v3.6.1.4 之前，SDK 仅在以下情况跟随系统默认设备变化：
    • 用户插入音频设备，导致系统默认的音频设备切换为新插入的音频设备。
    • 用户拔出或禁用系统默认的音频设备，且该设备为 SDK 当前使用的音频设备。
  • v3.6.1.4 及之后，SDK 始终跟随系统默认设备变化。如果无需跟随，你可以调用 followSystemPlaybackDevice(false) 和 followSystemRecordingDevice(false)。

3. 加入频道失败时返回的错误码变更

为准确报告加入频道失败的原因，自该版本起，在如下情况，SDK 返回的错误码由 -5 更改为 -17：

  • 当已经加入 IRtcEngine 频道的用户使用有效的频道名再次调用 IRtcEngine 类中的加入频道方法。
  • 当已经加入某个 IChannel 频道的用户再次调用该 IChannel 对象的加入频道方法。

4. 屏幕共享相关变更

自该版本起，屏幕共享相关的方法有如下变更：

  • getScreenWindowsInfo 方法新增参数 callback（入参为 WindowInfo 数组的回调）。
  • getScreenDisplaysInfo 方法新增参数 callback（入参为 DisplayInfo 数组的回调）。
  • 废弃 getRealScreenDisplayInfo 方法，使用 getScreenDisplaysInfo 作为替代。

新增特性

1. 视频截图

该版本新增 takeSnapshot 方法，支持对指定用户的视频进行截图，生成 JPG 格式图片，并保存至指定的路径。成功调用该方法后，SDK 触发 snapshotTaken 回调报告截图是否成功和获取截图的详情。

2. 音视频通话回路测试

为方便用户自行检查本地音频设备、视频设备、网络状态能否保障正常发送、接收音视频流，该版本新增 startEchoTestWithConfig 方法。你可以在加入频道前调用该方法，以测试用户的音视频设备和网络回路是否正常。

相比 startEchoTestWithInterval，startEchoTestWithConfig支持测试视频设备，可保障测试的安全性，不支持设置返回测试结果的时间间隔。

3. 背景虚化

为丰富虚拟背景的效果，该版本新增支持用户调用 enableVirtualBackground 开启虚拟背景时设置背景虚化。你需要将自定义的背景图类型设为 BACKGROUND_BLUR，并根据用户希望的背景虚化程度设置 blur_degree。

4. 暂停/恢复跨频道媒体流转发

为方便跨频道连麦中的主播快速暂停或恢复媒体流转发，该版本新增如下方法和和状态码：

  • pauseAllChannelMediaRelay：暂停向所有目标频道转发媒体流。
  • resumeAllChannelMediaRelay：恢复向所有目标频道转发媒体流。
  • RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS(12)：成功暂停向目标频道转发媒体流。
  • RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED(13)：暂停向目标频道转发媒体流失败。
  • RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS(14)：成功恢复向目标频道转发媒体流。
  • RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED(15)：恢复向目标频道转发媒体流失败。

成功调用 pauseAllChannelMediaRelay 或 resumeAllChannelMediaRelay 方法后，SDK 会触发 channelMediaRelayEvent 回调，并在回调中报告是否成功暂停或恢复媒体流转发。

5. 音乐文件高级设置

为设置音乐文件的播放速度、音轨和声道模式，该版本新增如下方法：

  • setAudioMixingPlaybackSpeed: 设置当前音乐文件的播放速度。声网推荐取值范围为 [50,400]，100 表示原始速度。
  • getAudioTrackCount: 获取当前音乐文件的音轨数量。
  • selectAudioTrack: 指定当前音乐文件的播放音轨。指定音轨的索引取值范围为 [0, getAudioTrackCount()]。
  • setAudioMixingDualMonoMode: 设置当前音乐文件的声道模式为原始模式、左声道模式、右声道模式或混合模式。

6. 获取音频文件信息

为获取任意音频文件的信息，该版本删除 getAudioMixingFileDuration 并新增 getAudioFileInfo 替代。加入频道后，你可以调用 getAudioFileInfo 并通过 requestAudioFileInfo 回调获取指定音频文件的时长等信息。

改进

1. 基础美颜

该版本更新了声网基础美颜算法，提升了你通过 setBeautyEffectOptions 方法开启的基础美颜效果。为平衡美颜效果，该版本将 lighteningLevel（美白程度）的默认值从 0.7 改为 0.6，并在 BeautyOptions 结构体中新增 sharpnessLevel 支持设置锐化程度。

自该版本起，调用 setBeautyEffectOptions 前，请确保已集成 libagora_video_process_extension.dll 动态库。否则，你无法体验新的声网基础美颜算法带来的基础美颜效果和锐度调节功能，只能体验原来的声网基础美颜算法带来的基础美颜效果。

2. 首帧出图

该版本缩短了弱网环境下首帧出图时间，提升用户视频体验。

3. 屏幕共享

该版本新增 getScreenCaptureSources 方法供你获取所有可用于共享的屏幕和窗口的对象列表。用户可通过列表中的缩略图直观选择共享某个显示器的屏幕或共享某个窗口。

4. 本地视频出错

为方便问题排查，该版本在 LOCAL_VIDEO_STREAM_ERROR 中新增如下错误码：

  • LOCAL_VIDEO_STREAM_ERROR_DEVICE_INVALID_ID(10): SDK 无法在视频设备列表中找到该视频设备。请检查视频设备 ID 是否有效。
  • LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_OCCLUDED(13): 待共享的窗口被其他窗口遮挡住，被遮挡住的部分在共享时会被 SDK 涂黑。
  • LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_NOT_SUPPORTED(20): SDK 不支持共享该类型的窗口。

5. 音频设备出错

该版本在 LOCAL_AUDIO_STREAM_ERROR 中新增如下错误码：

  • LOCAL_AUDIO_STREAM_ERROR_RECORD_INVALID_ID(9): 报告音频采集设备的 ID 无效。
  • LOCAL_AUDIO_STREAM_ERROR_PLAYOUT_INVALID_ID(10): 报告音频播放设备的 ID 无效。

6. 5G 移动网络的识别和质量测试

该版本新增对 5G 移动网络的识别和质量测试，具体如下：

  • 在 NETWORK_TYPE 中新增 NETWORK_TYPE_MOBILE_5G(6) 枚举，当本地网络切换为 5G 时，SDK 触发 onNetworkTypeChanged 回调报告该网络连接类型。
  • 支持调用 enableLastmileTest 或 startLastmileProbeTest 测试 5G 网络连接质量。

7. 其他改进

该版本还进行了如下改进：

  • 通过优化 FEC（Forward Error Correction）编解码，小幅降低视频场景下的 CPU 占用率。
  • 通过优化拥塞控制算法，提升弱网环境下视频清晰度和流畅度。
  • 持续优化虚拟背景的人像边缘效果。
  • 在 CPU 占用率高的情况下，提升了使用声卡采集音频时的音频体验。
  • 支持 S/PDIF（Sony/Philips Digital Interface）的音频播放设备。
  • 提升了开启 AI 降噪后使用部分蓝牙耳机时的音频体验。
  • 对屏幕共享进行了画质、延迟、性能优化。
  • 窗口共享功能适配共享更多类型的应用窗口。
  • 使用 Mac 设备的远端用户因调用 leaveChannel 或网络中断等原因而离开频道后，本地用户看到远端画面停留在最后一帧，而不再是远端视图直接消失。

问题修复

该版本修复了如下问题：

  • Web 用户恢复发送音频流后，3.6.0 或之后版本的 Native 用户可能听不到 Web 用户声音。
  • 对带端口号的旁路推流地址解析异常而导致的推流失败。
  • 本地用户共享某些应用窗口后，将其他应用窗口前置且覆盖当前共享窗口区域，远端用户看到共享窗口中存在黑色遮挡。
  • 在搭载 Windows 7 系统的特定机型上，出现崩溃。
  • 调用 updateScreenCaptureParameters 更新屏幕共享参数配置时，windowFocus 不生效。
  • 开启媒体流加密后，偶现远端用户接收到的视频卡顿。
  • 本地用户共享指定窗口时，本地用户发现该窗口被隐藏，远端用户看不到共享的窗口。
  • 共享 Foxmail 窗口失败。
  • 在部分设备上本地用户调用 enableLoopbackRecording 开启声卡采集，远端用户听到音频被播放两次。
  • 使用特定 NVIDIA 和 Intel 组合的双显卡，屏幕共享黑屏。
  • 用户在高丢包的弱网环境下加入频道，视频码率无法爬升。
  • 特定弱网条件下，视频码率断崖式下降所导致的视频清晰度和流畅度明显下降问题。
  • 在某些 Android 机型上调用 startAudioMixing 时，远端用户听到的人声和伴奏有轻微的不同步。
  • 部分设备上 Windows 版本识别错误问题。
  • GAME_STREAMING 场景下，偶现因音乐检测不准确导致的回声或噪声。
  • 远端用户在几秒内依次调用 enableLocalVideo(false)、enableLocalVideo(true) 关、开本地视频采集或依次调用 muteLocalVideoStream(true)、muteLocalVideoStream(false) 停止、恢复发送本地视频后，本地用户看远端用户偶现短暂黑屏。
  • 用户共享 QQ 浏览器窗口并切换浏览器 Tab 后，窗口共享停止。
  • 本地用户调用 muteAllRemoteAudioStreams，收到 remoteAudioStateChanged(REMOTE_AUDIO_REASON_LOCAL_MUTED) 回调 15 秒后，错误地收到了 remoteAudioStateChanged(REMOTE_AUDIO_REASON_REMOTE_MUTED) 回调。
  • 插拔音频设备时，SDK 重复触发 audioDeviceStateChanged 回调。
  • 自 3.4.5 版本起，连续多次调用 joinChannel 方法时，返回值不准确。
  • 特定场景下，主播使用特定低端机型时，偶现观众看主播视频卡顿。
  • 特定场景下，发送端使用特定的小米和红米机型时，偶现接收端看到视频画面出现马赛克方格。
  • 发送端使用特定的安卓模拟器时，本地视频或接收端看到的视频画面异常。
  • 使用光纤音箱时出现回声。
  • 在频道内调用 enableLocalAudio(false) 后，SDK 额外触发 localAudioStateChanged 回调报告 LOCAL_AUDIO_STREAM_ERROR_FAILURE(1)。
  • 特定场景下，在特定设备上初始化 AgoraRtcEngine 会出现崩溃。
  • 当系统版本为 10.14.6 或更低，调用 getScreenCaptureSources 获取当前所有可共享的窗口时，窗口异常显示为白屏。（macOS）
  • 本地用户在 Windows 设备上使用视频自渲染后，偶现本地用户看远端用户视频模糊。
  • 调用 enableVirtualBackground 开启虚拟背景并通过 source 设置一张 JPG 图片为背景后，关闭或更新虚拟背景时，此前设置的 JPG 图片均无法删除。
  • 当接收端使用 MediaIO 方式的视频自渲染时，如果发送端发送的视频分辨率改变，接收端可能出现崩溃。
  • 特定网络场景下，用户看到视频持续模糊。
  • 本地用户通过原始视频数据进行自渲染时，渲染出的远端视频存在色差。（macOS）
  • 在低于 10.11 的系统上，应用崩溃。（macOS）
  • 用户在频道内设置禁止 SDK 使用麦克风的权限后，SDK 异常触发 localAudioStateChanged(3,9) 回调，却未触发 localAudioStateChanged(3,2)。
  • 本地用户在配置双显卡的设备上启用屏幕共享，当本地用户屏蔽指定窗口后，偶现本地用户及远端用户看屏蔽窗口为黑屏。(Windows)
  • 使用集成了 SDK 的 app 进行窗口共享，当共享浏览器窗口时，浏览器全屏后切回 app 窗口后偶现本地用户及远端用户看共享窗口画面卡住。(Windows)
  • 本地用户使用显示器配置高于 Retina 5K 的 iMac 设备进行屏幕共享时，偶现远端用户看本地用户的共享画面出现黑屏。(macOS）
  • 屏幕共享时如果启用屏蔽窗口功能，屏幕共享可能失败。（Windows）

API 变更

新增

修改

  • 将 lighteningLevel 的默认值从 0.7 改为 0.6
  • getScreenWindowsInfo
  • getScreenDisplaysInfo

删除

  • getAudioMixingFileDuration
  • getRealScreenDisplayInfo

3.5.0.3 版

该版本于 2021 年 9 月 14 日发布。

改进

1. 视频画质

该版本对采集和接收的视频画质进行了如下改进：

  • 通过对色彩范围的适配，提升采集和接收的视频对比度，以改善画面泛白问题。
  • 通过对色彩空间的适配，提升采集和接收的视频色彩丰富度，进一步还原视频色彩。

2. 虚拟背景（beta）

该版本优化了虚拟背景的人像边缘效果。

3. 降噪

在开启 AGC 的场景下，该版本缩短了降噪收敛的时间，从而降低噪声忽大忽小的波动。

问题修复

该版本修复了如下问题：

  • 特定场景下调用 setupLocalVideo 或 setupRemoteVideo 初始化本地或远端视图时出现的黑屏问题。例如：
    • 先调用 setupLocalVideo(null) 或 setupRemoteVideo(null) 关闭本地或远端视图，再调用 setupLocalVideo 或 setupRemoteVideo 初始化本地或远端视图。
    • 在 remoteVideoStateChanged 回调中调用 setupRemoteVideo 初始化远端视图。
  • 远端用户调用 enableLoopbackRecording 后，偶现本地用户听到自己的回声。
  • 调用 muteLocalAudioStream(true) 停止发布本地音频后，用户第一次加入频道可以听到远端用户，但退出频道后再次加入频道偶现无法听到远端用户。
  • 本地网络环境较差时，SDK 报告的远端用户的下行网络质量 （rxquality）不准确。
  • rtcStats 回调报告的 memoryTotalUsageRatio 的值不准确。
  • 特定音频应用场景下，用户先关闭扬声器播放，再加入频道，扬声器被自动开启。

3.4.6 版

该版本于 2021 年 7 月 23 日发布。

改进

该版本提升了 SDK 的稳定性。

问题修复

该版本修复了 macOS 端的如下问题：

  • 无法监听摄像头的热插拔。
  • 在 M1 Mac 上，通过 My Mac (Designed for iPad) 方式在 Xcode 12 上运行 app 失败。
  • 连接 UltraStudio Recorder 3G 采集设备后，无法通过 UltraStudio Recorder 3G 采集音频。
  • Objective-C 头文件缺失 nonnull、 _Nullable 修饰符导致运行项目时出现警告。

3.4.5 版

该版本于 2021 年 7 月 1 日发布。

升级必看

1. AES-GCM 加密模式升级

为进一步提升实时音视频传输过程的安全性，该版本进行如下优化：

  • 在 ENCRYPTION_MODE 中新增 AES_128_GCM2 和 AES_256_GCM2 加密模式。新的 GCM 加密模式使用了安全性更高的密钥派生函数，支持设置密钥和盐。
  • 在 EncryptionConfig 中新增 encryptionKdfSalt 成员，用于为 AES_128_GCM2 和 AES_256_GCM2 加密模式设置盐。

此外，该版本将默认的加密模式由 AES_128_XTS 修改为 AES_128_GCM2。如果你原来使用了默认的加密模式，将 SDK 升级到 v3.4.5 之后，请务必调用 enableEncryption 并将 ENCRYPTION_MODE 设置为 AES_128_XTS。

开启加密功能后，同一频道内的所有用户都必须使用相同的加密模式和密钥，包括服务端用户（例如声网录制服务）。

2. 媒体流发布行为变更

为方便用户灵活控制多个频道中的发布状态，该版本对 AgoraRtcChannel 类进行如下优化：

  • 废弃 publish 和 unpublish，并新增 muteLocalAudioStream 和 muteLocalVideoStream 作为替代。你可以分别设置音频流和视频流的发布状态。
  • 在 ChannelMediaOptions 中新增 publishLocalAudio 和 publishLocalVideo 成员。你可以在加入频道时设置音视频流的发布状态。
  • 调用 setClientRole(1) 后，本地用户默认发布音视频流。
如下 API 功能相同，所以搭配使用时，后调用的 API 生效。
  • publishLocalAudio = false 和 muteLocalAudioStream(true) 的功能相同。
  • publishLocalVideo = false 和 muteLocalVideoStream(true) 的功能相同。

上述优化也带来了 AgoraRtcEngine 类的部分行为变更：

  • AgoraRtcEngine 类的 muteLocalAudioStream 和 muteLocalVideoStream 对通过 AgoraRtcChannel 类创建的频道不生效，你需要改用 AgoraRtcChannel 类的 muteLocalAudioStream 和 muteLocalVideoStream。
  • 通过带 options 参数的 joinChannel 加入频道时，你可以设置音视频流的发布状态。
  • 如果使用带 options 参数的 joinChannel 加入频道，muteLocalAudioStream 或 muteLocalVideoStream 只有在加入频道后调用才生效。

如果你将 SDK 升级到 v3.4.5 或之后版本，为保证你的业务功能不受影响，声网推荐你修改 muteLocalAudioStream、muteLocalVideoStream、publish 及 unpublish 的实现。

更多介绍见设置发布状态。

新增特性

虚拟背景（beta）

为满足用户对自定义虚拟背景的需求，该版本新增 enableVirtualBackground 方法，支持你开启虚拟背景，将用户的背景设为纯色或 PNG、JPG 格式的图片。同时，你可以通过 virtualBackgroundSourceEnabled 回调了解虚拟背景是否成功开启和相应的出错原因。

使用虚拟背景前，请确保已集成相关的动态库，且设备性能和用户场景符合要求。详见 enableVirtualBackground 文档。

改进

1. 性能优化

声网对该版本 SDK 进行内部线程优化，低端机上 CPU 占用率降低了约 20%。

2. 旁路推流

为向用户透明更多的旁路推流错误和事件，该版本新增如下：

  • 在 rtmpStreamingStateChanged 中新增错误码 100，报告推流已正常结束。当你调用 removePublishStreamUrl 结束推流时，SDK 会返回该错误码和状态码 0 (推流未开始或已结束)。
  • 在 RTMP_STREAMING_EVENT 中新增事件码 RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE (2)，报告该推流 URL 已用于推流。如果你想开始新的推流，请使用新的推流 URL。

3. 媒体设备状态回调

为更准确地报告媒体设备的状态，该版本优化了 audioDeviceStateChanged 和 videoDeviceStateChanged 回调中代表设备状态的值：

  • macOS：
    • 修改 0 的含义，由“已添加”改为“设备就绪”。
    • 报告设备被拔出的值由 1 修改为 8。
  • Windows：
    • 新增 0：报告设备就绪。
    • 修改 1 的含义，由“设备就绪”改为“设备正在使用”。

4. 音乐文件状态

在 pauseAudioMixing 后调用 startAudioMixing 时，该版本在报告 audioMixingStateChanged(710, 720) 状态之前新增了 audioMixingStateChanged(713, 724) 状态，提示已停止播放音乐文件。

问题修复

该版本修复了如下问题：

  • 在弱网环境下，调用 startAudioMixing 播放在线音乐文件时，偶现 SDK 响应时间过长而引起卡顿。
  • 音频场景为 5（游戏开黑） 时，本地用户通过系统播放器播放视频、开启屏幕共享与声卡采集后，远端用户听到播放的视频声音有杂音。
  • 弱网环境下，偶现用户无法切换角色。

API 变更

新增

修改

废弃

  • AgoraRtcChannel 类的 publish 和 unpublish

3.4.2 版

该版本于 2021 年 6 月 1 日发布。

升级必看

集成变更

  1. WGC 库 (Windows)

该版本新增与窗口共享相关的 libagora-wgc.dll 动态库。如果你将 SDK 升级到 v3.4.2 或更高版本，请务必在集成 SDK 时将该库拷贝至 agora_rtc_sdk.dll 所在文件夹中。

  1. 插件列表

为减少集成 SDK 后的 app 体积，该版本将部分功能以插件列表（命名以 Extension 为后缀）的形式发布。如果你不需要使用相关插件功能，你可以直接删除对应的插件并重新编译项目。

行为变更

  1. 音乐文件播放状态

为监听音乐文件播放状态改变的原因，该版本对 audioMixingStateChanged 回调进行如下修改：

  • 将 err 参数修改为 reason 参数。
  • 修改 state 的部分逻辑。例如，循环播放音乐时，播放完成或开始播放都会触发 710 状态。

如果你将 SDK 升级到 v3.4.2 或更高版本，为保证你的业务功能不受影响，声网推荐你修改 audioMixingStateChanged 的实现。

  1. 调节麦克风采集信号音量

自该版本起，adjustRecordingSignalVolume 仅调节麦克风采集信号音量。如需调节声卡采集信号音量，请改用 adjustLoopbackRecordingSignalVolume。

新增特性

1. 调节声卡采集信号音量

该版本新增 adjustLoopbackRecordingSignalVolume，你可以在 enableLoopbackRecording 后调用该方法调节声卡采集的信号音量。

2. 音效文件播放进度

为控制音效文件的播放进度，该版本新增如下方法和参数：

  • setEffectPosition: 在播放音效文件后，设置音效文件的播放位置。
  • getEffectDuration: 获取本地音效文件的总时长。
  • getEffectCurrentPosition: 获取音效文件的播放进度。
  • playEffect 中新增可选参数 startPos：支持在播放音效文件时设置播放位置。

改进

1. 视频编码

声网 SDK 允许你通过 degradationPreference 设置带宽受限时本地视频编码降级偏好，如降低视频帧率保障视频质量，降低视频质量保障视频帧率。
自该版本起，degradationPreference 新增支持设为 MAINTAIN_BALANCED，弱网下会降低视频帧率和视频质量，以在流畅性和视频质量之间取得平衡，适用于流畅性和画质均优先的场景，如一对一通话、一对一教学、多人会议。

2. 窗口共享

该版本对窗口共享进行如下优化：

  • 在 Windows 10 1809 及之后版本的系统上，startScreenCaptureByWindow 支持共享大部分 UWP 应用窗口和采用 DirectX 渲染的窗口。此时，共享的窗口有黄色描边，且 captureMouseCursor(false) 不生效。
  • 在 Windows 10 1809 之前版本的系统上，通过 startScreenCaptureByWindow 共享指定窗口画面时，被其他窗口遮挡的区域被涂黑。

3. 音乐文件播放进度

为方便控制音乐文件的播放进度，该版本进行如下优化：

  • startAudioMixing 新增可选参数 startPos，支持在播放音乐文件时设置播放位置。
  • 废弃 getAudioMixingDuration 并新增 getAudioMixingFileDuration 方法替代。新方法支持通过 filePath 参数在播放本地音乐文件前获取该音乐文件总时长。

4. 客户端录音

为在录音时设置录音内容，该版本废弃 startAudioRecording 并新增 startAudioRecordingWithConfig 方法替代。新方法支持通过 config 参数设置录音音质、内容、采样率及录音文件的存储路径。

该版本还新增了错误码 -160。如果你在当前录音结束前再次调用 startAudioRecordingWithConfig，SDK 会报告该错误码。

5. 媒体设备出错

为方便用户了解本地音视频出错的原因，该版本进行如下优化：

  • 在 LOCAL_VIDEO_STREAM_ERROR 中新增错误码 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(8)，报告无法找到本地视频采集设备。

  • 对 Windows 平台，在 LOCAL_AUDIO_STREAM_ERROR 中新增如下错误码：

    • LOCAL_AUDIO_STREAM_ERROR_NO_RECORDING_DEVICE(6): 报告无法找到本地音频采集设备。
    • LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE(7): 报告无法找到本地音频播放设备。

问题修复

该版本修复了如下问题：

  • 在特定的基础变声场景下，出现崩溃。
  • 极端弱网情况下，Electron 用户看 Web 主播花屏。
  • 调用 enableSoundPositionIndication(true) 后 groupAudioVolumeIndication 回调的音量信息不准确。
  • 集成 libagora_ai_denoise_extension.dll 后偶现崩溃。(Windows)
  • 在 Windows 10 特定机型上共享文件资源管理器窗口时，远端看到的窗口标题栏颜色异常。(Windows)
  • 特定场景下偶现崩溃。(macOS)

API 变更

新增

修改

  • audioMixingStateChanged
  • playEffect
  • startAudioMixing

废弃

  • getAudioMixingDuration
  • startAudioRecording

3.3.2 版

该版本于 2021 年 4 月 15 日发布，修复了如下问题：

  • Mac 上使用神奇效果最小化共享的窗口时，远端用户看到扭曲的画面。
  • 特定场景下，远端用户长时间无声时，本地用户听远端用户有杂音。

3.3.1 版

该版本于 2021 年 3 月 12 日发布。

升级必看

1. 集成变更

该版本新增如下库。

开发平台 声网基础计算库 AI 降噪库（可裁剪）
macOS AgoraCore.framework AgoraAIDenoiseExtension.framework
Windows libagora-core.dll libagora_ai_denoise_extension.dll

2. 行为变更

该版本废弃了 setDefaultMuteAllRemoteAudioStreams 和 setDefaultMuteAllRemoteVideoStreams，并修改了 mute 相关方法的如下行为：

  • mute 相关方法需要在加入频道或切换频道后调用，否则会不生效。
  • mute 相关方法都能独立控制用户的订阅状态。一起调用 muteAll 为前缀的方法和 muteRemote 为前缀的方法时，后调用的方法会生效。
  • muteAll 为前缀的方法设置是否订阅所有音频或视频流，包含调用时刻之后加入频道的用户的音频或视频流，即 muteAll 为前缀的方法包含了 setDefaultMute 为前缀的方法的功能。声网不推荐一起调用 muteAll和 setDefaultMute 为前缀的方法，否则设置可能会不生效。

更多介绍见设置订阅状态。

新增特性

1. 原生支持 M1 芯片

该版本新增对 M1 芯片的原生支持，即同时支持 x86-64 和 arm64 架构。自 v3.3.1 起，集成了 SDK 的 app 可以直接在搭载 M1 芯片的 Mac 设备上运行，无需通过 Rosetta 转译。

2. 频道媒体选项

为方便开发者更灵活地控制媒体流订阅，该版本在 joinChannel 和 switchChannel 方法中新增 options 参数，支持设置用户加入频道和切换频道时是否订阅频道内所有的远端音频流或视频流。

3. 云代理

为提升声网云代理的易用性，该版本新增 setCloudProxy 方法设置云代理并允许你选择连接 UDP 协议的云代理。详见云代理。

4. AI 降噪

为在传统降噪模式的基础上消除非平稳噪声，该版本新增 enableDeepLearningDenoise，用于开启 AI 降噪模式。

开启 AI 降噪前，请将 AI 降噪库集成到你的项目文件中。

5. 歌唱美声

在歌唱场景中，为美化歌声并添加混响效果，该版本新增 setVoiceBeautifierParameters，并在 VOICE_BEAUTIFIER_PRESET 中添加 SINGING_BEAUTIFIER 枚举值。

你可以调用 setVoiceBeautifierPreset(SINGING_BEAUTIFIER) 美化男声并添加歌声在小房间的混响效果。如需更多设置，你可以调用 setVoiceBeautifierParameters(SINGING_BEAUTIFIER, param1, param2) 美化男声或女声，并添加歌声在小房间、大房间或大厅的混响效果。

6. 基础变声

该版本新增 setVoiceConversionPreset 方法改变用户的声音。你可以把男声变得低沉、稳重，把女声变得甜美、中性。

7. 设置日志文件

为保证日志内容的完整性，该版本在 initialize 方法中新增 logConfig 参数，在你初始化 AgoraRtcEngine 时可用于设置声网 SDK 输出的日志文件。

自该版本起，声网不推荐使用 setLogFile、setLogFileSize 和 setLogFilter 方法设置日志文件。

8. 采集画质

为更好地控制摄像头采集的画质，该版本新增支持自定义采集分辨率并监听采集异常：

  • 自定义采集分辨率：调用 setCameraCapturerConfiguration 方法，将采集偏好设为 CAPTURER_OUTPUT_PREFERENCE_MANUAL(3) 并设置采集视频的宽高。
  • 监听采集异常：
    • 采集的画质亮度异常：通过 localVideoStateChanged 回调的 captureBrightnessLevel 监听。
    • 摄像头无法输出采集视频：通过 localVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)回调监听。
    • 摄像头重复输出采集视频：通过 localVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)回调监听。

9. 创建数据流

为了支持歌词同步、课件同步等场景，该版本废弃了原有的 createDataStream 方法，并使用新的 createDataStreamWithConfig 方法替代，用于创建数据流，并设置数据流是否与发布到声网频道内的音频流同步以及接收到的数据是否有序。

改进

1. AES-GCM 加密模式

在安全要求高的场景中，为保证数据的保密性、完整性和真实性，提高数据加密的计算效率，该版本在 ENCRYPTION_MODE 中新增如下枚举值：

  • AES_128_GCM: 128 位 AES 加密，GCM 模式。
  • AES_256_GCM: 256 位 AES 加密，GCM 模式。
开启加密功能后，同一频道内的所有用户都必须使用相同的加密模式和密钥，包括服务端用户（例如声网录制服务）。

2. 远端音频统计

为监测通话中与音频相关的主观体验，该版本在 RemoteAudioStats 中增加如下成员：

  • qoeQuality: 报告接收远端音频时的体验质量。
  • qualityChangedReason: 报告接收远端音频时体验质量较差的原因。
  • mosValue: 报告声网实时音频 MOS（平均主观意见分）评估系统对接收到的远端音频流的质量评分。

问题修复

该版本修复了如下问题：

  • 偶现本地用户无法播放远端音频。(Windows)
  • 360 安全大脑（网购模式）自动拦截程序运行。(Windows)

API 变更

新增

废弃

  • setDefaultMuteAllRemoteVideoStreams
  • setDefaultMuteAllRemoteAudioStreams
  • setLogFile
  • setLogFileSize
  • setLogFilter
  • createDataStream

3.2.1 版

该版本于 2020 年 12 月 30 日发布，修复了如下问题：

  • IPv6 场景下的高概率崩溃问题。
  • 调用 enableEncryption 后，firstLocalVideoFramePublished 回调无法被触发。
  • 部分虚拟摄像头视频采集异常。

3.2.0 版

该版本于 2020 年 12 月 30 日发布。

升级必看

1. 云代理

该版本优化了声网云代理架构。如果你已经在使用云代理，为避免新 SDK 和老云代理的兼容性问题，请在升级 SDK 前联系技术支持。详见云代理。

云代理在 Electron 和 Windows 平台上用法完全相同。

2. 安全合规

声网已通过 ISO 27001、ISO 27017、ISO 27018 国际认证，为全球用户提供安全可靠的实时互动云服务。详见 ISO 证书。

同时，为支持传输层加密，该版本新增 TLS（Transport Layer Security）加密和 UDP（User Datagram Protocol）加密方式。

传输层加密导致 SDK 包体积大小受到影响，数据详见《产品概述》。

新增特性

1. 美颜

常见的视频社交、在线教育和连麦直播等场景中，用户普遍希望有基础的美颜功能。该版本在 macOS 平台上新增支持 setBeautyEffectOptions 方法，你可以调用该接口设置对比度、亮度、平滑度等参数，达到美白、磨皮、红润肤色等美颜效果。

2. 极速直播

该版本新增 setClientRoleWithOptions 方法，支持设置观众的延时级别。你可以通过该方法在互动直播和极速直播之间切换：

  • 将观众的延时级别设为超低延时，使用互动直播。
  • 将观众的延时级别设为低延时，使用极速直播。

详见极速直播产品概述。

3. 设置区域访问限制

该版本新增支持在调用 initialize 方法时通过 areaCode 参数限定 SDK 访问指定的区域：

  • 如果用户在指定区域内，正常情况下，SDK 会连接位于你指定区域的声网服务器。
  • 如果用户不在指定区域内，SDK 会从位于用户所在区域和你指定区域的声网服务器中择优选择，然后建立连接。

4. 发布和订阅状态转换回调

该版本新增以下回调方便你了解音视频流当前的发布及订阅状态，有助于订阅和发布相关的数据统计：

  • audioPublishStateChanged：音频发布状态发生改变。
  • videoPublishStateChanged：视频发布状态发生改变。
  • audioSubscribeStateChanged：音频订阅状态发生改变。
  • videoSubscribeStateChanged：视频订阅状态发生改变。

5. 本地首帧发布回调

为提示用户本地音视频首帧已发布，该版本新增如下回调：

  • firstLocalAudioFramePublished：已发布本地音频首帧回调。该回调取代 firstLocalAudioFrame 回调，我们推荐你不再使用 firstLocalAudioFrame 回调。
  • firstLocalVideoFramePublished：已发布本地视频首帧回调。

6. 自定义数据上报

该版本支持自定义数据上报。如需试用，请联系 sales@shengwang.cn 开通并商定自定义数据格式，然后调用 sendCustomReportMessage 方法。

7. 调整音乐文件音调

为方便调整混音时音乐文件的播放音调，该版本新增 setAudioMixingPitch 方法。通过设置该方法的 pitch 参数，你可以升高或降低音乐文件的音调。该方法仅对音乐文件音调有效，对本地人声不生效。

8. 媒体附属信息

常见的直播场景中，主播会给观众分发商品链接、优惠券、在线答题等。为满足这种开发这种场景的需求，该版本新增如下 API，以支持主播在发出的视频帧中添加 metadata。

  • registerMediaMetadataObserver 方法：注册媒体附属信息观测器。
  • unRegisterMediaMetadataObserver 方法：取消注册媒体附属信息观测器。
  • setMaxMetadataSize 方法：设置媒体附属信息的最大大小。
  • sendMetadata 方法：发送媒体附属信息。
  • receiveMetadata 回调：已接收到媒体附属信息回调。
  • sendMetadataSuccess 回调：已发送出媒体附属信息回调。

改进

1. 会议场景

为提升会议场景的用户体验，该版本对音频属性和屏幕共享进行如下优化：

  • 音频编码属性：为提升多人会议的音频体验，该版本在 setAudioProfile 方法中新增 scenario 为 8 (Meeting)。
  • 屏幕共享：
    • 该版本新增支持共享过程中，将共享的幻灯片进入演示模式，将共享的窗口（如网页视频、网页文档）开启全屏模式。
    • 该版本在 localVideoStateChanged 回调中新增 error 为 12 (Closed)，提示你通过窗口 ID 共享的窗口已关闭，或通过窗口 ID 共享的全屏窗口已退出全屏。
    • 置顶指定窗口：通过在 CaptureParam 接口中新增 windowFocus 实现。
    • 屏蔽指定窗口：通过在 CaptureParam 接口中新增 excludeWindowList 实现。
    • 屏幕共享下的本地视频状态报告：通过在 localVideoStateChanged 回调中新增状态码 1 和错误码 11 实现。
    • 该版本优化弱网环境下 CONTENT_HINT_DETAILS 屏幕共享的流畅度和画质。

2. 美声与音效

为提升美声与音效 API 的易用性，该版本废弃 setLocalVoiceChanger 和 setLocalVoiceReverbPreset，并新增如下方法替代：

  • setVoiceBeautifierPreset: 与 setLocalVoiceChanger 相比，该方法删除了小男孩等变声音效和空旷音效。
  • setAudioEffectPreset: 与 setLocalVoiceReverbPreset 相比，该方法新增了小男孩等变声音效、空旷音效、3D 人声音效和电音音效，并删除了摇滚和嘻哈音效。
  • setAudioEffectParameters: 对指定的音效选项进行更细节的设置。该版本支持的音效选项有 3D 人声和电音音效。

3. 互动直播延时

互动直播场景下，观众看直播的延时降低了约 500 ms。

4. CDN 直播推流

为提升 CDN 直播推流用户体验，该版本新增 rtmpStreamingEvent 回调，报告推流过程中发生的事件，如未成功添加背景图或水印。

5. 加密

该版本新增 enableEncryption 方法，用于开启内置加密，并废弃原加密方法：

  • setEncryptionSecret
  • setEncryptionMode

与原加密方法相比，该方法新增对国密 SM4 加密模式的支持，你可以根据需要选择合适的加密模式。

6. 通话中质量透明

该版本进一步扩充了 LocalAudioStats、LocalVideoStats、RemoteVideoStats 和 RemoteAudioStats 接口的属性，提供更多音视频质量相关数据。

  • LocalAudioStats 接口新增 txPacketLossRate，表示本端到声网边缘服务器的物理音频丢包率 (%)。
  • LocalVideoStats 接口新增
    • txPacketLossRate：本端到声网边缘服务器的物理视频丢包率 (%)。
    • captureFrameRate：本地视频采集帧率 (fps)。
  • RemoteAudioStats 和 RemoteVideoStats 接口中新增 publishDuration，表示远端音频流和视频流的累计发布时长（毫秒）。

7. 设置音频编码属性

为提升音频性能，该版本对音频编码码率最大值进行如下优化：

profile 3.2.0 版本 3.2.0 版本之前
0 (default)
  • 直播场景：64 Kbps
  • 通信场景：16 Kbps (Windows)，18 Kbps (macOS)
    		•
  • 直播场景：52 Kbps
  • 通信场景：16 Kbps (Windows)，18 Kbps (macOS)
    		•
    1 (speech standard) 18 Kbps 18 Kbps
    2 (music standard) 64 Kbps 48 Kbps
    3 (music standard stereo) 80 Kbps 56 Kbps
    4 (music high quality) 96 Kbps 128 Kbps
    5 (music high quality stereo) 128 Kbps 192 Kbps

    8. 日志扩容

    该版本中，声网 SDK 日志文件的默认个数由 2 个增加至 5 个，单个日志文件的默认大小由 512 KB 扩大至 1024 KB。默认情况下，SDK 会生成 agorasdk.log、agorasdk_1.log、agorasdk_2.log、agorasdk_3.log、agorasdk_4.log 这 5 个日志文件。最新的日志永远写在 agorasdk.log 中。agorasdk.log 写满后，SDK 会从 1-4 中删除修改时间最早的一个文件，然后将 agorasdk.log 重命名为该文件，并建立新的 agorasdk.log 写入最新的日志。详见 setLogFileSize。

    9. 音频路由

    为支持在更多设备中播放音频，该版本在 AUDIO_ROUTE_TYPE 中新增 4 个类型：

    • 6: USB 外围设备 (macOS)
    • 7: HDMI 外围设备 (macOS)
    • 8: DisplayPort 外围设备 (macOS)
    • 9: Apple AirPlay (macOS)

    10. 优化弱网环境下的视频体验

    该版本优化了弱网环境下的视频体验：

    • 通过自动降低弱网环境下的视频分辨率，优化视频流畅度。
    • 优化网络状态变化过程中的视频画质，从而保证视频画面不模糊。

    问题修复

    该版本修复了如下问题：

    • AirPods 无声问题。(macOS)
    • 开启其他视频应用时，SDK 无法开启本地摄像头的问题。(macOS)
    • 该版本修复了特定场景下偶现因设备音频模块未启动，导致的本地录音无声。(macOS)
    • 音频无声、进频道后蓝牙设备断开、无法进入频道等问题。(macOS)
    • 该版本修复了华为特定型号的笔记本上偶现啸叫的问题。(Windows)
    • 美颜功能不生效。(Windows)
    • Loopback 测试异常等问题。(Windows)
    • 连麦用户屏幕共享黑屏的问题。(Windows)
    • clientRoleChanged 回调多次的问题。(Windows)
    • 日志目录乱码等问题。(Windows)
    • firstLocalVideoFrame 和 firstRemoteVideoFrame 回调的触发时机不准确的问题。(macOS/Windows)
    • 混音相关问题。(macOS/Windows)
    • App ID 和 Token 校验的问题。(macOS/Windows)

    API 变更

    新增

    废弃

    • setLocalVoiceChanger
    • setLocalVoiceReverbPreset
    • setEncryptionSecret
    • setEncryptionMode
    • firstLocalAudioFrame

    3.0.0 版

    该版本于 2020 年 4 月 7 日发布。

    在该版本对通信场景采用了全新的系统架构，并升级了通信和直播场景下的 last mile 网络策略。在带宽不足时，新的网络策略能充分利用上下行有限带宽提升有效码率，从而增强弱网对抗能力，极大提升了弱网情况下通信和直播场景的终端用户体验。

    由于通信场景采用了新的系统架构，为保证新老版本通信用户的互通兼容，我们使用了回退机制。如果频道内有老版本通信用户加入，则当前版本 (3.0.0) 的终端用户会回退成老版本通信。一旦回退，频道内所有用户都无法享受新版本带来的体验提升。因此我们强烈推荐同步升级所有终端用户到当前版本。

    同时，我们对本地服务端录制进行了升级发布。为确保享受全新架构和网络策略优化带来的好处，使用本地服务端录制的客户，请务必同步升级本地服务端录制 SDK 至 3.0.0 版本。

    新增特性、改进与问题修复详见下文。

    升级必看

    1. 通信场景上行默认不开启视频小流

    从该版本起，声网在通信场景下，默认不开启视频小流。如需启用，请在成功加入频道后，调用 enableDualStreamMode (true) 方法启用视频双流模式。在多人视频通信场景下，我们建议你开启视频双流。

    新增特性

    1. 多频道管理

    为方便用户在同一时间加入多个频道，该版本新增了 AgoraRtcChannel 类。通过创建多个 AgoraRtcChannel 对象，用户可以同时加入各 AgoraRtcChannel 对象对应的频道中，实现多频道功能。

    加入多个频道后，用户可以同时接收多个频道的流，但只能同时在一个频道内发流。该功能适用于用户需要同时接收多个频道的流，或频繁切换频道发流的场景。

    2. 调节本地播放的指定远端用户音量

    该版本新增 adjustUserPlaybackSignalVolume 方法，用以调节本地用户听到的指定远端用户的音量。通话或直播过程中，你可以多次调用该方法，来调节多个远端用户在本地播放的音量，或对某个远端用户在本地播放的音量调节多次。

    3. 人声检测

    为判断本地用户是否说话，该版本在启用说话者音量提示 enableAudioVolumeIndication 方法中新增 boolean 型的 report_vad 参数。启用该参数后，你会在 groupAudioVolumeIndication 回调中获取本地用户的人声状态。

    4. 美颜（Windows）

    常见的视频社交、在线教育和连麦直播等场景中，用户普遍希望有基础的美颜功能。该版本新增接口 setBeautyEffectOptions，你可以调用该接口设置对比度、亮度、平滑度等参数，达到美白、磨皮、红润肤色等美颜效果。

    改进

    1. 音频编码属性

    为满足更高音质需求，该版本调整了直播场景下 setAudioProfile 中 profile(0) 对应的音频编码属性，详见下表：

    SDK 版本 profile(0)
    3.0.0 48 KHz 采样率，音乐编码，单声道，编码码率最大值为 52 Kbps。
    3.0.0 之前
  • macOS：32 KHz 采样率，音乐编码，单声道，编码码率最大值为 44 Kbps。
  • Windows：32 KHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
    		•

    2. 镜像模式

    为提升视频镜像的使用体验，该版本增加了视频编码镜像的功能：

    在 VideoEncoderConfiguration 接口中，新增 mirrorMode 属性，方便设置本地视频编码的镜像模式，即远端看本地是否镜像。

    3. 质量透明

    为方便开发者获取更多通话统计信息，该版本在 RtcStats 接口中新增 gatewayRtt、memoryAppUsageRatio、memoryTotalUsageRatio 和 memoryAppUsageInKbytes 属性，方便更好地监控通话中的网络状态和内存使用情况。

    4. 屏幕共享

    为支持更多屏幕共享使用场景，该版本新增支持通过窗口信息共享屏幕时支持共享通用 Windows 平台（UWP）应用窗口。

    5. 直播水印

    该版本允许用户将一张 PNG 图片作为水印添加到正在进行的本地直播中。新增 addVideoWatermark 和 clearVideoWatermark 方法，以添加或删除本地直播水印。

    6. 设置客户端录音采样率

    为方便用户设置客户端录音的采样率，该版本废弃了原有方法，并使用新的 startAudioRecording 方法进行取代。新的方法下，录音采样率可设为 16、32、44.1 或 48 kHz。

    7. 其他提升

    该版本自动开启直播场景下 Electron SDK 与 Web SDK 的互通，并废弃原有的 enableWebSdkInteroperability 和 videoSourceEnableWebSdkInteroperability 方法。

    问题修复

    • 修复了混音、音频录制、音频编码、回声等音频问题。
    • 修复了水印、视频画面比例、画质模糊、视频不能全屏、屏幕共享黑边等视频问题。
    • 修复了特定场景下偶现的 app 崩溃、日志文件、推流不稳定等问题。
    • 通信场景下，调用 setRemoteSubscribeFallbackOption 方法也生效。
    • 一对一通信场景下，下行音视频弱网下会回退为纯音频。
    • macOS 10.15 系统下，偶现系统渲染窗口 UI 异常。

    API 变更

    行为变更

    该版本修改了 macOS 设备连接耳机或蓝牙时的音频路由。修改后的语音路由与 macOS 设备管理器中显示的一致。

    新增

    废弃

    • enableWebSdkInteroperability
    • videoSourceEnableWebSdkInteroperability
    • firstRemoteVideoFrame，使用 remoteVideoStateChanged 取代
    • userMuteAudio,firstRemoteAudioDecoded 和 firstRemoteAudioFrame，使用 remoteAudioStateChanged 取代
    • streamPublished 和 streamUnpublished，使用 rtmpStreamingStateChanged 取代

    2.9.0 版

    自 2021 年 12 月 8 日起，声网启动对早于 3.0.0 版的音频 SDK、视频 SDK 的退休流程。详见部分服务下架计划。

    该版本于 2019 年 8 月 30 日发布。新增特性与修复问题详见下文。

    升级必看

    远端视频状态

    为方便用户了解远端视频状态，该版本删除了原有的 remoteVideoStateChanged 接口，并使用一个新的同名接口进行取代。新的接口下， state 参数扩展为 STOPPED(0)、STARTING(1)、DECODING(2)、FROZEN(3) 和 FAILED(4)。同时，新接口还增加了 reason 参数，用以报告远端视频状态发生改变的原因。因此，如果你将 SDK 升级至该版本，请确保重新实现 remoteVideoStateChanged 接口。

    同时，扩展后的 state 参数和新增的 reason 参数搭配使用，可以涵盖大部分远端视频状态，因此该版本废弃了如下接口。你可以继续使用这些接口，但我们不再推荐。详细的取代方案，请参考 API 文档：

    • userEnableVideo
    • userEnableLocalVideo
    • addStream

    新增特性

    1. 快速切换频道

    为方便直播频道中的观众用户快速切换到其他频道，该版本新增 switchChannel 方法。和先调 leaveChannel，再调 joinChannel 相比，该方法能实现更快的频道切换。调用 switchChannel 方法切换到其他直播频道后，本地会先收到离开原频道的回调 leaveChannel，再收到成功加入新频道的回调 joinedChannel。

    2. 跨频道媒体流转发

    跨频道媒体流转发，指将主播的媒体流转发至其他直播频道，实现主播跨频道与其他主播实时互动的场景。该版本新增如下接口，通过将源频道中的媒体流转发至目标频道，实现跨直播间连麦功能：

    在跨频道媒体流转发过程中，SDK 会通过 channelMediaRelayState 和 channelMediaRelayEvent 回调报告媒体流转发的状态和事件。

    3. 本地及远端音频状态

    为方便用户了解本地及远端的音频状态，该版本新增 localAudioStateChanged 和 remoteAudioStateChanged 回调。新的回调下，本地及远端音频有如下状态：

    • 本地音频：STOPPED(0)、RECORDING(1)、ENCODING(2) 和 FAILED(3)。状态为 FAILED(3) 时，你可以通过 error 参数中返回的错误码定位及排查问题。
    • 远端音频：STOPPED(0)、STARTING(1)、DECODING(2)、FROZEN(3) 和 FAILED(4)。你可以在 reason 参数中了解引起远端音频状态发生改变的原因。

    4. 本地音频数据

    为方便更好地了解通话质量，获取更多质量相关数据，该版本新增 localAudioStats 回调，通过 numChannels、sentSampleRate、sentBitrate 参数报告本地音频统计信息。

    改进

    1. 通话中质量透明

    该版本进一步扩充了 RtcStats、LocalVideoStats 和 RemoteVideoStats 类的成员。各类新增成员如下：

    • RtcStats 类：累计发送音频/视频字节数及累计接收音频/视频字节数
    • LocalVideoStats 类：本地视频的编码码率、宽高、发送帧数及编码类型
    • RemoteVideoStats 类：远端视频在网络对抗后的丢包率

    2. 直播视频质量提升

    该版本改善了弱网条件下直播视频卡顿问题，提升了画面清晰度，优化了网络极端丢包情况下的直播画面流畅度。

    3. 屏幕共享质量提升

    该版本提升了通信场景下，下行网络状况不佳时，屏幕共享文字的清晰度。该改进只在屏幕共享的内容类型 ContentHint 设置为 Details(2) 时生效。

    4. 其他改进

    • 优化了 Game Streaming 模式下的音频质量。
    • 优化了通信场景下用户关闭麦克风后听到的音质。

    问题修复

    音频

    • 修复了与 Web 互通时听声辨位过程中出现的声音失真的问题。
    • 修复了 muteRemoteAudioStream 方法调用无效的问题。
    • 修复了特殊场景下偶现的音频无声的问题。
    • 修复了测试麦克风时出现的崩溃问题。

    视频

    • 修复了视频卡住的问题。
    • 修复了 remoteVideoStateChanged 回调行为不符预期的问题。

    其他

    • 修复了偶现的旁路推流串流的问题。
    • 修复了偶现的崩溃问题。
    • 修复了特定场景下加入频道失败的问题。

    API 变更

    为提升用户体验，声网 SDK 在该版本中对 API 进行了如下变动：

    新增

    废弃

    • microphoneEnabled 回调，请改用 localAudioStateChanged
    • remoteVideoTransportStats，请改用 remoteVideoStats
    • remoteAudioTransportStats，请改用 remoteAudioStats
    • userEnableVideo，请改用 remoteVideoStateChanged
    • userEnableLocalVideo，请改用 remoteVideoStateChanged
    • addStream，请改用 remoteVideoStateChanged

    2.8.0 版

    该版本于 2019 年 7 月 8 日发布。

    该 SDK 首次发版。你可以参考以下文档集成 SDK，实现相应的实时音视频功能：

    声网提供了开源的 Electron-Quickstart 示例项目，你也可以前往下载并体验。