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.
This section introduces the main steps to upgrade the SDK from v3.x to v4.0.0.
See Project setup for more information about integrating the v4.0.0 SDK into your project.
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.
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.
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.
In v3.7.0, the SDK provides the initialize
method to create and initialize the RtcEngine
instance.
In v4.0.0, the SDK provides the createAgoraRtcEngine
method to create the RtcEngine
instance, and the initialize
method to initialize the engine.
Take onError
as an example:
In v3.7.0, the SDK provides the on
method to register event listener.
this.engine.on('error', (err, msg) => {});
In v4.0.0, the SDK provides the registerEventHandler
method to register event listener.
this.engine.registerEventHandler({
onError(err: ErrorCodeType, msg: string) {},
});
In v3.7.0, the SDK provides the AgoraRtcChannel
class and the on
function under the AgoraRtcChannel
class 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:
IRtcEngineEx
class to join multiple channels. After calling joinChannel
to join the first channel, call joinChannelEx
multiple times to join multiple channels, and publish the specified stream to different channels through different user ID (localUid
) and ChannelMediaOptions
settings.RtcConnection
to represent the connection established by joinChannel
. A connection is determined by the channel name (channelId
) and localUid
. You can control the publishing and subscribing state of different connections through RtcConnection
. The SDK adds Ex in the name of all APIs with a connection
parameter (corresponding to the RtcConnection
class) to distinguish them, and gathers these APIs in the IRtcEngineEx
class to implement more multi-stream functions.Combined with the multi-channel capability, you can also experience the following functions:
localUids
.localUid
.localUid
.AgoraRtcChannel
and IRtcEngine
of v3.7.0 are partially duplicated and overlap in their functionality, so v4.0.0 hides the AgoraRtcChannel
class and the on
function under the AgoraRtcChannel
class. See the JoinMultiChannel sample project for more details on how to replace AgoraRtcChannel
with joinChannel
and ChannelMediaOptions
. The expected migration cost is one day or less.
If you need to continue to use the AgoraRtcChannel
class and the on
function under the AgoraRtcChannel
class, contact support@agora.io. The decision whether to maintain compatibility in a future release is based on your feedback.
In v4.0.0, 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 JoinMultiChannel sample project to update the code in your app.
In v3.7.0, the SDK returns warning codes through the Warning
event.
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:
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, v4.0.0 removes the Warning
event.
After updating from v4.0.0 Beta to v4.0.0, the SDK package name has changed from electron-agora-rtc-ng
to agora-electron-sdk
, see Intergrate the SDK.
In v4.0.0 Beta, the SDK provides the joinChannel
and joinChannelWithOptions
methods to join a channel.
this._engine?.joinChannel(token: string, channelId: string, info: string, uid: number): number;
this._engine?.joinChannelWithOptions(token: string, channelId: string, uid: number, options: ChannelMediaOptions): number;
In v4.0.0, the original joinChannel
is removed, and the original joinChannelWithOptions
is renamed to joinChannel
.
this._engine?.joinChannel(
token: string,
channelId: string,
uid: number,
options: ChannelMediaOptions
): number;
Besides, publishAudioTrack
in the ChannelMediaOptions
enum is replaced with publishMicrophoneTrack
. If you used this feature in v4.0.0 Beta and wish to upgrade to v4.0.0, modify the implementation code of the feature after upgrading the SDK.
This section introduces changes caused by reasonable optimization of the SDK default behavior and API behavior.
In v3.7.0, the default channel profile is ChannelProfileCommunication
(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 ChannelProfileLiveBroadcasting
(the interactive live streaming profile).
In v3.7.0, if the uid
parameter returned in onNetworkQuality
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.
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.
In v3.7.0, you need to call switchChannel
to quickly switch a channel.
In v4.0.0, you can achieve the same switching speed as switchChannel
in v3.7.0 by switching a channel through leaveChannel
and joinChannel
. Therefore, v4.0.0 removes switchChannel
. If you call switchChannel
to quickly switch a channel in v3.7.0, you need to call leaveChannel
to leave the current channel in v4.0.0 and joinChannel
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 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 IRtcEngine
. You can directly call the corresponding method of the extension to enable this feature.
API | Extension type |
---|---|
enableVirtualBackground | Virtual background extension |
Video enhancement extension | |
enableRemoteSuperResolution | Super resolution extension |
Voice beautifier extension | |
enableSpatialAudio | Spatial audio extension |
enableContentInspect | Content moderation extension |
Local audio and video recording
In v3.7.0, the SDK does not support local audio and video recording.
In v 4.0.0, if you want to enable local audio and video recording, you need to call the getMediaRecorder
method to get the IMediaRecorder object.
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 ChannelMediaOptions
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 onAudioVolumeIndication
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 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 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, AudioLocalError.DeviceNoPermission
in the LocalAudioStateChanged
event reports that there is no permission to start the capture device, and LocalVideoStreamError
in the LocalVideoStateChanged
event 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 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
.
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.
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 |
---|---|
AudioScenarioDefault |
AudioScenarioDefault |
AudioScenarioChatroomEntertainment |
AudioScenarioChatroom |
AudioScenarioEducation |
AudioScenarioDefault |
AudioScenarioGameStreaming |
AudioScenarioGameStreaming |
AudioScenarioShowroom |
AudioScenarioDefault |
AudioScenarioChatroomGaming |
AudioScenarioChatroom |
AudioScenarioIot |
AudioScenarioDefault |
AudioScenarioMeeting |
AudioScenarioMeeting |
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.setAudioMixingPlaybackSpeed
: Use the relevant API under the IMediaPlayer
class instead.getAudioFileInfo
and onRequestAudioFileInfo:
Use getDuration
instead.onAudioDeviceTestVolumeIndication
:Use onAudioVolumeIndication
instead.setLocalPublishFallbackOption
and onLocalPublishFallbackToAudioOnly
: Rarely used in v3.7.0.enableDeepLearningDenoise
: The SDK adds deep-learning noise reduction as one of its capability in a future release instead of implementing through an API.Channel
parameter in takeSnapshot
and onSnapshotTaken
: The parameter is redundant.SetDefaultMuteAllRemoteVideoStreams: Use
autoSubscribeVideo
in the ChannelMediaOptions
instead.SetDefaultMuteAllRemoteAudioStreams
:Use autoSubscribeAudio
in the ChannelMediaOptions
instead.LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_NOT_SUPPORTED
in LOCAL_VIDEO_STREAM_ERROR
:Deprecated in v3.7.0.replace
parameter in startAudioMixing
: Use publishMicrophoneTrack
in the ChannelMediaOptions
instead.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 adjustLoopbackRecordingVolume
.onFirstLocalAudioFrame
is changed to onFirstLocalAudioFramePublished.
fileSize
member in LogConfig
is renamed to fileSizeInKB
.options
parameter in joinChannel
[2/2] is changed to mediaOptions
.report_vad
parameter in enableAudioVolumeIndication is changed to reportVad
.