声网 SDK v4.0.0 是一个新的 SDK 版本,可帮助用户将实时音视频功能集成到 app 中。在大规模的实时互动场景下,你可以用它实现更好的实时互动效果,详见产品概述。
本文介绍如何将 SDK 从 v3.x(指 v3.7.0.3 以及之前版本)升级至 v4.0.0。
本节介绍将 SDK 从 v3.x 升级至 v4.0.0 的主要步骤。
在 v4.0.0 中,当你成功下载声网 Unity SDK 后可以看到一个 .unitypackage
的资源包,你可以直接在 Unity 编辑器中将其导入至你的项目中。成功导入后,你项目的 Assets
路径下会出现 Agora-RTC-Plugin
目录。
参考创建项目,将 v4.0.0 SDK 集成到你的项目中。
v4.0.0 SDK 对部分功能的实现方式进行了优化或修改,从而导致与 v3.x 不兼容。为了继续使用 app 中已有的声网功能,请根据变更介绍更新 app 中的代码。
本节以 v3.x 为基础,按如下分类介绍 v4.0.0 相对于 v3.x 的主要变更,你需要结合实际业务场景更新 app 代码:
从 v3.x 升级至 v4.0.0 后,实现部分功能的 API 存在差异。本节介绍这些 API 的兼容性变更及 app 代码的更新逻辑。
在 v3.x 中,SDK 提供 AgoraChannel
类和 Channel
相关 delegate
实现多频道控制,支持订阅多个频道的音视频流,但只能选择一个频道发布一组音视频流。
在 v4.0.0 中:
IRtcEngineEx
类实现多频道功能:调用 JoinChannel
加入首个频道后,多次调用 JoinChannelEx
加入多个频道,通过不同的用户 ID(localUid
)和 ChannelMediaOptions
设置发布指定的流到不同的频道。RtcConnection
二元组表示 JoinChannel
建立的连接,一个连接由频道名(channelId
)和 localUid
确定。你可以通过 RtcConnection
控制不同连接的发布和订阅。所有带 connection
参数(对应 RtcConnection
类)的 API 命名中都增加了 Ex 以区分,并统一放在 IRtcEngineEx
类中,用于多流的扩展。通过设置 ChannelMediaOptions
,v4.0.0 支持一个 IRtcEngine
实例同时采集多路音视频源并发布到远端,适应各种业务场景。例如:
结合多频道能力,你还可以体验如下功能:
localUid
发布到远端localUid
发布到远端localUid
发布到远端v3.x 的 AgoraChannel
和 IRtcEngine
在功能上有部分重复、不够正交,因此在 v4.0.0 中隐藏了 AgoraChannel
类和 Channel
相关 delegate
。你可以参考示例项目,用 JoinChannel
和 ChannelMediaOptions
替代 AgoraChannel
,预计迁移成本在一天以内。如果你需要继续使用 AgoraChannel
和 Channel
相关 delegate
,请提交工单联系技术支持,声网会根据反馈情况决定是否在后续版本中保持兼容。
在 v4.0.0 中,将更多频道相关的设置都汇聚进了 ChannelMediaOptions
,包括不同音视频流的发布、自动订阅、用户角色切换、Token 更新、默认大小流选项等。你可以在加入频道时通过 JoinChannel
或 JoinChannelEx
明确媒体流发布和订阅行为,也可以在加入频道后通过 UpdateChannelMediaOptions
动态更新频道中的媒体选项,例如切换视频源。
在 v3.x 中,SDK 通过 OnWarning
回调报告警告码。
为方便用户定位和排查问题,v4.0.0 通过 API 返回值或不同状态回调来报告问题和原因。例如:
OnConnectionStateChanged
:报告网络连接状态。OnLocalAudioStateChanged
:报告本地音频状态。OnLocalVideoStateChanged
:报告本地视频状态。OnRemoteAudioStateChanged
:报告远端音频状态。OnRemoteVideoStateChanged
:报告远端视频状态。因此,v4.0.0 删除了 OnWarning
回调。
ChannelMediaOptions
中的 publishAudioTrack
替换为 publishMicrophoneTrack
。
如果你在 v4.0.0 Beta 版本中使用了该功能、并且希望升级到 v4.0.0 版本,请在升级 SDK 后修改功能的实现。
本节介绍由 v4.0.0 对 SDK 默认行为和 API 行为的合理优化造成的变更。
在 v3.x 中,你可以使用 GetEngine (appId)
或 GetEngine(engineConfig)
方法获取 IRtcEngine
实例并初始化引擎。
在 v4.0.0 中,你可以使用 CreateAgoraRtcEngine
或 RtcEngine.Instance
方法来实例化 IRtcEngine
,然后通过 Initialize
方法来初始化引擎,在初始化的同时你还可以通过 RtcEngineContext
来设置频道场景、音频应用场景、进行日志文件配置等。
在 v3.x 中,你可以使用 C# delegate
注册的形式来注册回调事件。
在 v4.0.0 中,你依然可以使用 C# delegate
注册的形式来注册回调事件,delegate
被封装在 Agora.Rtc.RtcEngineEventHandler
中。除此之外,你还可以通过 InitEventHandler
来注册回调事件,你需要继承声网提供的事件基类并实现自己的 EventHandler
类,通过 InitEventHandler
方法将自己的 EventHandler
类实例注册给 SDK。
如果你需要释放声网 Unity SDK 使用的所有资源:
在 v3.x 中,你需要调用 Destroy
方法来释放资源。
在 v4.0.0 中,你需要调用 Dispose
方法来释放资源。
在 v3.x 中,默认的频道场景为 CHANNEL_PROFILE_COMMUNICATION
(通信)。因为直播场景支持从一对一通话无缝切换到多人互动,所以声网自 v3.0.0 起将通信场景下内部的传输协议和弱网对抗能力改成与直播场景一致。
在 v4.0.0 中,声网也将默认的频道场景改成了 CHANNEL_PROFILE_LIVE_BROADCASTING
(直播)。
在 v3.x 中,如果OnNetworkQuality
中的 uid
为 0,则该回调返回的是本地用户的网络质量。
在 v4.0.0 中,该回调返回的本地用户 uid
和用户在频道内实际的 uid
相同。
在 v3.x 中,有多个日志文件时,旧的文件会以 agorasdk_x.log
格式命名,例如 agorasdk_1.log
。
在 v4.0.0 中, 修改命名格式为 agorasdk.x.log
(例如 agorasdk.1.log
)。此外,v4.0.0 新增了 agoraapi.log
、agora_iris.log
记录 API 调用的日志。
在 v3.x 中,你需要调用 SwitchChannel
实现快速切换频道。
在 v4.0.0 中,通过 LeaveChannel
和 JoinChannel
切换频道即可实现和 SwitchChannel
一样的切换速度,因此该版本删除了 SwitchChannel
。如果你在 v3.x 中使用 SwitchChannel
切换频道,你需要在 v4.0.0 中先调用 LeaveChannel
离开当前频道,再调用JoinChannel
加入第二个频道。
v4.0.0 在 v4.0.0 Beta 的基础上新增了自动加载自研动态库功能。自该版本起,当你使用声网自研的插件时,不需要在项目中手动集成动态库,SDK 会在 IRtcEngine
初始化阶段自动加载动态库。你可以直接调用插件对应的方法即可开启该功能。
API | 插件类型 |
---|---|
EnableVirtualBackground |
虚拟背景插件 |
SetBeautyEffectOptions SetVideoDenoiserOptions SetLowlightEnhanceOptions SetColorEnhanceOptions |
视频增强插件 |
EnableRemoteSuperResolution |
超分辨率插件 |
SetAudioEffectPreset SetVoiceBeautifierPreset SetVoiceConversionPreset |
美声插件 |
EnableSpatialAudio |
空间音效插件 |
EnableContentInspect |
内容审核插件 |
当你调用 EnableAudioVolumeIndication
方法并将 interval
参数设置为 >0 时,可启用用户音量提示。在 v3.x 和 v4.0.0 中,interval
参数的定义存在差异:
OnAudioVolumeIndication
回调。当启用音量提示回调后,SDK 会上报 OnAudioVolumeIndication
回调,如果本地用户将自己静音(调用了 MuteLocalAudioStream
),在 v3.x 和 v4.0.0 中,SDK 的行为不一致:
OnLocalAudioStateChanged
中的 LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION
上报没有权限启动音频采集设备;通过 OnLocalVideoStateChanged
中的 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION
上报没有权限启动视频采集设备。在 v4.0.0 中,统一通过 OnPermissionError
回调上报音视频采集设备的权限状态。
如果你需要开启或停止网络连接质量测试:
在 v3.x 中,你可以调用 EnableLastmileTest
开启网络质量测试,如果你想停止网络测试,需要调用 DisableLastmileTest
。
在 v4.0.0 中,你可以调用 StartLastmileProbeTest
启用网络质量测试,如果你想停止网络测试,需要调用 StopLastmileProbeTest
。
在 v3.x 中,你可以通过 VideoRawDataManager
、AudioRawDataManager
类下的 API 来管理原始音视频数据。
在 v4.0.0 中,你可以调用 IRtcEngine
类中的 RegisterAudioFrameObserver
或 RegisterVideoFrameObserver
注册语音或视频观测器后,直接使用该类实现原始音视频数据观测;或者通过继承该类,自行实现原始音视频数据观测。
假设存在以下两种场景:
MuteLocalAudioStream
或 MuteLocalVideoStream
改变本地音视频流的发布状态、然后加入频道。MuteLocalAudioStream
或 MuteLocalVideoStream
改变本地音视频流的发布状态,然后其他用户加入频道。v3.7.0 和 v4.0.0 SDK 中存在以下行为差异:
OnRemoteAudioStateChanged
或 OnRemoteVideoStateChanged
回调,报告远端主播的音视频流的状态变化。OnRemoteAudioStateChanged
或 OnRemoteVideoStateChanged
回调,但是会收到 OnUserMuteAudio
或 OnUserMuteVideo
回调,报告远端主播的发流状态变化(即是否正在发布音视频流)。本节介绍在 v3.x 中支持、但在 v4.0.0 中不支持或行为不一致的功能,这些功能会在后续版本中支持或改为一致。
v4.0.0 重构了音频应用场景,可以替代大部分 v3.x 的音频应用场景。下表展示了两个版本中音频应用场景的对应关系:
v3.x | v4.0.0 |
---|---|
AUDIO_SCENARIO_DEFAULT |
AUDIO_SCENARIO_DEFAULT |
AUDIO_SCENARIO_CHATROOM_ENTERTAINMENT |
AUDIO_SCENARIO_CHATROOM |
AUDIO_SCENARIO_EDUCATION |
AUDIO_SCENARIO_DEFAULT |
AUDIO_SCENARIO_GAME_STREAMING |
AUDIO_SCENARIO_GAME_STREAMING |
AUDIO_SCENARIO_SHOWROOM |
AUDIO_SCENARIO_DEFAULT |
AUDIO_SCENARIO_CHATROOM_GAMING |
AUDIO_SCENARIO_CHATROOM |
AUDIO_SCENARIO_IOT |
AUDIO_SCENARIO_DEFAULT |
AUDIO_SCENARIO_MEETING |
AUDIO_SCENARIO_MEETING |
相比于 v3.x,某些功能在 v4.0.0 中不支持或仅支持部分。本节展示尚未支持的 API,这些 API 会在后续版本中支持。
远端视频流回退:
SetRemoteUserPriority
屏幕共享:
OnScreenCaptureInfoUpdated
v4.0.0 中,删除了已废弃或不推荐使用的 类和 API。已删除 API 的替代方案或删除原因展示如下:
VideoRawDataManager
:使用 IVideoFrameObserver
类下的相关 API 替代。
AudioRawDataManager
:使用 IAudioFrameObserver
类下的相关 API 替代。
PacketObserver
:在 v3.x 中很少使用。
EnableFilpTextureApply
:推荐自行实现。
SetGameFps
:推荐自行实现。
VirtualBackgroundSourceEnabled
:使用 EnableVirtualBackground
的返回值替代。
OnUserSuperResolutionEnabled
:使用 OnRemoteVideoStats
回调的 superResolutionType
成员替代。
SetExternalAudioSourceVolume
: 使用 AdjustCustomAudioPublishVolume
替代。
GetAudioFileInfo
和 OnRequestAudioFileInfo
:使用 GetDuration
替代。
OnAudioDeviceTestVolumeIndication
:由 OnAudioVolumeIndication
替代。
SetLocalPublishFallbackOption
和 OnLocalPublishFallbackToAudioOnly
:在 v3.x 中很少使用。
RENDER_MODE_TYPE
中的 RENDER_MODE_FILL(4)
:该模式可能造成图片过度拉伸,不推荐使用。
AUDIO_MIXING_REASON_TYPE
中的以下枚举:在 v3.x 中应用场景很少。
AUDIO_MIXING_REASON_STARTED_BY_USER
AUDIO_MIXING_REASON_START_NEW_LOOP
AUDIO_MIXING_REASON_PAUSED_BY_USER
AUDIO_MIXING_REASON_RESUMED_BY_USER
OnAudioMixingFinished
: 使用 OnAudioMixingStateChanged
替代。
EnableDeepLearningDenoise
:AI 降噪将在后续版本改由 SDK 控制,不通过 API 实现。
TakeSnapshot
和 OnSnapshotTaken
中的 channel
参数:冗余参数。
SetDefaultMuteAllRemoteVideoStreams:
由 ChannelMediaOptions
中的 autoSubscribeVideo
替代。
SetDefaultMuteAllRemoteAudioStreams
:由 ChannelMediaOptions
中的 autoSubscribeAudio
替代。
LOCAL_VIDEO_STREAM_ERROR
中的 LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_NOT_SUPPORTED
:该枚举在 v3.x 已废弃。
StartAudioMixing
中的 replace
参数:由 ChannelMediaOptions
中的 publishMicrophoneTrack
替代。
v4.0.0 的命名和数据类型变更会在你编译项目时引入 IDE 的报错提示,你需要根据提示更新 app 代码。
相较于 v3.x,v4.0.0 中主要的命名变更如下:
namespace agora_gaming_rtc
变更为 namespace Agora.Rtc
AudioPlaybackDeviceManager
和 AudioRecorderDeviceManager
合并为 IAudioDeviceManager
VideoDeviceManager
变更为 IVideoDeviceManager
MediaRecorder
变更为 IMediaRecorder
MetadataObserver
变更为 IMetadataObserver
AgoraCallback
变更为 IRtcEngineEventHandler
AdjustLoopbackRecordingSignalVolume
变更为 AdjustLoopbackSignalVolume
OnFirstLocalAudioFrame
变更为 OnFirstLocalAudioFramePublished
LogConfig
中的 fileSize
成员变更为 fileSizeInKB
JoinChannel
[2/2] 中的 options
参数变更为 mediaOptions
EnableAudioVolumeIndication
中的 report_vad
参数变更为 reportVad