Migrate from 3.x to 4.0.0

Agora SDK v4.0.0 is a new version of the SDK that you can use to embed real-time video and audio into your app. It supports large-scale real-time interactive activities and provides better real-time interactive effects. For details, see Benefits and features.

This page introduces the main steps to upgrade the SDK from v3.x (v3.7.0 and earlier) to v4.0.0, as well as the related changes.

Migration steps

This section introduces the main steps to upgrade the SDK from v3.x to v4.0.0.

1. Integrate the SDK

See Project setup for more information about integrating the v4.0.0 SDK into your project.

2. Update the Agora code in your app

The v4.0.0 SDK has optimized or modified the implementation of some functions, resulting in incompatibility with the v3.7.0 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 is based on v3.7.0 and introduces the main changes of v4.0.0 compared to v3.7.0 in the following categories. You need to update the code of your app according to your business scenario.

• Breaking changes: Introduces API compatibility changes. 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.0 but are not supported in v4.0.0. However, these functions are intended to be added in a future release.
• Removed APIs: Introduces APIs that were supported in v3.7.0 but removed in v4.0.0. Most of these APIs have alternatives in v4.0.0. 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.0 to v4.0.0, 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.0, the SDK provides the AgoraRtcChannel and AgoraRtcChannelDelegate classes to implement multi-channel control. The v3.7.0 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.

v4.0.0 introduces the following changes:

• The SDK supports one AgoraRtcEngineKit instance to collect multiple audio and video sources at the same time and publish them to the remote users by setting AgoraRtcEngineKit(Ex) and ChannelMediaOptions.
• After calling joinChannelByToken to join the first channel, call joinChannelExByToken multiple times to join multiple channels, and publish the specified stream to different channels through different user ID (localUid) and AgoraRtcChannelMediaOptions settings.
• Added a binary group AgoraRtcConnection to represent the connection established by joinChannelExByToken. A connection is determined by the channel name (channelId) and localUid. You can control the publishing and subscribing state of different connections through AgoraRtcConnection. The SDK adds Ex in the name of all APIs with a connection parameter (corresponding to the AgoraRtcConnection class) to distinguish them, and gathers these APIs in the AgoraRtcEngineKit(Ex) class to implement more multi-stream functions.

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 localUid.
• 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.

AgoraRtcChannel and AgoraRtcEngineKit of v3.7.0 are partially duplicated and overlap in their functionality, so v4.0.0 hides the AgoraRtcChannel and AgoraRtcChannelDelegate classes. See the JoinMultiChannel sample project for more details on how to replace AgoraRtcChannel with joinChannelExByToken and AgoraRtcChannelMediaOptions. The expected migration cost is one day or less.

If you need to continue to use the AgoraRtcChannel and AgoraRtcChannelDelegate 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 v4.0.0, the SDK gathers more channel-related settings into AgoraRtcChannelMediaOptions, 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 joinChannelByToken or joinChannelExByToken when joining a channel, or you can flexibly update the media options by calling updateChannelWithMediaOptions after joining a channel, such as switching video sources.

See the LiveBroadcasting sample project to update the code in your app.

Custom video source and renderer

In v3.7.0, 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 (AgoraVideoSourceProtocol) for custom video source
• MediaIO mode (AgoraVideoSinkProtocol) for custom video renderer

v4.0.0 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:

• AgoraVideoSourceProtocol
• AgoraVideoSinkProtocol
• AgoraVideoFrameConsumer
• setVideoSource
• setLocalVideoRenderer
• setRemoteVideoRenderer

If you use the MediaIO mode in v3.7.0 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: ScreenCapture

Warning codes

In v3.7.0, the SDK returns warning codes through the didOccurWarning callbacks.

To facilitate locating and troubleshooting issues, v4.0.0 reports problems and causes through the return values of APIs or different callbacks for listening to states. For example:

• connectionChangedToState: Reports the network connection state.
• localAudioStateChanged: Reports the local audio state.
• localVideoStateChange: Reports the local video state.
• remoteAudioStateChangedOfUid: Reports the remote audio state.
• remoteVideoStateChangedOfUid: Reports the remote video state.

As a consequence, v4.0.0 removes the didOccurWarning callbacks.

In addition to the breaking changes listed here relative to v3.7.0, v4.0.0 has a small number of breaking changes relative to the v4.0.0 release. For example:

• In v4.0.0, replace publishAudioTrack in AgoraRtcChannelMediaOptions with publishMicrophoneTrack.

If you used this feature in v4.0.0 and wish to upgrade to v4.0.0, modify the implementation code of the feature after upgrading the SDK.

Behavior changes

This section introduces changes caused by reasonable optimization of the SDK default behavior and API behavior.

Channel profile

In v3.7.0, the default channel profile is AgoraChannelProfileCommunication (the communication profile).

Because the interactive live 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 live streaming profile. In v4.0.0, Agora also changed the default channel profile to AgoraChannelProfileLiveBroadcasting (the interactive live streaming profile).

Network quality callback

In v3.7.0, if the uid parameter returned in networkQuality is 0, the callback reports the network quality of the local user. In v4.0.0, the uid of the local user returned in this callback is the same as the local user's actual uid in the channel.

Default log file

In v3.7.0, when the SDK creates multiple log files, the earlier files are named in a agorasdk_x.log format, such as agorasdk_1.log. v4.0.0 modified the naming format to agorasdk.x.log, such as agorasdk.1.log. Additionally, v4.0.0 adds the agoraapi.log file to record API logs.

