发版说明

本文提供 Agora RTC Flutter SDK 的发版说明。

已知问题和局限性

iOS 15 兼容性

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

5.2.0 版（对应 Native 3.6.2 版）

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

新增特性

该版本新增对 Flutter 3 的支持。

问题修复

该版本修复了调用以下方法时返回 null 的问题。

• isCameraAutoFocusFaceModeSupported
• isCameraExposurePositionSupported
• isCameraFocusSupported
• isCameraTorchSupported

5.1.1 版（对应 Native 3.6.2 版）

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

该版本修复了以下问题：

• SDK 在部分 Android 机型中崩溃。
• SDK 因不兼容 macOS 11.3 以下版本导致崩溃。

5.1.0 版（对应 Native 3.6.2 版）

该版本于 2022 年 4 月 15 日发布。

升级必看

该版本相比上个版本，发生以下兼容性变更：

• RtcEngine.setDefaultAudioRoutetoSpeakerphone 更名为 RtcEngine.setDefaultAudioRouteToSpeakerphone。
• 成员变量 LiveTranscoding.watermark 的类型由AgoraImage? 更改为 List<AgoraImage>?。
• 成员变量 LiveTranscoding.backgroundImage 的类型由 AgoraImage? 更改为 List<AgoraImage>?。
• 成员变量 LiveTranscoding.backgroundColor 的类型由 Color 更改为 int。
• 成员变量 VideoEncoderConfiguration.degradationPrefer 重命名为 degradationPreference。
• 成员变量 VirtualBackgroundSource.color 的类型由 Color 更改为 int。

新增特性和改进

该版本适配了 Agora RTC Native SDK 3.6.2 版。新增特性、改进等内容详见各平台自 3.5.2 到 3.6.2 版的发版说明：

• Android 发版说明
• iOS 发版说明
• macOS 发版说明
• Windows 发版说明

已知问题

startAudioMixing 不支持播放 Flutter 项目中 assets 路径下的音乐文件。

5.0.0 版（对应 Native 3.5.2 版）

该版本于 2022 年 2 月 22 日发布。

自该版本起，Agora RTC Flutter SDK 支持 Flutter 2.x，支持运行在 Android，iOS，macOS，Windows 平台。

升级必看

该版本优化了底层架构，代码更加整洁，你可以参考如下兼容性变更修改你的业务代码：

• RtcEngine 类中兼容性变更：

  • getErrorDescription 不再是 static 方法
  • getSdkVersion 不再是 static 方法
  • sendMetadata 中 metadata 数据类型由 String 变更为 Uint8List
  • sendStreamMessage 中 message 数据类型由 String 变更为 Uint8List
  • setEffectsVolume 中 volume 数据类型由 double 变更为 int
  • setLocalVoiceReverbPreset 中 preset 更名为 reverbPreset
  • setVolumeOfEffect 中 volume 数据类型由 double 变更为 int
  • enableFaceDetection 中 enabled 更名为 enable
  • enableDeepLearningDenoise 中 enabled 更名为 enable
  • enableRemoteSuperResolution 中 uid 更名为 userId，enabled 更名为 enable
  • getAudioFileInfo 方法返回值由 void 变更为 int
  • playEffect 中 gain 数据类型由 double 更名为 int
  • setEnableSpeakerphone 中 enabled 更名为 defaultToSpeaker
  • setRemoteVideoStreamType 中 uid 更名为 userId

• RtcChannel 类中兼容性变更：

  • sendMetadata 中 metadata 数据类型由 String 变更为 Uint8List
  • sendStreamMessage 中 message 数据类型由 String 变更为 Uint8List
  • muteRemoteAudioStream 中 uid 更名为 userId
  • muteRemoteVideoStream 中 uid 更名为 userId
  • setRemoteVideoStreamType 中 uid 更名为 userId
  • enableRemoteSuperResolution 中 uid 更名为 userId，enabled 更名为 enable
  • muteLocalAudioStream 中 muted 更名为 mute
  • muteLocalVideoStream 中 muted 更名为 mute
  • createWithContext 中 context 更名为 config

