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

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 示例项目。你也可以前往下载并体验。