Fast channel switching

In v3.7.0, you need to call switchChannelByToken to quickly switch a channel.

In v4.0.0, you can achieve the same switching speed as switchChannelByToken in v3.7.0 by switching a channel through leaveChannel and joinChannelByToken. Therefore, v4.0.0 removes switchChannelByToken. If you call switchChannelByToken to quickly switch a channel in v3.7.0, you need to call leaveChannel to leave the current channel in v4.0.0 and joinChannelByToken to join the second channel instead.

Agora self-developed extensions

v4.0.0 adds the feature of automatically loading self-developed dynamic libraries based on v4.0.0. 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 AgoraRtcEngineKit. 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 set publish to false.
In v4.0.0, set publishRhythmPlayerTrack in AgoraRtcChannelMediaOptions to false.

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, the reportAudioVolumeIndicationOfSpeakers callback is not received.
In v4.0.0, you must set the intervalto an integer that is a multiple of 200 ms. If the value of interval is lower than 200, the SDK automatically adjusts it to 200.

When the user's volume indication is enabled, the SDK triggers the reportAudioVolumeIndicationOfSpeakers 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, AgoraAudioLocalErrorDeviceNoPermission in localAudioStateChange reports that there is no permission to start the capture device, and AgoraLocalVideoStreamErrorDeviceNoPermission in localVideoStateChange 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 permissionError 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 call disableLastmileTest.

In v4.0.0, you can call startLastmileProbeTest to enable network quality testing. If you want to stop network testing, you need to call stopLastmileProbeTest.

Function gaps

This section introduces functions that were supported in v3.7.0 but are no longer supported or behave inconsistently in v4.0.0. Plans exist to support them or make them consistent in a future release, however.

Audio application scenarios

v4.0.0 reconstructs the audio application scenarios, which can replace most of the audio application scenarios of v3.7.0. The following table shows the correspondence of audio application scenarios in the two releases:

• v3.7.0	v4.0.0
  AgoraAudioScenarioDefault	AgoraAudioScenarioDefault
  AgoraAudioScenarioChatRoomEntertainment	AgoraAudioScenarioChatRoom
  AgoraAudioScenarioEducation	AgoraAudioScenarioDefault
  AgoraAudioScenarioGameStreaming	AgoraAudioScenarioGameStreaming or AgoraAudioScenarioHighDefinition
  AgoraAudioScenarioShowRoom	AgoraAudioScenarioDefault
  AgoraAudioScenarioChatRoomGaming	AgoraAudioScenarioChatRoom
  AgoraAudioScenarioIot	AgoraAudioScenarioDefault
  AgoraAudioScenarioMeeting	AgoraAudioScenarioMeeting

Unsupported functions

Compared to v3.7.0, some features are not supported or only partially supported in v4.0.0. This section shows the APIs currently unsupported but for which support is planned in a future release.

Remote video stream fallback:

• setRemoteUserPriority

Removed APIs

The v4.0.0 removes deprecated or unrecommended APIs. Alternatives to the removed API or reasons for their removal are shown as follows:

• virtualBackgroundSourceEnabled: Use the return value of enableVirtualBackground instead.
• superResolutionEnabledOfUid: Use the superResolutionType member of the AgoraRtcRemoteVideoStats class instead.
• setAudioMixingPlaybackSpeed: Use the relevant API under the IMediaPlayer (AgoraRtcMediaPlayerProtocol) class instead.
• setExternalAudioSourceVolume: Use adjustCustomAudioPublishVolume instead.
• getAudioFileInfo and didRequestAudioFileInfo: Use getDuration instead.
• reportAudioDeviceTestVolume：Use reportAudioVolumeIndicationOfSpeakers instead.
• setLocalPublishFallbackOption and didLocalPublishFallbackToAudioOnly: Rarely used in v3.7.0.
• AgoraVideoRenderModeFill(4) in AgoraVideoRenderMode: This mode can cause image overstretch and is not recommended.
• The following enumerations in AgoraAudioMixingReasonCode: Rarely used in v3.7.0.
  • AgoraAudioMixingReasonStartedByUser
  • AgoraAudioMixingReasonStartNewLoop
  • AgoraAudioMixingReasonPausedByUser
  • AgoraAudioMixingReasonResumedByUser
• rtcEngineLocalAudioMixingDidFinish: Use audioMixingStateChanged instead.
• enableDeepLearningDenoise: The SDK adds deep-learning noise reduction as one of its capability in a future release instead of implementing through an API.
• The channel parameter in takeSnapshot and snapshotTaken: The parameter is redundant.
• setDefaultMuteAllRemoteVideoStreams: Use autoSubscribeVideo in the AgoraRtcChannelMediaOptions instead.
• setDefaultMuteAllRemoteAudioStreams：Use autoSubscribeAudio in the AgoraRtcChannelMediaOptions instead.
• The replace parameter in startAudioMixing: Use publishMicrophoneTrack in the AgoraRtcChannelMediaOptions instead.

Naming changes

The naming changes in v4.0.0 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.

The main API and parameter name changes are as follows:

• adjustLoopbackRecordingSignalVolume is changed to adjustLoopbackSignalVolume.
• firstLocalAudioFrame is changed to firstLocalAudioFramePublished.
• The fileSize member in AgoraLogConfig is renamed to fileSizeInKB.
• The options parameter in joinChannelByToken[2/2] is changed to mediaOptions.
• The report_vad parameter in enableAudioVolumeIndication is changed to reportVad.