• View 相关的兼容性变更：

  • RtcSurfaceView 中 channelId 由可选变为必填
  • RtcTextureView 中 channelId 由可选变为必填

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

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

新增特性和改进

该版本适配了 Agora RTC Native SDK 3.5.2 版。新增特性、改进等内容详见各平台自 3.5.0.4 到 3.5.2 版的发版说明：

• Android 发版说明
• iOS 发版说明
• macOS 发版说明
• Windows 发版说明

4.0.7 版（对应 Native 3.5.0.3 版）

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

升级必看

音频路由行为变更 （仅 Android 平台）

为提升用户体验，该版本优化了如下 SDK 行为：

• 当 SDK 使用媒体音量时，音频路由受如下影响：

  • 4.0.7 之前，SDK 无法设置音频路由为听筒。
  • 4.0.7 及之后，SDK 可以设置音频路由为听筒，但同时 SDK 使用的音量类型会变成通话音量。如果将音频路由再次切换回扬声器，则音量类型会恢复为媒体音量。
  参考如何区分媒体音量和通话音量了解 SDK 使用媒体音量的场景。

• 如果连接了多个外置音频设备，当用户移除当前播放设备时，音频路由受如下影响：

  • 4.0.7 之前，音频不会通过任何路由播放，造成无声问题。
  • 4.0.7 及之后，音频路由会按如下优先级设置：倒数第二个连接的外置设备 > ... > 第一个连接的外置设备 > setEnableSpeakerphone > setDefaultAudioRouteToSpeakerphone > SDK 默认的音频路由。

更多介绍见 Android 平台的设置音频路由。

新增特性

虚拟背景（beta）

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

改进

1. 视频画质

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

• 通过对色彩范围的适配，提升采集和接收的视频对比度，以改善画面泛白问题。
• 通过对色彩空间的适配，提升采集和接收的视频色彩丰富度，进一步还原视频色彩。
• 自动开启最佳的视频采集策略，使采集的视频画质（分辨率、帧率、色彩范围等）最优。该改进仅针对采集分辨率不高于 1080P 的部分视频。（仅 iOS 平台）
• 默认开启摄像头自动对焦并动态调整采集行为，以改善画面过曝问题。如果你想关闭自动对焦，请调用 setCameraAutoFocusFaceModeEnabled(false)。（仅 iOS 平台）

2. 其他改进

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

• 降低了高分辨率（720P 及更高）场景下 CPU 占用率和端到端视频延时。（仅 Android 平台）
• 在开启 AGC 的场景下，缩短降噪收敛的时间，从而降低噪声忽大忽小的波动。
• 改善了视频自渲染场景下的出帧平滑度。

问题修复

该版本修复了如下问题：

Android 和 iOS 平台

• 远端用户调用 enableLoopbackRecording 后，偶现本地用户听到自己的回声。
• 调用 muteLocalAudioStream(true) 停止发布本地音频后，用户第一次加入频道可以听到远端用户，但退出频道后再次加入频道偶现无法听到远端用户。
• 本地网络环境较差时，SDK 报告的远端用户的下行网络质量 （rxQuality）不准确。

仅 Android 平台

• 特定场景下，偶现更新旁路推流转码布局失败。

仅 iOS 平台

• 会议场景下，远端用户在频道内开启本地音频采集后，偶现本地用户听远端用户有回声。
• RtcStats 回调报告的 memoryTotalUsageRatio 的值不准确。
• 偶现的崩溃问题。
• 设置输出视频为 FixedPortrait 模式时，分辨率宽高设置颠倒导致的大头问题。

API 变更

新增

• enableVirtualBackground
• VirtualBackgroundSourceEnabled

修改

• setEnableSpeakerphone
• setDefaultAudioRouteToSpeakerphone

4.0.6 版（对应 Native 3.4.6 版）

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

改进

为提升人脸检测结果的准确性，自该版本起，SDK 在检测到人脸消失后会立即触发 facePositionChanged 回调。

