Migrate from Voice SDK 3.x
-
Migration steps to upgrade your app to Voice Calling v4.x.
-
What's changed between Voice Calling v2.x and v4.x.
Migration steps
This section introduces the main steps to upgrade the SDK from v2.x or v3.7.x to v4.x.
-
Integrate the SDK
See Get started for more information about integrating the v4.x SDK into your project.
-
Rename imported classes
After successfully integrating the SDK, you need to update the codes of imported classes from the
io.agora.rtc
prefix to theio.agora.rtc2
prefix in the/app/java/com.example.<projectname>/MainActivity
file of your project.NoticeThe file path of
ChannelMediaOtions.java
in the 4.x SDK is also changed from/models
to the root directory. -
Update the Agora code in your app
The 4.x SDK has optimized or modified the implementation of some functions, resulting in incompatibility with the v3.7.x SDK. In order to retain Agora functionality in your app, update the code in your app according to What has changed.
What has changed
This section introduces the main changes of 4.x compared to v3.7.x in the following categories. You need to update the code of your app according to your business scenario.
-
Breaking changes: Introduces API compatibility changes that have a big impact. You need to spend significant time modifying the related implementation.
-
Behavior changes: Introduces changes caused by reasonable optimization of the SDK default behavior and API behavior. Less time is required to modify the related implementation, if any.
-
Function gaps: Introduces functions that were supported in v3.7.x but are not supported in 4.x. However, these functions are intended to be added in a future release.
-
Removed APIs: Introduces APIs that were supported in v3.7.x but removed in 4.x. Most of these APIs have alternatives in 4.x. Modifying the related implementation should require less time.
-
Naming and data type changes: Introduces the naming and data type changes of the main APIs. You can update the relevant implementation according to the error message in the IDE, which is expected to take less time.
Breaking changes
After upgrading from v3.7.x to 4.x, the way the APIs implement some functions is different. This section introduces compatibility changes for these APIs and the logic for updating the code of your app.
Multiple channels
In v3.7.x, the SDK provides the RtcChannel
and IRtcChannelEventHandler
classes to implement multi-channel control. The v3.7.x SDK supports subscribing to the audio and video streams of multiple channels, but only supports publishing one group of audio and video streams in one channel.
4.x introduces the following changes:
-
The SDK supports capturing or publishing multiple groups of audio and video streams at the same time. For example, simultaneously publishing video streams captured by multiple cameras or multiple screens.
-
The SDK retains the following behavior of
RtcEngine
: you can calljoinChannel
(replacingjoinChannel
of theRtcChannel
class in v3.7.x) multiple times, and publish the specified stream to different channels through different user IDs (localUid
) andChannelMediaOptions
settings. -
Added a binary group
RtcConnection
to represent the connection established byjoinChannel
. A connection is determined by the channel name (channelId
) andlocalUid
. You can control the publishing and subscribing state of different connections throughRtcConnection
. The SDK adds Ex in the name of all APIs with aconnection
parameter (corresponding to theRtcConnection
class) to distinguish them, and gathers these APIs in theIRtcEngineEx
class to implement more multi-stream functions.
By setting ChannelMediaOptions
, 4.x supports using one RtcEngine
instance to capture audio and video streams from multiple sources at the same time and publish them to the remote user, adapting to various business scenarios. For example:
-
Simultaneously publish a media player stream, a screen-sharing stream, and a video stream captured by the front and rear cameras.
-
Simultaneously publish one audio stream captured by the microphone and one by the custom audio source, and one media player steam.
Combined with the multi-channel capability, you can also experience the following functions:
-
Publish multiple groups of audio and video streams to the remote user through different
localUids
. -
Mix multiple audio streams and publish them to the remote user through one
localUid
. -
Mix multiple video streams and publish them to the remote user through one
localUid
.RtcChannel
andRtcEngine
of v3.7.x are partially duplicated and overlap in their functionality, so 4.x hides theRtcChannel
andIRtcChannelEventHandler
classes. See the JoinMultiChannel sample project for more details on how to replaceRtcChannel
withjoinChannel
andChannelMediaOptions
. The expected migration cost is one day or less.
If you need to continue to use the RtcChannel
and IRtcChannelEventHandler
classes, contact support@agora.io. The decision whether to maintain compatibility in a future release is based on your feedback.
Media stream publishing control
In v3.7.x, the SDK uses the publishLocalAudio
and publishLocalVideo
members in ChannelMediaOptions
to control the audio and video publishing state in the channel.
In 4.x, the SDK gathers more channel-related settings into ChannelMediaOptions
, including publishing of audio and video streams from different sources, automatic subscribing of audio and video streams, user role switching, token updating, and default dual stream options. You can determine the media stream publishing and subscribing behavior by calling joinChannel
or joinChannelEx
when joining a channel, or you can flexibly update the media options by calling updateChannelMediaOptions
after joining a channel, such as switching video sources.
See the JoinChannelVideo sample project to update the code in your app.
Custom video source and renderer
In v3.7.x, the SDK provides the following ways to implement the custom video source and renderer:
-
Push mode for custom video source
-
Raw video data mode for custom video renderer
-
MediaIO mode (
IVideoSource
) for custom video source -
MediaIO mode (
IVideoSink
) for custom video renderer
4.x unifies the audio and video processing pipeline internally. Push mode and raw video data mode are simpler for integration, so Agora recommends using them for custom video source and renderer and removes the following related APIs of the MediaIO mode:
-
IVideoSource
-
IVideoSink
-
IVideoFrameConsumer
-
setVideoSource
-
setLocalVideoRenderer
-
setRemoteVideoRenderer
If you use the MediaIO mode in v3.7.x to implement custom video source, custom video renderer, switching video source, and other functions, Agora recommends updating the code of your app by referring to the following sample projects:
-
Custom video source: CustomVideoSourcePush
-
Custom video renderer: CustomVideoRender
-
Switching video source: ScreenShare
Error codes and warning codes
In v3.7.x, the SDK returns error codes and warning codes through the onError
and onWarning
callbacks.
To facilitate locating and troubleshooting issues, 4.x reports problems and causes through the return values of APIs or different callbacks for listening to states. For example:
-
getConnectionState
: Reports the network connection state. -
onLocalAudioStateChanged
: Reports the local audio state. -
onLocalVideoStateChanged
: Reports the local video state. -
onRemoteAudioStateChanged
: Reports the remote audio state. -
onRemoteVideoStateChanged
: Reports the remote video state.
As a consequence, 4.x removes the onError
and onWarning
callbacks.
Behavior changes
This section introduces changes caused by reasonable optimization of the SDK default behavior and API behavior.
Channel profile
In v3.7.x, the default channel profile is CHANNEL_PROFILE_COMMUNICATION
(the communication profile).
Because the interactive streaming profile supports seamless switching from one-to-one calls to multi-user interaction, since v3.0.0, Agora has changed the internal transmission protocol and the ability to resist poor network conditions in the communication profile to be consistent with the interactive streaming profile. In 4.x, Agora also changed the default channel profile to CHANNEL_PROFILE_LIVE_BROADCASTING
(the interactive streaming profile).
Default log file
In v3.7.x, when the SDK creates multiple log files, the earlier files are named in a agorasdk_x.log format, such as agorasdk_1.log. 4.x modified the naming format to agorasdk.x.log, such as agorasdk.1.log. Additionally, 4.x adds the agoraapi.log file to record API logs.
Fast channel switching
In v3.7.x, you need to call switchChannel
to quickly switch a channel.
In 4.x, you can achieve the same switching speed as switchChannel
in v3.7.x by switching a channel through leaveChannel
and joinChannel
. Therefore, 4.x removes switchChannel
. If you call switchChannel
to quickly switch a channel in v3.7.x, see the VideoQuickSwitch sample project to update the code in your app.
Agora self-developed extensions
v4.0.0 adds the feature of automatically loading self-developed dynamic libraries based on v4.0.0 Beta. As of this release, when using an Agora self-developed extension, you do not need to manually integrate the dynamic library in the project. The SDK automatically loads the dynamic library during the initialization phase of RtcEngine
. You can directly call the corresponding method of the extension to enable this feature.
API | Extension type |
---|---|
enableVirtualBackground | Virtual background extension |
setBeautyEffectOptions setVideoDenoiserOptions setLowlightEnhanceOptions setColorEnhanceOptions | Video enhancement extension |
enableRemoteSuperResolution | Super resolution extension |
setAudioEffectPreset setVoiceBeautifierPreset setVoiceConversionPreset | Voice beautifier extension |
enableSpatialAudio | Spatial audio extension |
enableContentInspect | Content moderation extension |
Virtual metronome
When you call startRhythmPlayer
, the SDK publishes the sound of the virtual metronome to the remote by default. If you do not want the remote users to hear the virtual metronome, refer to the following operations:
- In v3.7.0, call the
configRhythmPlayer,
and setpublish
tofalse
. - In v4.0.0, set
publishRhythmPlayerTrack
inChannelMediaOptions
tofalse
.
Volume indication
You can call the enableAudioVolumeIndication
method to enable the user's volume indication function. There is a difference in the definition of the interval
parameter in the enableAudioVolumeIndication
method between v3.7.0 and v4.0.0, as follows:
- In v3.7.0, Agora recommends that you set the
interval
to be greater than 200 ms. The minimum is 10 ms; otherwise, theonAudioVolumeIndication
callback is not received. - In v4.0.0, you must set the
interval
to an integer that is a multiple of 200 ms. If the value ofinterval
is lower than 200, the SDK automatically adjusts it to 200.
When the user's volume indication is enabled, the SDK triggers the onAudioVolumeIndication
callback at the time interval set in this method. If the local user calls muteLocalAudioStream
to mute themselves, the SDK behaves inconsistently between v3.7.0 and v4.0.0:
- In v3.7.0, the SDK immediately stops reporting the local user's volume indication callback.
- In v4.0.0, the SDK continues to report the local user's volume indication callback.
Device permissions
-
In v3.7.0,
LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION
inonLocalAudioStateChanged
reports that there is no permission to start the capture device, andLOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION
inonLocalVideoStateChanged
reports that there is no permission to start the video capture device. -
In v4.0.0, the permission statuses of the audio and video capture devices are both reported in the
onPermissionError
callback.
Pre-call network test
If you need to start or stop the network connection quality test, note the following:
-
In v3.7.0, you can call
enableLastmileTest
to start the network quality test. If you want to stop the network test, you need to calldisableLastmileTest
. -
In v4.0.0, you can call
startLastmileProbeTest
to enable network quality testing. If you want to stop network testing, you need to callstopLastmileProbeTest
.
Remote media event triggering mechanism
In the following scenarios, the mechanism of triggering remote media events is changed:
- Scenario 1: When the host calls
muteLocalAudioStream
ormuteLocalVideoStream
outside the channel to change the publishing status of the local audio or video stream and then joins the channel. - Scenario 2: When the host calls
muteLocalAudioStream
ormuteLocalVideoStream
within the channel to change the publishing status of the local audio or video stream, and then other users join the channel.
The behavior differences of Agora SDK between v3.7.0 and v4.0.0 are listed as follow:
- In v3.7.0, the local user receives the
onRemoteAudioStateChanged
oronRemoteVideoStateChanged
callback, which reports the status changes of the remote host's audio or video streams. - In v4.0.0, instead of the
onRemoteAudioStateChanged
oronRemoteVideoStateChanged
callback, the local user receives theonUserMuteAudio
oronUserMuteVideo
callback, which reports the changes in the remote host's publishing status.
Media options
There are differences in the behavior of the SDK when setting channel media options while joining a channel between agora_rtc_engine: ^5.x and agora_rtc_engine: ^6.0.0:
- In agora_rtc_engine: ^5.x, if you set
publishLocalAudio
inChannelMediaOptions
tofalse
, it will stop publishing the local audio stream within the channel. - In agora_rtc_engine: ^6.0.0, if you set
publishMicrophoneTrack
inChannelMediaOptions
tofalse
, it will not only stop publishing the local audio stream within the channel but also stop local microphone capture.
Function gaps
This section introduces functions that were supported in v3.7.x but are no longer supported or behave inconsistently in 4.x. Plans exist to support them or make them consistent in a future release, however.
Audio application scenarios.
reconstructs the audio application scenarios, which can replace most of the audio application scenarios of v3.7.x. The following table shows the correspondence of audio application scenarios in the two releases:
v3.7.x | 4.x |
---|---|
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 or AUDIO_SCENARIO_HIGH_DEFINITION |
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 |
Audio route
The following table shows the differences in the behavior of APIs related to the audio route between v3.7.x and :
API | v3.x | v4.x |
---|---|---|
|
|
|
|
After connecting external playback devices such as Bluetooth and wired headphones, calling |
Not recommended. |
Also, when an external playback device is removed, for example, by disconnecting the Bluetooth headset, the audio route change is different between v3.5.0 and 4.x:
-
In v3.7.x, the audio route changes as follows (in terms of priority): The external device connected next to last (if any) > … > The external device connected first >
setEnableSpeakerphone
>setDefaultAudioRoutetoSpeakerphone
> The default audio route. -
In 4.x, the audio route changes as follows (in terms of priority): The external device connected next to last (if any) > … > The external device connected first >
setDefaultAudioRoutetoSpeakerphone
> The default audio route.
Default video bitrate
In v3.7.x, if you set the video bitrate in VideoEncoderConfiguration as STANDARD_BITRATE
, the default video bitrate in the CHANNEL_PROFILE_LIVE_BROADCASTING
profile is twice that of the CHANNEL_PROFILE_COMMUNICATION
profile.
In 4.x, the video bitrate in the CHANNEL_PROFILE_COMMUNICATION
profile is the same as that in the CHANNEL_PROFILE_LIVE_BROADCASTING
profile, which means the video bitrate in the CHANNEL_PROFILE_COMMUNICATION
profile is doubled.
Virtual background
See Virtual Background to update the code in your app.
Image enhancement
4.x modifies the calling logic of setBeautyEffectOptions
. Before calling setBeautyEffectOptions
, you need to do the following:
-
Call
addExtension(agora_video_process)
duringRtcEngine
initialization to specify the extension’s library path. -
Call
enableExtension (agora, beauty, true)
to enable the extension. -
Call
enableVideo
to enable the video module.
See the VideoProcessExtensionVideoProcessExtension sample project to update the code in your app.
Unsupported functions
Compared to v3.7.x, some features are not supported or only partially supported in 4.x. This section shows the APIs currently unsupported but for which support is planned for a future release.
Remote video stream fallback:
-
setRemoteUserPriority
-
setRemoteSubscribeFallbackOption
-
onRemoteSubscribeFallbackToAudioOnly
Raw audio data:
-
getObservedAudioFramePosition
-
getRecordAudioParams
-
getMixedAudioParams
-
getPlaybackAudioParams
Raw video data:
getVideoFormatPreference
Audio and video statistics:
-
qualityChangedReason
member inRemoteAudioStats
-
captureBrightnessLevel
member inLocalVideoStats
Network type:
NETWORK_TYPE_MOBILE_5G
inAgoraNetworkType
Audio and video errors:
LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(8)
Selecting the playback track of the audio file:
selectAudioTrack
Pre-call network test: Before supporting the following APIs, you can use startLastmileProbeTest
and stopLastmileProbeTest
instead.
-
enableLastmileTest
-
disableLastmileTest
Call loop test:
startEchoTest
(with theconfig
parameter)
Screen sharing:
-
startScreenCaptureByDisplayId
-
onScreenCaptureInfoUpdated
Audio recording on the client:
-
recordingChannel
inAudioRecordingConfiguration
-
AgoraMediaRecorder
-
getMediaRecorder
-
startRecording
-
stopRecording
-
releaseRecorder
-
onRecorderStateChanged
-
onRecorderInfoUpdated
Wi-Fi acceleration:
-
enableWirelessAccelerate
-
onWlAccMessage
-
onWlAccStats
Video content inspection:
-
enableContentInspect
-
onContentInspectResult
Cloud proxy connection state:
onProxyConnected
External audio data:
-
pushExternalAudioFrame
(with thesourcePos
parameter) -
setExternalAudioSourceVolume
Removed APIs
The 4.x removes deprecated or unrecommended APIs. Alternatives to the removed API or reasons for their removal are shown as follows:
-
setVideoDenoiserOptions
,setLowlightEnhanceOptions
, andsetColorEnhanceOptions
: UsesetExtensionProperty
instead. -
onVirtualBackgroundSourceEnabled
: Use the return value ofenableVirtualBackground
instead. -
onUserSuperResolutionEnabled
: Use theRemoteVideoStats
member of thesuperResolutionType
class instead. -
setAudioMixingPlaybackSpeed
: UsesetPlaybackSpeed
instead. -
setAudioMixingDualMonoMode
: UsesetAudioDualMonoMode
instead. -
getEffectCurrentPosition
: UsegetPosition
instead. -
setEffectPosition
: Useseek
instead. -
getEffectDuration
:UsegetDuration
instead. -
setAgoraLibPath
: Use themNativeLibPath
member inRtcEngineConfig
instead when callingcreate
[2/2]. -
getAudioFileInfo
andonRequestAudioFileInfo
:UsegetDuration
instead. -
onFirstLocalAudioFrame
:UseonFirstLocalAudioFramePublished
instead. -
getRecordAudioParams
:UsesetRecordingAudioFrameParameters
instead. -
getMixedAudioParams
:UsesetMixedAudioFrameParameters
instead. -
getPlaybackAudioParams
:UsesetPlaybackAudioFrameParameters
instead. -
The
pushMode
parameter insetExternalVideoSource
: The default value of this parameter istrue
, and this parameter only takes effect when it is set totrue
. After deletion, it does not affect the function. -
The
channel
parameter intakeSnapshot
andonSnapshotTaken
has been removed: This change was made as thechannel
parameter was found to be redundant and was not essential for the functionality of these APIs. -
setLocalPublishFallbackOption
andonLocalPublishFallbackToAudioOnly
: Rarely used in v3.7.x. -
RENDER_MODE_FILL(4)
inRENDER_MODE_TYPE
: This mode might cause image overstretch and is not recommended. -
The following enumerations of audio mixing: Rarely used in v3.7.x.
-
AUDIO_MIXING_REASON_STARTED_BY_USER
-
AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED
-
AUDIO_MIXING_REASON_START_NEW_LOOP
-
AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED
-
AUDIO_MIXING_REASON_STOPPED_BY_USER
-
AUDIO_MIXING_REASON_PAUSED_BY_USER
-
AUDIO_MIXING_REASON_RESUMED_BY_USER
-
onAudioMixingFinished
: Rarely used in v3.7.x. -
The
info
parameter injoinChannel
[2/2]: This parameter is optional and rarely used in v3.7.x. -
enableDeepLearningDenoise
: The SDK will add deep-learning noise reduction as one of its capability in a future release instead of implementing through an API. -
setDefaultMuteAllRemoteVideoStreams
: UseautoSubscribeVideo
inChannelMediaOptions
. -
setDefaultMuteAllRemoteAudioStreams
: UseautoSubscribeAudio
inChannelMediaOptions
. -
The
replace
parameter instartAudioMixing
: UsepublishMicrophoneTrack
in theChannelMediaOptions
instead.
Naming and data type changes
The naming and data type changes in 4.x cause error messages in the IDE when you compile your project, and you need to update the code of your app according to each error message.
Naming changes
The main API and parameter name changes are as follows:
-
adjustLoopbackRecordingSignalVolume
is changed toadjustLoopbackRecordingVolume
. -
The
fileSize
member inLogConfig
is renamed tofileSizeInKB
. -
The
options
parameter injoinChannel
[2/2] is changed tomediaOptions
. -
The
report_vad
parameter in enableAudioVolumeIndication is changed toreportVad
. -
registerVideoEncodedFrameObserver
is changed toregisterVideoEncodedImageReceiver
.
Data type changes
The main API data type changes are as follows:
-
The
state
andreason
parameters inonRemoteAudioStateChanged
are changed from integer to enumeration. -
The
oldState
andnewState
parameters inonAudioPublishStateChanged
,onVideoPublishStateChanged
,onAudioSubscribeStateChanged
, andonVideoSubscribeStateChanged
are changed from integer to enumeration. -
The
state
anderror
parameters inonLocalAudioStateChanged
are changed from integer to enumeration. -
The
state
anderror
parameters inonRtmpStreamingStateChanged
are changed from integer to enumeration