声网 SDK v4.x 是一个新的 SDK 版本,可帮助用户将实时音视频功能集成到 app 中。在大规模的实时互动场景下,你可以用它实现更好的实时互动效果,详见产品概述。
本文介绍将 SDK 从 v3.x(指 v3.7.0 以及之前版本)或 v2.x 升级至 v4.0.0 的主要步骤及变更。
参考建立项目,将 v4.x SDK 集成到你的项目中。
成功集成 SDK 后,你还需要在项目的 /app/java/com.example.<projectname>/MainActivity
文件中导入类的代码由 io.agora.rtc
前缀修改为 io.agora.rtc2
前缀。
AgoraRtcChannelMediaOtions.java
文件路径也由 /models
变更为根目录下。v4.x SDK 对部分功能的实现方式进行了优化或修改,从而导致与 v3.x 或 v2.x 不兼容。为了继续使用 app 中已有的声网功能,请根据变更介绍更新 app 中的代码。
本节按如下分类介绍 v4.0.0 相比 v3.7.0 的主要变更,你需要结合实际业务场景更新 app 代码:
从 v3.7.0 升级至 v4.0.0 后,实现部分功能的 API 存在差异。本节介绍这些 API 的兼容性变更及 app 代码的更新逻辑。
在 v3.7.0 中,SDK 提供 RtcChannel
类和 IRtcChannelEventHandler
类实现多频道控制,支持订阅多个频道的音视频流,但只能选择一个频道发布一组音视频流。
在 v4.0.0 中:
SDK 提供 RtcEngineEx
类实现多频道功能,结合多频道能力实现一个 RtcEngine
实例同时采集多组音视频流并发布到远端,适应各种业务场景。
调用 joinChannel
加入首个频道后,多次调用 joinChannelEx
加入多个频道,通过不同的用户 ID(localUid
)和 ChannelMediaOptions
设置发布指定的流到不同的频道。
新增了 RtcConnection
二元组表示 joinChannel
建立的连接,一个连接由频道名(channelId
)和 localUid
确定。你可以通过 RtcConnection
控制不同连接的发布和订阅。所有带 connection
参数(对应 RtcConnection
类)的 API 命名中都增加了 Ex 以区分,并统一放在 RtcEngineEx
类中,用于多流的扩展。
通过设置 ChannelMediaOptions
,v4.0.0 支持一个 RtcEngine
实例同时采集多路音视频源并发布到远端,适应各种业务场景。例如:
结合多频道能力,你还可以体验如下功能:
localUid
发布到远端localUid
发布到远端localUid
发布到远端v3.7.0 的 RtcChannel
和 RtcEngine
在功能上有部分重复、不够正交,因此在 v4.0.0 中隐藏了 RtcChannel
类和 IRtcChannelEventHandler
类。你可以参考 JoinMultiChannel 示例项目,用 joinChannel
和 ChannelMediaOptions
替代 RtcChannel
,预计迁移成本在一天以内。如果你需要继续使用 RtcChannel
和 IRtcChannelEventHandler
类,请联系技术支持,声网会根据反馈情况决定是否在后续版本中保持兼容。
在 v4.0.0 中,将更多频道相关的设置都汇聚进了 ChannelMediaOptions
,包括不同音视频流的发布、自动订阅、用户角色切换、Token 更新、默认大小流选项等。你可以在加入频道时通过 joinChannel
或 joinChannelEx
明确媒体流发布和订阅行为,也可以在加入频道后通过 updateChannelMediaOptions
动态更新频道中的媒体选项,例如切换视频源。
你可以参考 LiveBroadcasting 示例项目更新 app 代码。
在 v3.7.0 中,SDK 提供如下方式实现自定义采集与渲染:
IVideoSource
)自采集IVideoSink
)自渲染v4.0.0 内部统一了音视频处理管线,推荐使用集成最简单的 Push 方式自采集、原始视频数据方式自渲染,因此删除了 MediaIO 方式的相关 API:
IVideoSource
IVideoSink
IVideoFrameConsumer
setVideoSource
setLocalVideoRenderer
setRemoteVideoRenderer
如果你在 v3.7.0 使用了 MediaIO 方式实现视频自采集、视频自渲染、切换视频源等功能,声网推荐参考如下示例项目更新 app 代码:
在 v3.7.0 中,SDK 通过 onWarning
回调报告警告码。
为方便用户定位和排查问题,v4.0.0 通过 API 返回值或不同状态回调来报告问题和原因。例如:
getConnectionState
:报告网络连接状态。onLocalAudioStateChanged
:报告本地音频状态。onLocalVideoStateChanged
:报告本地视频状态。onRemoteAudioStateChanged
:报告远端音频状态。onRemoteVideoStateChanged
:报告远端视频状态。因此,v4.0.0 删除了 onWarning
回调。
ChannelMediaOptions
中的 publishAudioTrack
替换为 publishMicrophoneTrack
。ChannelMediaOptions
中的 publishScreenTrack
替换为 publishScreenCaptureVideo
。如果你在 v4.0.0 Beta 版本中使用了该功能、并且希望升级到 v4.0.0 版本,请在升级 SDK 后修改功能的实现。
本节介绍由 v4.0.0 对 SDK 默认行为和 API 行为的合理优化造成的变更。
在 v3.7.0 中,默认的频道场景为 CHANNEL_PROFILE_COMMUNICATION
(通信)。
因为直播场景支持从一对一通话无缝切换到多人互动,所以声网自 v3.0.0 起将通信场景下内部的传输协议和弱网对抗能力改成与直播场景一致。在 v4.0.0 中,声网也将默认的频道场景改成了 CHANNEL_PROFILE_LIVE_BROADCASTING
(直播)。
在 v3.7.0 中,如果 onNetworkQuality
中的 uid
为 0,则该回调返回的是本地用户的网络质量。 在 v4.0.0 中,该回调返回的本地用户 uid
和用户在频道内实际的 uid
相同。
在 v3.7.0 中,有多个日志文件时,旧的文件会以 agorasdk_x.log 格式命名,例如 agorasdk_1.log。v4.0.0 修改命名格式为 agorasdk.x.log(例如 agorasdk.1.log)。此外,v4.0.0 新增了 agoraapi.log 记录 API 调用的日志。
在 v3.7.0 中,你需要调用 switchChannel
实现快速切换频道。
在 v4.0.0 中,通过 leaveChannel
和 joinChannel
切换频道即可实现和 switchChannel
一样的切换速度,因此该版本删除了 switchChannel
。如果你在 v3.7.0 中使用 switchChannel
切换频道,你需要在 v4.0.0 中先调用 leaveChannel
离开当前频道,再调用 joinChannel
加入第二个频道。
v4.0.0 在 v4.0.0 Beta 的基础上新增了自动加载自研动态库功能。自该版本起,当你使用声网自研的插件时,不需要在项目中手动集成动态库,SDK 会在 RtcEngine
初始化阶段自动加载动态库。你可以直接调用插件对应的方法即可开启该功能。
API | 插件类型 |
---|---|
enableVirtualBackground |
虚拟背景插件 |
setBeautyEffectOption setVideoDenoiserOptions setLowlightEnhanceOptions setColorEnhanceOptions |
视频增强插件 |
enableRemoteSuperResolution |
超分辨率插件 |
setAudioEffectPreset setVoiceBeautifierPreset setVoiceConversionPreset |
美声插件 |
enableSpatialAudio |
空间音效插件 |
enableContentInspect |
内容审核插件 |
当你调用 startRhythmPlayer
时,SDK 默认将虚拟节拍器的声音发布到远端,如果你不希望远端用户听到虚拟节拍器,需参考以下操作:
configRhythmPlayer
并将 publish
设置为 false
。ChannelMediaOptions
中的 publishRhythmPlayerTrack
设置为 false
。当你调用 enableAudioVolumeIndication
方法并将 interval
参数设置为 >0 时,可启用用户音量提示。在 v3.7.0 和 v4.0.0 中,interval
参数的定义存在差异:
onAudioVolumeIndication
回调。当启用音量提示回调后,SDK 会上报 onAudioVolumeIndication
回调,如果本地用户将自己静音(调用了 muteLocalAudioStream
),在 v3.7.0 和 v4.0.0 中,SDK 的行为不一致:
在 v3.7.0 中,通过 onLocalAudioStateChanged
中的 LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION
上报没有权限启动音频采集设备;通过 onLocalVideoStateChanged
中的 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION
上报没有权限启动视频采集设备。
在 v4.0.0 中,统一通过 onPermissionError
回调上报音视频采集设备的权限状态。
如果你需要开启或停止网络连接质量测试:
在 v3.7.0 中,你可以调用 enableLastmileTest
开启网络质量测试,如果你想停止网络测试,需要调用 disableLastmileTest
。
在 v4.0.0 中,你可以调用 startLastmileProbeTest
启用网络质量测试,如果你想停止网络测试,需要调用 stopLastmileProbeTest
。
假设存在以下两种场景:
muteLocalAudioStream
或 muteLocalVideoStream
改变本地音视频流的发布状态、然后加入频道。muteLocalAudioStream
或 muteLocalVideoStream
改变本地音视频流的发布状态,然后其他用户加入频道。v3.7.0 和 v4.0.0 SDK 中存在以下行为差异:
onRemoteAudioStateChanged
或 onRemoteVideoStateChanged
回调,报告远端主播的音视频流的状态变化。onRemoteAudioStateChanged
或 onRemoteVideoStateChanged
回调,但是会收到 onUserMuteAudio
或 onUserMuteVideo
回调,报告远端主播的发流状态变化(即是否正在发布音视频流)。本节介绍在 v3.7.0 中支持、但在 v4.0.0 中不支持或行为不一致的功能,这些功能会在后续版本中支持或改为一致。
v4.0.0 重构了音频应用场景,可以替代大部分 v3.7.0 的音频应用场景。下表展示了两个版本中音频应用场景的对应关系:
v3.7.0 | 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.7.0,某些功能在 v4.0.0 中不支持或仅支持部分。本节展示尚未支持的 API,这些 API 会在后续版本中支持。
远端视频流回退:
setRemoteUserPriority
屏幕共享:
onScreenCaptureInfoUpdated
v4.0.0 中,删除了已废弃或不推荐使用的 API。已删除 API 的替代方案或删除原因展示如下:
virtualBackgroundSourceEnabled
:使用 enableVirtualBackground
的返回值替代。onUserSuperResolutionEnabled
:使用 remoteVideoStats
回调的 superResolutionType
成员替代。setAudioMixingPlaybackSpeed
:使用 IMediaPlayer
(AgoraRtcMediaPlayerProtocol
)类下的相关 API 替代。setExternalAudioSourceVolume
:使用 adjustCustomAudioPublishVolume
替代。getAudioFileInfo
和 onRequestAudioFileInfo
:使用 getDuration
替代。onAudioDeviceTestVolumeIndication
:由 onAudioVolumeIndication
替代。setLocalPublishFallbackOption
和 onLocalPublishFallbackToAudioOnly
:在 v3.7.0 中很少使用。RENDER_MODE_TYPE
中的 RENDER_MODE_FILL(4)
:该模式可能造成图片过度拉伸,不推荐使用。AUDIO_MIXING_REASON_TYPE
中的以下枚举:在 v3.7.0 中应用场景很少。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
替代。startAudioMixing
中的 replace
参数:由 ChannelMediaOptions
中的 publishMicrophoneTrack
替代。v4.0.0 的命名和数据类型变更会在你编译项目时引入 IDE 的报错提示,你需要根据提示更新 app 代码。
主要的 API 及参数名变更如下:
onFirstLocalAudioFrame
变更为 onFirstLocalAudioFramePublished
。LogConfig
中的 fileSize
成员变更为 fileSizeInKB
。joinChannel
[2/2] 中的 options
参数变更为 mediaOptions
。enableAudioVolumeIndication
中的 report_vad
参数变更为 reportVad
。