问题修复

该版本修复了如下问题：

• 特定的 Android 4.4 TV 机型上，开启摄像头失败。
• 使用 Type-C 耳机时声音小的问题。
• 在特定 Android 机型上运行项目时出现 interface xxx is not visible from class loader 报错。
• 特定场景下，SDK 初始化时偶现崩溃。
• 调用 startAudioMixing 时传入经过百分号编码后的 URL，对应的在线音频文件播放失败。

4.0.5 版（对应 Native 3.4.5 版）

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

升级必看

1. iOS 15 兼容性 （仅 iOS 平台）

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

2. API 兼容性变更

该版本对 API 进行了如下涉及兼容性的变更：

• 废弃 RtcEngineConfig 类和 createWithConfig 方法，并新增 RtcEngineContext 类和 createWithContext 方法替代。与 RtcEngineConfig 相比，RtcEngineContext 类中的 areaCode 属性的数据类型由 AreaCode 变更为 List<AreaCode>，支持设置多个多个访问区域。
• RtcStats 接口中的 totalDuration 属性更名为 duration，users 属性更名为 userCount，数据类型和含义保持不变。
• 所有类的构造函数都严格区分必传和非必传参数，详见构造函数变更列表。
• getAssetAbsolutePath 方法变更为非 static 函数，且支持使用 RtcEngine 类实例调用。

如果你将 SDK 升级到 v4.0.5 或更高版本，为保证你的业务功能不受影响，Agora 推荐你修改上述 API 的实现。

3. 支持 GCM2 加密

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

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

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

4. 媒体流发布行为变更

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

• 废弃 publish 和 unpublish，并新增 muteLocalAudioStream 和 muteLocalVideoStream 作为替代。你可以分别设置音频流和视频流的发布状态。
• 在 ChannelMediaOptions 中新增 publishLocalAudio 和 publishLocalVideo 成员。你可以在加入频道时设置音视频流的发布状态。
• 调用 setClientRole(Broadcaster) 后，本地用户默认发布音视频流。

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

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

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

改进

1. 旁路推流

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

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

2. 音乐文件状态

在 pauseAudioMixing 后调用 startAudioMixing 时，该版本在报告 AudioMixingStateChanged(Playing,StartedByUser) 状态之前新增了 AudioMixingStateChanged(Stopped,StoppedByUser) 状态，提示已停止播放音乐文件。

3. 音频设备出错

为方便获取系统电话对音频采集的影响，该版本在 AudioLocalError 中新增 Interrupted (8)，报告音频采集被系统电话中断。

问题修复

该版本修复了如下问题：

• 在弱网环境下，调用 startAudioMixing 播放在线音乐文件时，偶现 SDK 响应时间过长而引起卡顿。
• 在弱网环境下，频繁调用 startAudioMixing 播放在线音乐文件时，偶现 ANR 弹窗。
• 在部分 Android 设备上，连接蓝牙耳机后，声音依旧通过扬声器播放。
• 特定场景下切换音频路由到蓝牙，偶现蓝牙设备采集失效。
• 弱网环境下，偶现用户无法切换角色。
• 特定网络环境下，主播使用小米手机进行纹理格式的视频自采集时，频道内其他用户看主播黑屏。
• 应用运行在 M1 芯片设备上时，偶现用户画面上下颠倒。（仅 iOS 平台）。

API 变更

新增

• RtcEngineContext 类
• createWithContext
• RtmpStreamingErrorCode 中新增 UnPublishOK (100)
• RtmpStreamingEvent 中新增 UrlAlreadyInUse (2)
• EncryptionMode 中新增 AES128GCM2 (7) 和 AES256GCM2 (8)
• EncryptionConfig 中新增 encryptionKdfSalt
• RtcChannel 中新增 muteLocalAudioStream 和 muteLocalVideoStream
• ChannelMediaOptions 中新增 publishLocalAudio 和 publishLocalVideo
• AudioLocalError 中新增 Interrupted (8)

修改

• RtcStats 接口中的 totalDuration 属性更名为 duration，users 属性更名为 userCount。

废弃

• createWithConfig
• RtcEngineConfig 类
• RtcChannel 类的 publish 和 unpublish

类的构造函数变更

为提升代码的规范性和健壮性，自 4.0.5 版本起，Agora SDK 对所有类的成员属性严格区分了必传和非必传，并修改了类的构造函数。

本节列出了 4.0.5 版本所有涉及构造函数变更的类。如果你将 SDK 升级到 4.0.5 或更高版本，为保证你的业务功能不受影响，请确保修改这些类的实现。

• VideoDimensions
• AgoraImage
• TranscodingUser
• ChannelMediaInfo
• Rectangle
• WatermarkOptions
• CameraCapturerConfiguration
• ChannelMediaOptions
• EncryptionConfig
• RtcStats
• ClientRoleOptions
• DataStreamConfig
• getAssetAbsolutePath

VideoDimensions

VideoDimensions 类中的以下属性由必传变为可选：

• width
• height

VideoDimensions 类构造函数变更如下：

v4.0.5 之前

new VideoDimensions(640, 360);

v4.0.5 起

new VideoDimensions(width: 640, height: 360);

AgoraImage

AgoraImage 类中的以下属性由必传变为可选：

• x
• y
• width
• height

AgoraImage 的构造函数变更如下：

v4.0.5 之前

new AgoraImage('url', 0, 0, 640, 360);

v4.0.5 起

new AgoraImage('url', x: 0, y: 0, width: 640, height: 360);

TranscodingUser

TranscodingUser 类中的以下属性由必传变为可选：

• x
• y

TranscodingUser 的构造函数变更如下：

v4.0.5 之前

new TranscodingUser(0, 0, 0, width: 640, height: 360, ...);

v4.0.5 起

new TranscodingUser(0, x: 0, y: 0, width: 640, height: 360, ...);

ChannelMediaInfo

ChannelMediaInfo 类中的 channelName 由可选变为必传。

ChannelMediaInfo 的构造函数变更如下：

v4.0.5 之前

new ChannelMediaInfo(0, channelName: 'channelName', token: 'token');

v4.0.5 起

new ChannelMediaInfo('channelName', 0, token: 'token');

Rectangle

Rectangle 类中的以下属性由必传变为可选：

• x
• y
• width
• height

Rectangle 的构造函数变更如下：

v4.0.5 之前

new Rectangle(0, 0, 640, 360);

v4.0.5 起

new Rectangle(x: 0, y: 0, width: 640, height: 360);

WatermarkOptions

WatermarkOptions 类中的以下属性由必传变为可选：

• positionInLandscapeMode
• positionInPortraitMode

WatermarkOptions 的构造函数变更如下：

v4.0.5 之前

new WatermarkOptions(Rectangle, Rectangle, visibleInPreview: true);

v4.0.5 起

new WatermarkOptions(visibleInPreview: true, positionInLandscapeMode: Rectangle, positionInPortraitMode: Rectangle);

CameraCapturerConfiguration

CameraCapturerConfiguration 类中的以下属性由必传变为可选：

• preference
• cameraDirection

CameraCapturerConfiguration 的构造函数变更如下：

v4.0.5 之前

new CameraCapturerConfiguration(CameraCaptureOutputPreference, CameraDirection, captureWidth: 640, captureHeight: 360);

v4.0.5 起

new CameraCapturerConfiguration(preference: CameraCaptureOutputPreference, captureWidth: 640, captureHeight: 360, cameraDirection: CameraDirection);

ChannelMediaOptions

ChannelMediaOptions 类中的以下属性由必传变为可选：

• autoSubscribeAudio
• autoSubscribeVideo

ChannelMediaOptions 的构造函数变更如下：

v4.0.5 之前

new ChannelMediaOptions(true, true);

v4.0.5 起

new ChannelMediaOptions(autoSubscribeAudio: true, autoSubscribeVideo: true);

EncryptionConfig

EncryptionConfig 类中的以下属性由必传变为可选：

• encryptionMode
• encryptionKey

EncryptionConfig 的构造函数变更如下：

v4.0.5 之前

new EncryptionConfig(EncryptionMode, 'encryptionKey');

v4.0.5 起

new EncryptionConfig(encryptionMode: EncryptionMode, encryptionKey: 'encryptionKey');

RtcStats

自 v4.0.5 起，RtcStats 类中的所有属性都不允许为 null，节省了开发时额外的判断逻辑。

ClientRoleOptions

ClientRoleOptions 类中的 audienceLatencyLevel 属性由必传变为可选。

ClientRoleOptions 的构造函数变更如下：

v4.0.5 之前

new ClientRoleOptions(AudienceLatencyLevelType);

v4.0.5 起

new ClientRoleOptions(audienceLatencyLevel: AudienceLatencyLevelType);

DataStreamConfig

DataStreamConfig 类中的以下属性由可选变为必传：

• syncWithAudio
• ordered

DataStreamConfig 的构造函数变更如下：

v4.0.5 之前

new DataStreamConfig(syncWithAudio: true, ordered: true);

v4.0.5 起

new DataStreamConfig(true, true);

4.0.1 版（对应 Native 3.4.2 版）

该版本于 2021 年 5 月 25 日发布。

升级必看

集成变更

1. 支持 Null safety

从该版本起，Agora RTC Flutter SDK 支持 Null safety。由于 Null safety 功能不向前兼容，你的 Dart 必须是 2.12 或更高版本。详见 Flutter 官方文档。

2. 支持 Flutter 2.x （仅支持 Android 和 iOS）

从该版本起，Agora RTC Flutter SDK 支持 Flutter 2.x，但仅限于 Android 和 iOS 平台。

3. SDK 包发布平台 (仅 Android 平台)

由于 JCenter 即将关闭，Agora 已停止将 RTC Android SDK 包发布到 JCenter，改为发布到 JitPack。因此，编译 Android 应用时，请确保在项目的 /android/build.gradle 文件中添加如下行：

allprojects {
    repositories {
        ...
        maven { url 'https://www.jitpack.io' }
    }
}

4. 插件列表

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

行为变更

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

• 将 errorCode 参数修改为 reason 参数。
• 废弃 AudioMixingErrorCode，并新增 AudioMixingReason 替代。通过 AudioMixingReason，你可以获取播放开始、暂停、停止或失败的原因。
• 修改 AudioMixingStateCode 的部分逻辑。例如，循环播放音乐时，播放完成或开始播放都会触发 Playing 状态。

如果你将 SDK 升级到 v4.0.1 或更高版本，为保证你的业务功能不受影响，Agora 推荐你修改 AudioMixingStateChanged 的实现。

新增特性

1. 虚拟节拍器

为满足在线教学等场景对节拍器的需求，该版本新增如下方法：

• startRhythmPlayer：开启虚拟节拍器。
• stopRhythmPlayer：关闭虚拟节拍器。
• configRhythmPlayer：在开启虚拟节拍器后，重新配置虚拟节拍器。

2. 音效文件播放进度

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

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

改进

1. 本地文件路径 （仅 Android 平台）

为符合 Google Play Store 的要求，该版本支持通过 URI 访问本地文件。如需调用 startAudioMixing、startAudioRecordingWithConfig、getAudioMixingDuration、preloadEffect、playEffect、 getEffectDuration 或 addVideoWatermark，Agora 推荐你按如下步骤访问本地文件：

1. 使用 Storage Access Framework 获取本地文件的 URI。
2. 调用 Uri.toString 将 URI 转换为字符串。
3. 将转换的字符串传入 filePath 或 watermarkUrl 参数。

2. 视频编码

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

3. 音乐文件播放进度

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

• startAudioMixing 新增 startPos 参数，支持在播放音乐文件时设置播放位置。
• getAudioMixingDuration 新增 filePath 参数，支持在播放本地音乐文件前获取该音乐文件总时长。

4. 客户端录音

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

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

5. 媒体设备出错

为方便用户了解本地视频出错原因，该版本在 LocalVideoStreamError 中新增错误码 DeviceNotFound(8)，报告无法找到本地视频采集设备。

问题修复

该版本修复了如下问题：

• 音频采样率超出 4.8 kHz 时引起的崩溃。
• 调用 enableSoundPositionIndication(true) 后 AudioVolumeIndication 回调的音量信息不准确。
• 远端用户切换前后摄像头时，本地用户看到远端画面闪现颠倒。
• 在特定的基础变声场景下，出现崩溃。
• 极端弱网情况下，Native 用户看 Web 主播花屏。
• Mac 上使用神奇效果最小化共享的窗口时，远端用户看到扭曲的画面。
• 长时间在后台的应用回到前台时，偶现用户无法加入频道。（仅 iOS 平台）
• 在调用 setupLocalVideo 或 setupRemoteVideo 后调用如 getCallId、getSdkVersion 的 get 方法或 destroy 方法，app 的用户界面会卡住。（仅 iOS 平台）
• 特定场景下偶现崩溃。（仅 iOS 平台）
• 特定场景下，接收到的自定义视频帧画面旋转。（仅 Android 平台）

API 变更

新增

• startRhythmPlayer
• stopRhythmPlayer
• configRhythmPlayer
• startAudioRecordingWithConfig
• getEffectDuration
• setEffectPosition
• getEffectCurrentPosition
• getAudioMixingDuration 新增 filePath 参数
• playEffect 新增 startPos 参数
• startAudioMixing 新增 startPos 参数
• LocalVideoStreamError 中新增 DeviceNotFound(8)
• 错误码: AlreadyInRecording(160)

修改

• AudioMixingStateChanged

废弃

• startAudioRecording
• AudioMixingErrorCode

3.3.1 版

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

升级必看

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

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

新增特性

1. 频道媒体选项

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

2. 云代理

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

3. AI 降噪

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

4. 歌唱美声

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

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

5. 设置日志文件

为保证日志内容的完整性，该版本新增 createWithConfig 方法，并在 config 参数中新增 logConfig 属性，在你初始化 RtcEngine 时可用于设置 Agora SDK 输出的日志文件。详见如何设置日志文件。

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

6. 采集画质

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

• 自定义采集分辨率：调用 setCameraCapturerConfiguration 方法，将采集偏好设为 Manual(3) 并设置采集视频的宽高。

• 监听采集异常：

  • 采集的画质亮度异常：通过 localVideoStats 回调的 captureBrightnessLevel 监听。
  • 摄像头无法输出采集视频：通过 localVideoStateChanged(Failed, CaptureFailure) 回调监听。
  • 摄像头重复输出采集视频：通过 localVideoStateChanged(Capturing, CaptureFailure) 回调监听。

（仅适用于 iOS）同时，为提升用户体验，该版本在 localVideoStateChanged 回调中新增本地采集出错的原因：

• CaptureInBackGround(6)：应用处于后台。
• CaptureMultipleForegroundApps(7)：应用窗口处于侧拉、分屏、画中画模式。

7. 创建数据流

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

8. 基础变声

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

改进

1. AES-GCM 加密模式

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

• AES128GCM: 128 位 AES 加密，GCM 模式。
• AES256GCM: 256 位 AES 加密，GCM 模式。

2. 远端音频统计

• 为监测通话中与音频相关的主观体验，该版本在 remoteAudioStats 中增加 mosValue，报告 Agora 实时音频 MOS（平均主观意见分）评估系统对接收到的远端音频流的质量评分。
• 为方便监测通话中与音频有关的主观体验，该版本在 remoteAudioStats 中增加 qoeQuality 和 qualityChangedReason，报告接收远端音频时的体验质量以及体验质量较差的原因。

问题修复

Android 平台

• 特定机型上，设备被插入耳机后，采集音频失败。
• Android 10 设备上偶现的采集本地音频失败的问题。

iOS 平台

该版本修复了如下问题：

• 开启听声辨位后，无法通过 audioVolumeIndication 回调获取远端用户音量。
• 在应用窗口切换为侧拉、分屏、画中画模式时调用 enableLocalVideo(false) 有可能会崩溃。

API 变更

新增

• createWithConfig
• setVoiceConversionPreset
• EncryptionMode 中新增 AES128GCM 和 AES256GCM
• RemoteAudioStats 中新增 mosValue
• setVoiceBeautifierParameters
• VoiceBeautifierPreset 中新增 SingingBeautifier
• enableDeepLearningDenoise
• joinChannel 新增 options 参数
• switchChannel 新增 options 参数
• createDataStreamWithConfig
• RemoteAudioStats 中新增 qoeQuality 和 qualityChangedReason 属性
• setCloudProxy
• LocalVideoStats 中新增 captureBrightnessLevel 属性
• CameraCapturerConfiguration 中新增 captureWidth 和 captureHeight 属性
• CameraCaptureOutputPreference 中新增 Manual(3)
• LocalVideoStreamError 中新增 CaptureInBackGround(6) 和 CaptureMultipleForegroundApps(7)
• 错误码: ModuleNotFound(157)

废弃

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

3.2.1 版

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

升级必看

1. 云代理

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

2. 安全合规

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

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

新增特性

极速直播

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

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

详见极速直播产品概述。

改进

1. 会议场景

为提升多人会议的音频体验，该版本在 setAudioProfile 中新增 MEETING(8)。

2. 美声与音效

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

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

3. 互动直播延时

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

4. 本地采集视频画质 （仅 iOS）

为提升本地采集的视频画质，该版本对摄像头采集本地视频进行如下优化：

• 优化后置摄像头自动对焦功能。
• 改善强光场景下图像局部过曝问题，该改善仅对分辨率不低于 960 × 540 的视频有效。

问题修复

该版本修复了如下问题：

Android 平台

• 该版本修复了用户使用小米音箱进行通话时偶现的录音问题。
• 修复了发送端使用 vivo X30 时，接收端出现黑屏的问题。
• 修复了发送端使用 Android TV 频繁进、出频道时，接收端偶现黑屏的问题。
• IPv6 场景下的高概率崩溃问题。
• 调用 enableEncryption 后，firstLocalVideoFramePublished 回调无法被触发。
• Native 音频 SDK 的客户端与 Web 客户端互通时，Web 客户端持续报告 Client.on(disable-local-video) 或 Client.on(mute-video) 回调。

iOS 平台

• iPhone 5s 和 iPhone 6 开启基础美颜且用户切换前、后台时，画面出现闪烁的问题。
• stopChannelMediaRelay 不生效的问题。
• 特定场景下 SDK 错误地返回了 AdmStartRecording(1012) 错误码的问题。
• IPv6 场景下的高概率崩溃问题。
• 调用 enableEncryption 后，firstLocalVideoFramePublished 回调无法被触发。
• Native 音频 SDK 的客户端与 Web 客户端互通时，Web 客户端持续报告 Client.on(disable-local-video) 或 Client.on(mute-video) 回调。

API 变更

新增

• setClientRole 中新增 options
• setAudioEffectPreset
• setVoiceBeautifierPreset
• setAudioEffectParameters
• AudioScenario enum 中新增 MEETING(8)

废弃

• setLocalVoiceChanger
• setLocalVoiceReverbPreset

3.1.2 版

该版本于 2020 年 9 月 30 日发布。功能特性及相关文档详见下文。

功能特性

1. 全面适配 Agora RTC SDK v3.1.2。
2. 支持多频道管理。
3. 全面支持异步编程 （async/await）。
4. Android 平台支持 TextureView 渲染。
5. 支持发布和订阅状态转换回调、本地首帧发布回调。

相关文档

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

• 快速开始：
  • 实现语音通话
  • 实现视频通话
  • 实现视频互动直播
  • 实现音频互动直播
• API 参考

Agora 在 GitHub 提供一个开源的 Agora Flutter Quickstart 示例项目。你也可以前往下载并体验。