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.

1. Integrate the SDK

   See Get started for more information about integrating the v4.x SDK into your project.

2. Rename imported classes

   After successfully integrating the SDK, you need to update the codes of imported classes from the io.agora.rtc prefix to the io.agora.rtc2 prefix in the /app/java/com.example.<projectname>/MainActivity file of your project.

   The location of AgoraRtcChannelMediaOptions.java in the 4.x SDK is also changed from /models to the root directory.

3. 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 use-case.

• 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 provides a RtcEngineEx class to implement multi-channel functions. Combined with the multi-channel capabilities, an RtcEngine instance can simultaneously collect multiple audio and video streams and publish them to the remote end to adapt to various business use-cases.

After calling joinChannel to join the first channel, call joinChannelEx multiple times to join multiple channels to publish the specified stream to different channels using different user IDs (localUid) and ChannelMediaOptions settings.

• A new RtcConnection class is added 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 RtcEngineEx class to implement more multi-stream functions.

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 use-cases. For example:

• Simultaneously publish video streams collected by multiple cameras or multiple screen sharing streams.
• 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 and RtcEngine of v3.7.x are partially duplicated and overlap in their functionality, so 4.x hides the RtcChannel and IRtcChannelEventHandler classes. See the JoinMultiChannel sample project for more details on how to replace RtcChannel with joinChannel and ChannelMediaOptions. 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 warning codes through the onWarning callback.

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 onWarning callback.

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).

Since 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.

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, LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION in onLocalAudioStateChanged reports that there is no permission to start the capture device, and LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION in onLocalVideoStateChanged 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.

Remote media event triggering mechanism

In the following use-cases, the mechanism of triggering remote media events is changed:

• Use-case 1: When the host calls muteLocalAudioStream or muteLocalVideoStream outside the channel to change the publishing status of the local audio or video stream and then joins the channel.
• Use-case 2: When the host calls muteLocalAudioStream or muteLocalVideoStream 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 or onRemoteVideoStateChanged callback, which reports the status changes of the remote host's audio or video streams.
• In v4.0.0, instead of the onRemoteAudioStateChanged or onRemoteVideoStateChanged callback, the local user receives the onUserMuteAudio or onUserMuteVideo 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 v3.7.x and 4.x:

• In v3.7.x, if you set publishLocalAudio in ChannelMediaOptions to false, it will stop publishing the local audio stream within the channel.
• In 4.x, if you set publishMicrophoneTrack in ChannelMediaOptions to false, 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 use-cases.

4.x 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:

The following table shows the differences in the behavior of APIs related to the audio route between v3.7.x and 4.x:

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:

1. Call addExtension(agora_video_process) during RtcEngine initialization to specify the extension’s library path.

2. Call enableExtension (agora, beauty, true) to enable the extension.

3. 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

Screen sharing:

• onScreenCaptureInfoUpdated

Removed APIs

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

• onVirtualBackgroundSourceEnabled: Use the return value of enableVirtualBackground instead.

• onUserSuperResolutionEnabled: Use the RemoteVideoStats member of the superResolutionType class instead.

• setAudioMixingPlaybackSpeed: Use setPlaybackSpeed instead.

• setExternalAudioSourceVolume: Use adjustCustomAudioPublishVolume instead.

• setAudioMixingDualMonoMode: Use setAudioDualMonoMode instead.

• getEffectCurrentPosition: Use getPosition instead.

• setEffectPosition: Use seek instead.

• getEffectDuration：Use getDuration instead.

• setAgoraLibPath: Use the mNativeLibPath member in RtcEngineConfig instead when calling create [2/2].

• getAudioFileInfo and onRequestAudioFileInfo：Use getDuration instead.

• onAudioDeviceTestVolumeIndication：Use onAudioVolumeIndication instead.

• onFirstLocalAudioFrame：Use onFirstLocalAudioFramePublished instead.

• getRecordAudioParams：Use setRecordingAudioFrameParameters instead.

• getMixedAudioParams：Use setMixedAudioFrameParameters instead.

• getPlaybackAudioParams：Use setPlaybackAudioFrameParameters instead.

• The pushMode parameter in setExternalVideoSource: The default value of this parameter is true, and this parameter only takes effect when it is set to true. After deletion, it does not affect the function.

• The channel parameter in takeSnapshot and onSnapshotTaken has been removed: This change was made as the channel parameter was found to be redundant and was not essential for the functionality of these APIs.

• setLocalPublishFallbackOption and onLocalPublishFallbackToAudioOnly: Rarely used in v3.7.x.

• RENDER_MODE_FILL(4) in RENDER_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: Use onAudioMixingStateChanged instead.

• The info parameter in joinChannel [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: Use autoSubscribeVideo in ChannelMediaOptions.

• setDefaultMuteAllRemoteAudioStreams: Use autoSubscribeAudio in ChannelMediaOptions.

• The replace parameter in startAudioMixing: Use publishMicrophoneTrack in the ChannelMediaOptions 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 to adjustLoopbackRecordingVolume.

• The fileSize member in LogConfig is renamed to fileSizeInKB.

• The options parameter in joinChannel[2/2] is changed to mediaOptions.

• The report_vad parameter in enableAudioVolumeIndication is changed to reportVad.

• registerVideoEncodedFrameObserver is changed to registerVideoEncodedImageReceiver.

Data type changes

The main API data type changes are as follows:

• The state and reason parameters in onRemoteAudioStateChanged are changed from integer to enumeration.

• The oldState and newState parameters in onAudioPublishStateChanged, onVideoPublishStateChanged, onAudioSubscribeStateChanged, and onVideoSubscribeStateChanged are changed from integer to enumeration.

• The state and error parameters in onLocalAudioStateChanged are changed from integer to enumeration.

• The state and error parameters in onRtmpStreamingStateChanged are changed from integer to enumeration

• 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 3.7.x to v4.x.

1. Integrate the SDK

   See Get started for more information about integrating the v4.x SDK into your project.

2. Update the Agora code in your app

   The v4.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 the What has changed section below.

What has changed

This section introduces the main changes of v4.x compared to v3.7.x in the following categories. You need to update the code of your app according to your business use-case.

• 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 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 v4.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 AgoraRtcChannel and AgoraRtcChannelDelegate 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.

v4.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 AgoraRtcEngineKit: you can call joinChannelExByToken (replacing joinChannelByToken of the AgoraRtcChannel class in v3.7.x) multiple times, and publish the specified stream to different channels through different user IDs (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.

By setting AgoraRtcChannelMediaOptions, v4.x supports using one AgoraRtcEngineKit 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 use-cases. For example:

• Simultaneously publish a media player stream, a screen-sharing stream, and a video stream captured by the camera.

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

AgoraRtcChannel and AgoraRtcEngineKit of v3.7.x are partially duplicated and overlap in their functionality, so v4.x 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 v3.7.x, the SDK uses the publishLocalAudio and publishLocalVideo members in AgoraRtcChannelMediaOptions to control the audio and video publishing state in the channel.

In v4.x, 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 achannel, 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 (AgoraVideoSourceProtocol) for custom video source

• MediaIO mode (AgoraVideoSinkProtocol) for custom video renderer

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

• AgoraVideoSourceProtocal

• AgoraVideoSinkProtocal

• AgoraVideoFrameConsumer

• setVideoSource

• setLocalVideoRenderer

• setRemoteVideoRenderer

• videoSource

• localVideoRenderer

• remoteVideoRendererOfUserId

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 didOccurError and didOccurWarning callbacks.

To facilitate locating and troubleshooting issues, v4.x 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.

• localVideoStateChangedOfState: Reports the local video state.

• remoteAudioStateChangedOfUid: Reports the remote audio state.

• remoteVideoStateChangedOfUid: Reports the remote video state.

As a consequence, v4.x removes the didOccurError and didOccurWarning 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 AgoraChannelProfileCommunication (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 v4.x, Agora also changed the default channel profile to AgoraChannelProfileLiveBroadcasting (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. v4.x modified the naming format to agorasdk.x.log, such as agorasdk.1.log. Additionally, v4.x adds the agoraapi.log file to record API logs.

Fast channel switching

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

In v4.x, you can achieve the same switching speed as switchChannelByToken in v3.7.x by switching a channel through leaveChannel and joinChannelByToken. Therefore, v4.x removes switchChannelByToken. If you call switchChannelByToken to quickly switch a channel in v3.7.x, see the QuickSwitchChannel 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. 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.

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

Remote media event triggering mechanism

In the following use-cases, the mechanism of triggering remote media events is changed:

• Use-case 1: When the host calls muteLocalAudioStream or muteLocalVideoStream outside the channel to change the publishing status of the local audio or video stream and then joins the channel.
• Use-case 2: When the host calls muteLocalAudioStream or muteLocalVideoStream 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 remoteAudioStateChangedOfUid or remoteVideoStateChangedOfUid callback, which reports the status changes of the remote host's audio or video streams.
• In v4.0.0, instead of the remoteAudioStateChangedOfUid or remoteVideoStateChangedOfUid callback, the local user receives the didAudioMuted or didVideoMuted 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 v3.7.0 and v4.0.0:

• In v3.7.0, if you set publishLocalAudio in AgoraRtcChannelMediaOptions to NO, it will stop publishing the local audio stream within the channel.
• In v4.0.0, if you set publishMicrophoneTrack in AgoraRtcChannelMediaOptions to NO, it will not only stop publishing the local audio stream within the channel but also stop local microphone capture.

Video information change event

If the video capture device is put into the landscape or portrait mode during video capture, in v3.7.0 and v4.0.0, the following differences exist in the video information change events reported by the SDK:

• In v3.7.0, the rotation parameter in the videoSizeChangedOfUid callback displays the current device rotation information.
• In v4.0.0, the rotation parameter in the videoSizeChangedOfSourceType callback is always 0.

Function gaps

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

Audio application scenarios

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

Audio route

The following table shows the differences in the behavior of APIs related to the audio route between v3.7.x and v4.x:

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 v4.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 v4.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 AgoraVideoEncoderConfiguration as AgoraVideoBitrateStandard, the default video bitrate in the AgoraChannelProfileLiveBroadcasting profile is twice that of the AgoraChannelProfileCommunication profile.

In v4.x, the video bitrate in the AgoraChannelProfileCommunication profile is the same as that in the AgoraChannelProfileLiveBroadcasting profile, which means the video bitrate in the AgoraChannelProfileCommunication profile is doubled.

Virtual background

See Virtual Background to update the code in your app.

Image enhancement

v4.x modifies the calling logic of setBeautyEffectOptions. Before calling setBeautyEffectOptions, you need to do the following:

1. Integrate the AgoraVideoProcessExtension.xcframework dynamic library in the project.

2. Call enableExtension ("agora", "beauty", "YES") before joining a channel to enable the image enhancement extension.

3. Call enableVideo to enable the video module.

See the VideoProcess 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 v4.x. This section shows the APIs currently unsupported but for which support is planned for a future release.

Remote video stream fallback:

• setRemoteUserPriority

• setRemoteSubscribeFallbackOption

• didRemoteSubscribeFallbackToAudioOnly

Raw audio data:

• getObservedAudioFramePosition

• getRecordAudioParams

• getMixedAudioParams

• getPlaybackAudioParams

Raw video data:

• getVideoFormatPreference

Audio and video statistics:

• qualityChangedReason member in RemoteAudioStats

• captureBrightnessLevel members in LocalVideoStats

Network type:

• AgoraNetworkTypeMobile5G in AgoraNetworkType

Audio and video errors:

• AgoraAudioLocalErrorInterrupted(8)

• AgoraLocalVideoStreamErrorCaptureNoDeviceFound(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:

• startEchoTestWithInterval (with the config parameter)

Audio recording on the client:

• recordingChannel in AgoraAudioRecordingConfiguration

• AgoraMediaRecorder

• sharedMediaRecorderWithRtcEngine

• startRecording

• stopRecording

• destroy

• stateDidChanged

• informationDidUpdated

Wi-Fi acceleration:

• enableWirelessAccelerate

• wlAccMessage

• wlAccStats

Video content inspection:

• enableContentInspect

• contentInspectResult

Cloud proxy connection state:

• didProxyConnected

External audio data:

• pushExternalAudioFrameRawData (with the sourcePos parameter)

• pushExternalAudioFrameSampleBuffer (with the sourcePos parameter)

Removed APIs

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

• setVideoDenoiserOptions, setLowlightEnhanceOptions, and setColorEnhanceOptions: Use setExtensionPropertyWithVendor instead.

• virtualBackgroundSourceEnabled: Use the return value of enableVirtualBackground instead.

• superResolutionEnabledOfUid: Use the superResolutionType member of the AgoraRtcRemoteVideoStats class instead.

• setAudioMixingPlaybackSpeed: Use setPlaybackSpeed instead.

• setExternalAudioSourceVolume: Use adjustCustomAudioPublishVolume instead.

• setAudioMixingDualMonoMode: Use setAudioDualMonoMode instead.

• getEffectCurrentPosition: Use getPosition instead.

• setEffectPosition: Use seekToPosition instead.

• getEffectDuration: Use getDuration instead.

• getAudioFileInfo and didRequestAudioFileInfo: Use getDuration instead.

• reportAudioDeviceTestVolume: Use reportAudioVolumeIndicationOfSpeakers instead.

• firstLocalAudioFrame: Use firstLocalAudioFramePublished instead.

• getRecordAudioParams: Use setRecordingAudioFrameParametersWithSampleRate instead.

• getMixedAudioParams: Use setMixedAudioFrameParametersWithSampleRate instead.

• getPlaybackAudioParams: Use setPlaybackAudioFrameParametersWithSampleRate instead.

• The pushMode parameter in setExternalVideoSource: The default value of this parameter is YES, and this parameter only takes effect when it is set to YES. After deletion, it does not affect the function.

• setLocalPublishFallbackOption and didLocalPublishFallbackToAudioOnly: Rarely used in v3.7.x.

• AgoraVideoRenderModeFill(4) in AgoraVideoRenderMode: This mode might cause image overstretch and is not recommended.

• The following enumerations in AgoraAudioMixingReasonCode: Rarely used in v3.7.x.

• AgoraAudioMixingReasonStartedByUser

• AgoraAudioMixingReasonOneLoopCompleted

• AgoraAudioMixingReasonStartNewLoop

• AgoraAudioMixingReasonAllLoopsCompleted

• AgoraAudioMixingReasonStoppedByUser

• AgoraAudioMixingReasonPausedByUser

• AgoraAudioMixingReasonResumedByUser

• rtcEngineLocalAudioMixingDidFinish: Use audioMixingStateChanged instead.

• The info parameter in joinChannelByToken [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.

• The channel parameter in takeSnapshot and snapshotTaken has been removed: This change was made as the channel parameter was found to be redundant and was not essential for the functionality of these APIs.

• setDefaultMuteAllRemoteVideoStreams: Use autoSubscribeVideo in AgoraRtcChannelMediaOptions.

• setDefaultMuteAllRemoteAudioStreams: Use autoSubscribeAudio in AgoraRtcChannelMediaOptions.

• The replace parameter in startAudioMixing: Use publishMicrophoneTrack in the AgoraRtcChannelMediaOptions instead.

Naming changes

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

The main API and parameter name changes are as follows:

• localVideoStateChange is changed to localVideoStateChangedOfState.

• localVideoStats is changed to localVideoStatssourceType.

• sourceType is added in didVideoPublishStateChange.

• firstLocalVideoFramePublished is changed to firstLocalVideoFramePublishedWithElapsed.

• videoSizeChangedOfUid is changed to videoSizeChangedOfSourceType.

• adjustLoopbackRecordingSignalVolume is changed to adjustLoopbackSignalVolume.

• sourceType is added in firstLocalVideoFrameWithSize.

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

• localVideoStateChange is changed to localVideoStateChangedOfState, and AgoraLocalVideoStreamState is changed to AgoraVideoLocalState.

• The report_vad parameter in enableAudioVolumeIndication is changed to reportVad.

• The errorCode parameter in rtmpStreamingChangedToState is changed to errCode.

• localAudioMixingStateDidChanged is changed to audioMixingStateChanged.

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 v2.x or 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 v2.x or v3.x to v4.0.0.

1. Integrate the SDK

See Get started 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 use-case.

• 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 Join multiple channels 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.

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

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.

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

Remote media event triggering mechanism

In the following use-cases, the mechanism of triggering remote media events is changed:

• Use-case 1: When the host calls muteLocalAudioStream or muteLocalVideoStream outside the channel to change the publishing status of the local audio or video stream and then joins the channel.
• Use-case 2: When the host calls muteLocalAudioStream or muteLocalVideoStream 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 remoteAudioStateChangedOfUid or remoteVideoStateChangedOfUid callback, which reports the status changes of the remote host's audio or video streams.
• In v4.0.0, instead of the remoteAudioStateChangedOfUid or remoteVideoStateChangedOfUid callback, the local user receives the didAudioMuted or didVideoMuted 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 v3.7.0 and v4.0.0:

• In v3.7.0, if you set publishLocalAudio in AgoraRtcChannelMediaOptions to NO, it will stop publishing the local audio stream within the channel.
• In v4.0.0, if you set publishMicrophoneTrack in AgoraRtcChannelMediaOptions to NO, it will not only stop publishing the local audio stream within the channel but also stop local microphone capture.

Video information change event

If the video capture device is put into the landscape or portrait mode during video capture, in v3.7.0 and v4.0.0, the following differences exist in the video information change events reported by the SDK:

• In v3.7.0, the rotation parameter in the videoSizeChangedOfUid callback displays the current device rotation information.
• In v4.0.0, the rotation parameter in the videoSizeChangedOfSourceType callback is always 0.

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:

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:

• localVideoStateChange is changed to localVideoStateChangedOfState.
• localVideoStats is changed to localVideoStatssourceType.
• sourceType is added in didVideoPublishStateChange.
• firstLocalVideoFramePublished is changed to firstLocalVideoFramePublishedWithElapsed.
• videoSizeChangedOfUid is changed to videoSizeChangedOfSourceType.
• adjustLoopbackRecordingSignalVolume is changed to adjustLoopbackSignalVolume.
• sourceType is added in firstLocalVideoFrameWithSize.
• 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.
• The errorCode parameter in rtmpStreamingChangedToState is changed to errCode.

Web SDK v4.x represents a complete overhaul of Web SDK v3.x, featuring optimized internal architecture and enhanced API usability. Key advantages include:

• Promise-based APIs for asynchronous operations, improving code robustness and readability.
• Full TypeScript support for enhanced development experience.
• Introduction of Track objects to independently control audio and video, offering increased flexibility and separation of concerns.
• Streamlined channel event notification mechanism, with unified event naming and callback parameter formats, reducing complexity in handling disconnections and reconnections.
• Clear and comprehensive error code system to facilitate troubleshooting.

This version provides a clearer and more concise overview of the improvements in Web SDK v4.x while maintaining focus on the key advantages for users.

This page tells you about:

• Migration steps to upgrade your app to Voice Calling v4.x.

• What's changed between Voice Calling v3.x and v4.x.

• Core API change list between Voice Calling v3.x and v4.x.

Migration steps

This section takes building a video conferencing app as an example and introduces the differences between implementing the Voice Calling v4.x and the Voice Calling v3.x in detail.

Join a channel

First, create a Client object and join a specified channel.

• Using Voice SDK v3.x

  const client = AgoraRTC.createClient({ mode: "live", codec: "vp9" });
  client.init("APPID", () => {
   client.join("Token", "Channel", null, (uid) => {
    console.log("join success", uid);
   }, (e) => {
    console.log("join failed", e);
   });
  });

• Using Voice SDK v4.x

    const client = AgoraRTC.createClient({ mode: "live", codec: "vp9" });
  
    try {
     const uid = await client.join("APPID", "Channel", "Token", uid);
     console.log("join success");
    } catch (e) {
     console.log("join failed", e);
    }

Here we assume that our code runs within in an async function and use await in the following code snippets.

Key points:

• In the Voice Calling v4.x, we use the Promise object together with async/await for the asynchronous operation join.

• The Voice Calling v4.x removes the client.init method and you pass APPID when calling client.join. If you want to join another channel that uses a different App ID, you do not need to create another client object.

Create an audio track and a video track

Second, create an audio track object from the audio sampled by a microphone and create a local video track from the video captured by a camera. In the sample code, by default, we play the local video track and do not play the local audio track.

• Using Voice SDK v3.x

  const localStream = AgoraRTC.createStream({ audio: true, video: true });
  localStream.init(() => {
   console.log("init stream success");
   localStream.play("DOM_ELEMENT_ID", { muted: true });
  }, (e) => {
   console.log("init local stream failed", e);
  });

• Using Voice SDK v4.x

    const localAudio = await AgoraRTC.createMicrophoneAudioTrack();
    const localVideo = await AgoraRTC.createCameraVideoTrack();
    console.log("create local audio/video track success");
  
    localVideo.play("DOM_ELEMENT_ID");

Key points:

• The Voice Calling v4.x removes the Stream object. Call createMicrophoneAudioTrack to create an audio track and call createCameraVideoTrack to create a video track.

• The audio and video track objects in the Voice Calling v4.x do not provide the init method because the SDK initializes the microphone and camera when creating the tracks and notifies you of the result with promises.

• The Voice Calling v4.x can control the playback of local audio and video tracks separately and removes the muted parameter in the play method. If you do not want to play the local audio track, do not call play in the local audio track object.

Publish the local audio and video tracks

After creating the local audio and video tracks, publish these tracks to the channel.

• Using Voice SDK v3.x

  client.publish(localStream, err => {
   console.log("publish failed", err);
  });
  client.on("stream-published", () => {
   console.log("publish success");
  });

• Using Voice SDK v4.x

  try {
   // Remove this line if the channel profile is not live broadcast.
   await client.setClientRole("host");
   await client.publish([localAudio, localVideo]);
   console.log("publish success");
  } catch (e) {
   console.log("publish failed", e);
  }

Key points:

• If your channel profile is live broadcast, the Voice Calling v3.x automatically sets the user role as host when publishing the stream. However, in the Voice Calling v4.x, you need to call setClientRole to set the user role as host.

• In the Voice Calling v4.x, publish returns a Promise object representing the eventual completion or failure of the asynchronous operation.

• In the Voice Calling v4.x, when calling publish, you need to pass one or multiple LocalTrack objects instead of the Stream object. You can call publish repeatedly to publish multiple tracks and call unpublish repeatedly to unpublish multiple tracks.

Subscribe to remote media tracks and play

When a remote user in the channel publishes media tracks, we need to automatically subscribe to these tracks and play. To do this, you need to listen for the user-published event and call subscribe when the SDK triggers this event.

• Using Voice SDK v3.x

  client.on("stream-added", e => {
   client.subscribe(e.stream, { audio: true, video: true }, err => {
    console.log("subscribe failed", err);
   });
  });
  
  client.on("stream-subscribed", e => {
   console.log("subscribe success");
   e.stream.play("DOM_ELEMENT_ID");
  });

• Using Voice SDK v4.x

  client.on("user-published", async (remoteUser, mediaType) => {
   await client.subscribe(remoteUser, mediaType);
   if (mediaType === "video" || mediaType === "all") {
    console.log("subscribe video success");
    remoteUser.videoTrack.play("DOM_ELEMENT_ID");
   }
   if (mediaType === "audio" || mediaType === "all") {
    console.log("subscribe audio success");
    remoteUser.audioTrack.play();
   }
  });

Key points:

• The Voice Calling v4.x replaces the stream-added, stream-removed, and stream-updated events with the user-published and user-unpublished events.

Pay attention to the mediaType parameter of the user-published event, which marks the type of the current track the remote user publishes. It can be "video" or "audio". If the remote user publishes an audio track and a video track at the same time, the SDK triggers two user-published events, in which mediaType is "audio" and "video" respectively.

• In the Voice Calling v4.x, subscribe returns a Promise object representing the eventual completion or failure of the asynchronous operation. When calling subscribe, pass a remoteUser object. For details, see AgoraRTCRemoteUser.

• When the subscription succeeds, the subscribed tracks are updated to remoteUser and you can go on to call play.

What’s changed

This section lists the major changes to Voice Calling.

Use promises for asynchronous operations

For asynchronous methods such as joining and leaving a channel, publishing and subscribing, enumerating media input devices, and starting and stopping live transcoding, the Voice Calling notifies users of the results of these asynchronous operations with callbacks or events, while the Voice Calling v4.x uses promises.

Fine control over audio and video tracks

For the Voice Calling v4.x, we replace the Stream object with Track objects. You create, publish, or subscribe to one or multiple audio and video tracks. Tracks make up a stream. The advantage of dividing a stream up into tracks is that audio and video are controllable separately. And these new methods are easier to use than the Stream.addTrack and Stream.removeTrack methods in the Voice Calling.

For now, the Voice Calling v4.x allows publishing multiple audio tracks but only one video track. The SDK automatically mixes multiple audio tracks into one when publishing.

In addition to replacing the Stream object with Track objects, the Voice Calling v4.x provides different interfaces for the local and remote tracks. Some methods and objects are only available locally, and some are only available remotely. This change affects multiple API methods, including creating objects, publishing, and subscribing to tracks. For details, see Create an audio track and a video track and Publish the local audio and video tracks.

Improved channel events

The improved events are:

• Rename events

The Voice Calling v4.x ensures the consistency of all event names. For example, Agora renames onTokenPrivilegeWillExpire as token-privilege-will-expire. Agora also renames several events to ensure developers can better understand how they work. For example, Agora renames peer-online and peer-offline as user-joined and user-left, stream-added and stream-removed as user-published and user-unpublished.

• Change the format of parameters in events

In the Voice Calling v3.x, the parameters of events must be wrapped in an object, while in the Voice Calling v4.x, you can directly pass multiple parameters in events.

Take the "connection-state-change" event as an example:

• Using Voice SDK v3.x

  client.on("connection-state-change", e => {
   console.log("current", e.curState, "prev", e.prevState);
  });

• Using Voice SDK v4.x

  client.on("connection-state-change", (curState, prevState) => {
   console.log("current", curState, "prev", prevState);
  });

• Improve the event notification mechanism

The Voice Calling v4.x improves its event notification mechanism, and does not trigger channel events repeatedly.

For example, assume that a local user A and remote users B, C, and D joins a channel at the same time, and B, C, and D all publishes their streams. If A suddenly loses connection with the channel due to bad network conditions, the SDK automatically reconnects A to the channel. While A is reconnecting to the channel, B leaves the channel and C unpublishes the stream. My question is, what events that the SDK triggers during the whole process?

When A joins the channel, the Voice Calling v3.x and Voice Calling v4.x trigger the same events:

• Events indicating B, C, D joining the channel.

• Events indicating B, C, D publishing their streams.

When A loses connection with the channel due to poor network conditions and reconnects to the channel:

• If A uses the Voice Calling v3.x: When A loses connection with the channel due to poor network conditions, the SDK assumes A has left the channel and clears all the states in the channel. When A successfully reconnects to the channel, it receives:

• Events indicating C, D joining the channel.

• Events indicating D publishing the stream.

In the Voice Calling v3.x, you can expect to receive the same events multiple times due to disconnection and reconnection, which may cause unexpected problems for dealing with these events on the app level. You need to listen for connection state changes and reset the states on the app level to avoid unexpected problems when receiving these events for the second time.

• If A uses the Voice Calling v4.x: When A loses connection with the channel due to poor network conditions, the SDK assumes that A is still in the channel and does not clear all the states in the channel. When A successfully reconnects to the channel, the SDK only sends A events that are lost during the reconnection process, including:

• The event indicating B leaving the channel.

• The event indicating C unpublishing the stream.

  The Voice Calling v4.x does not send you the same events repeatedly and ensures your app works properly during reconnection.

  As these hypothetical examples demonstrate, the event notification mechanism in the Voice Calling v4.x is more intuitive and does not need extra work.

Core API change list

AgoraRTC

• Rename getScreenSources as getElectronScreenSources, remove callbacks, and return a promise

• getDevices returns a promise. Add getCameras and getMicrophones

• Remove the Logger object, and add disableLogUpload, enableLogUpload, and setLogLevel

• Replace createStream with the following methods:

• createMicrophoneAudioTrack

• createCameraVideoTrack

• createScreenVideoTrack

• createBufferSourceAudioTrack

• createCustomAudioTrack

• createCustomVideoTrack

Client

• Remove Client.init

• Remove Client.getConnectionState and add Client.connectionState

• Add RECONNECTING in ConnectionState

• Add Client.uid

• Add Client.remoteUsers

• Remove Client.on("streamInjectStatus")

• Remove Client.removeInjectStream

• Remove the callbacks of Client.enableDualStream / Client.disableDualStream and return a promise

• Move Client.getCameras, Client.getDevices, Client.getRecordingDevices to the AgoraRTC interface

• Remove Client.getPlayoutDevices

• Replace Client.getLocalAudioStats, Client.getLocalVideoStats, Client.getRemoteAudioStats, and Client.getRemoteVideoStats with LocalAudioTrack.getStats, LocalVideoTrack.getStats, RemoteAudioTrack.getStats, and RemoteVideoTrack.getStats.

• Remove Client.getSystemStats

• Replace Client.getSessionStats and Client.getTransportStats with Client.getRTCStats

• Remove the callback in Client.join and return a promise. Also add the appid parameter in this method

• Remove the callback in Client.leave and return a promise.

• Add Client.once

• Add Client.removeAllListeners

• Add the tracks parameter in Client.publish for passing LocalTrack. This method returns a promise. Remove Client.on("stream-published")

• Client.unpublish returns a promise.

• Add the user parameter in Client.subscribe for passing AgoraRTCRemoteUser. This method returns a promise. Remove Client.on("stream-subscribed").

• Add the user parameter in Client.unsubscribe for passing AgoraRTCRemoteUser. This method returns a promise.

• Client.renewToken returns a promise.

• Remove the callback in Client.setClientRole and return a promise. In the Voice Calling v4.x, setting the user role as audience does not unpublish, and when calling publish, the SDK does not automatically set the user role as host

• Replace Client.setEncryptionMode and Client.setEncryptionSecret with Client.setEncryptionConfig

• Client.setLiveTranscoding, Client.startLiveStreaming, and Client.stopLiveStreaming all return a promise. Remove Client.on("liveTranscodingUpdated"), Client.on("liveStreamingStarted"), Client.on("liveStreamingFailed"), and Client.on("liveStreamingStopped") events.

• Client.startChannelMediaRelay return a promise

• Replace setDestChannelInfo in ChannelMediaRelayConfiguration with addDestChannelInfo, remove several parameters

• Remove several parameters in setSrcChannelInfo of ChannelMediaRelayConfiguration

• Client.stopChannelMediaRelay return a promise.

• Remove the callback in Client.updateChannelMediaRelay and this method returns a promise.

• Replace Client.on("first-video-frame-decode") and Client.on("first-audio-frame-decode") with RemoteTrack.on("first-frame-decode")

• Replace Client.on("mute-audio"), Client.on("mute-video"), Client.on("unmute-audio"), and Client.on("unmute-video") with Client.on("user-mute-updated")

• Replace Client.on("active-speaker") with Client.on("volume-indicator")

• Rename Client.on("onTokenPrivilegeWillExpire") and Client.on("onTokenPrivilegeDidExpire") as Client.on("token-privilege-will-expire") and Client.on("token-privilege-did-expire")

• Remove Client.on("network-type-changed")

• Remove Client.on("connected") and Client.on("reconnect"). You can get events related to connection states from Client.on("connection-state-change")

• Add the isFallbackOrRecover parameter in Client.on("stream-fallback")

Stream

In the Voice Calling v4.x, Agora replaces the Stream object with Track objects. Tracks make up a stream. You create, publish, or subscribe to one or multiple audio and video tracks to control the media stream. The advantage of dividing a stream up into tracks is that audio and video are controllable separately. Additionally, the Voice Calling v4.x provides different interfaces for the local and remote tracks. Some methods and objects are only available locally, and some are only available remotely.

Listed below are the major differences on media control between the Voice Calling v4.x and Voice Calling v3.x:

• Enable/disable a local track: The Voice Calling v4.x replaces the Stream.muteAudio and Stream.muteVideo methods with ILocalTrack.setEnabled for enabling or disabling a local audio or video track. This replacement changes the following SDK behaviors:

• In the Voice Calling v3.x, when the mute state changes, the SDK triggers the Client.on("mute-audio"), Client.on("mute-video"), Client.on("unmute-audio"), or Client.on("unmute-video") events. The Voice Calling v4.x removes these events. When you call setEnabled to enable or disable a published local track, the SDK triggers the Client.on("user-published") or Client.on("user-unpublished") events on the remote client.

• In the Voice Calling v3.x, after you call Stream.muteVideo(true) to disable a local video stream, the camera light stays on, which might adversely impact the user experience. In contrast, if you call setEnabled(false) in the Voice Calling v4.x to disable a local video track, the SDK immediately turns off the camera.

• Set the media device:

• The Voice Calling v4.x replaces Stream.switchDevice with IMicrophoneAudioTrack.setDevice and ICameraVideoTrack.setDevice for setting the media input device.

• The Voice Calling v4.x replaces Stream.setAudioOutput with IRemoteAudioTrack.setPlaybackDevice for setting the audio output device.

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 v2.x or 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 v2.x or v3.x to v4.0.0.

1. Integrate the SDK

See Get started 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.

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 use-case.

• 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 IChannel and IChannelEventHandler 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 IRtcEngine instance to collect multiple audio and video sources at the same time and publish them to the remote users by setting IRtcEngineEx and ChannelMediaOptions.
• 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.
• Added a binary group 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:

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

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

If you need to continue to use the IChannel and IChannelEventHandler 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 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 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 (IVideoSource) for custom video source
• MediaIO mode (IVideoSink) 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:

• IVideoSource
• IVideoSink
• IVideoFrameConsumer
• 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/Custom video renderer: CustomVideoCapture
• Switching video source: ScreenShare

Warning codes

In v3.7.0, the SDK returns warning codes through the onWarning 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:

• onConnectionStateChanged: 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 onWarning 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 Beta release. For example:

• In v4.0.0, replace publishAudioTrack in ChannelMediaOptions 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.

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

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

Local audio and video recording

In v3.7.0, if you want to enable local audio and video recording, you need to call the getMediaRecorder method to get the AgoraMediaRecorder object. In v 4.0.0, if you want to enable local audio and video recording, you need to call the queryInterface 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, LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION in onLocalAudioStateChanged reports that there is no permission to start the capture device, and LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION in onLocalVideoStateChanged 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.

Remote media event triggering mechanism

In the following use-cases, the mechanism of triggering remote media events is changed:

• Use-case 1: When the host calls muteLocalAudioStream or muteLocalVideoStream outside the channel to change the publishing status of the local audio or video stream and then joins the channel.
• Use-case 2: When the host calls muteLocalAudioStream or muteLocalVideoStream 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 or onRemoteVideoStateChanged callback, which reports the status changes of the remote host's audio or video streams.
• In v4.0.0, instead of the onRemoteAudioStateChanged or onRemoteVideoStateChanged callback, the local user receives the onUserMuteAudio or onUserMuteVideo 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 v3.7.0 and v4.0.0:

• In v3.7.0, if you set publishLocalAudio in ChannelMediaOptions to false, it will stop publishing the local audio stream within the channel.
• In v4.0.0, if you set publishMicrophoneTrack in ChannelMediaOptions to false, 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.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:

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

Screen sharing:

• onScreenCaptureInfoUpdated

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.
• onUserSuperResolutionEnabled: Use the remoteVideoStats member of the superResolutionType class instead.
• setAudioMixingPlaybackSpeed: Use the relevant API under the IMediaPlayer (AgoraRtcMediaPlayerProtocol) class instead.
• setExternalAudioSourceVolume: Use adjustCustomAudioPublishVolume instead.
• getAudioFileInfo and onRequestAudioFileInfo: Use getDuration instead.
• onAudioDeviceTestVolumeIndication：Use onAudioVolumeIndication instead.
• setLocalPublishFallbackOption and onLocalPublishFallbackToAudioOnly: Rarely used in v3.7.0.
• RENDER_MODE_FILL(4) in RENDER_MODE_TYPE: This mode can cause image overstretch and is not recommended.
• The following enumerations in AUDIO_MIXING_REASON_TYPE: Rarely used in 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: Use onAudioMixingStateChanged 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 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.
• The replace parameter in startAudioMixing: Use publishMicrophoneTrack in the ChannelMediaOptions 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 adjustLoopbackRecordingVolume.
• onFirstLocalAudioFrame is changed to onFirstLocalAudioFramePublished.
• The fileSize member in LogConfig is renamed to fileSizeInKB.
• The options parameter in joinChannel[2/2] is changed to mediaOptions.
• The report_vad parameter in enableAudioVolumeIndication is changed to reportVad.

Agora SDK v4.x 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 Product overview.

This page introduces the main steps to upgrade the SDK from v3.x to v4.x, as well as the related changes.

Migration steps

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

1. Integrate the SDK

   See Get started for more information about integrating the v4.x SDK into your project.

2. Update the Agora code in your app

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

• 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.x but are not supported in v4.x. However, these functions are intended to be added in a future release.
• Removed APIs: Introduces APIs that were supported in v3.x but removed in v4.x. Most of these APIs have alternatives in v4.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 (v3.x to v4.0.0)

After upgrading from v3.x to v4.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.

Initialize engine

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.

Register event listener

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) {},
});

Multiple channels

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:

• The SDK provides the 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.
• Added a binary group 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:

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

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.

Media stream publishing control

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.

Warning codes

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:

• onConnectionStateChanged: 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.

Breaking changes (v4.0.0 Beta to v4.0.0)

SDK package name

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 Integrate the SDK.

Join channel

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.

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 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).

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

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, LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION in the localAudioStateChanged event reports that there is no permission to start the capture device, and LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION 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.

Remote media event triggering mechanism

In the following use-cases, the mechanism of triggering remote media events is changed:

• Use-case 1: When the host calls muteLocalAudioStream or muteLocalVideoStream outside the channel to change the publishing status of the local audio or video stream and then joins the channel.
• Use-case 2: When the host calls muteLocalAudioStream or muteLocalVideoStream 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 remoteAudioStateChangedOfUid or remoteVideoStateChangedOfUid callback, which reports the status changes of the remote host's audio or video streams.
• In v4.0.0, instead of the remoteAudioStateChangedOfUid or remoteVideoStateChangedOfUid callback, the local user receives the didAudioMuted or didVideoMuted 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 v3.7.0 and v4.0.0 SDKs:

• In v3.7.0, if you set publishLocalAudio in ChannelMediaOptions to false, it will stop publishing the local audio stream within the channel.
• In v4.0.0, if you set publishMicrophoneTrack in ChannelMediaOptions to false, 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.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:

Unsupported functions

Compared to v3.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

Screen sharing:

• videoSourceScreenCaptureInfoUpdated

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.
• setAudioMixingPlaybackSpeed: Use the relevant API under the IMediaPlayer class instead.
• getAudioFileInfo and requestAudioFileInfo: Use getDuration instead.
• audioDeviceTestVolumeIndication：Use onAudioVolumeIndication instead.
• setLocalPublishFallbackOption and localPublishFallbackToAudioOnly: 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.
• The channel parameter in takeSnapshot and snapshotTaken: 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.
• The replace parameter in startAudioMixing: Use publishMicrophoneTrack in the ChannelMediaOptions 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 onFirstLocalAudioFramePublished.
• The fileSize member in LogConfig is renamed to fileSizeInKB.
• The options parameter in joinChannel[2/2] is changed to mediaOptions.
• The report_vad parameter in enableAudioVolumeIndication is changed to reportVad.

agora_rtc_engine 6.x is a new version of the Flutter 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.

This page introduces the main steps to upgrade the SDK from 5.x to 6.x, as well as the related changes.

• Migration steps to upgrade your app to Voice Calling 6.x.

• What's changed between Voice Calling 5.x and 6.x.

Migration steps

This section introduces the main steps to upgrade the SDK from agora_rtc_engine 5.x to agora_rtc_engine 6.x

1. Integrate the SDK

See Get started for more information about integrating the agora_rtc_engine 6.x SDK into your project.

2. Update the Agora code in your app

The agora_rtc_engine 6.x SDK has optimized or modified the implementation of some functions, resulting in incompatibility with the agora_rtc_engine 5.x. 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 agora_rtc_engine 6.x compared to agora_rtc_engine 5.x in the following categories:

• 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 agora_rtc_engine 5.x but are not supported in agora_rtc_engine 6.x. However, these functions are intended to be added in a future release.
• Removed APIs: Introduces APIs that were supported in agora_rtc_engine 5.x but removed in agora_rtc_engine 6.x. Most of these APIs have alternatives in agora_rtc_engine 6.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 messages in the IDE, which is expected to take less time.

As stated above, you need to update the code of your app according to your business use-case.

Breaking changes

After upgrading from agora_rtc_engine 5.x to agora_rtc_engine 6.x, you may notice that 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.

Named parameters

For optimal code readability, agora_rtc_engine 6.x has changed the parameters of all methods with more than two parameters to named parameters. Take the joinChannel method as an example:

await agoraEngine.joinChannel(token: '', channelId: 'channelid', uid: 0, options: const ChannelMediaOptions());

Initialization

In agora_rtc_engine 6.x, the top-level createAgoraRtcEngine method is provided to create the RtcEngine object. Once created, call initialize to initialize it.

Rendering control

In agora_rtc_engine 6.x, SurfaceView are removed. AgoraVideoView is used instead for video rendering.

Multiple channels

In agora_rtc_engine 5.x, the SDK provides the RtcChannel and RtcChannelEventHandler classes to implement multi-channel control. The agora_rtc_engine 5.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.

agora_rtc_engine 6.x introduces the following changes:

• The SDK supports one RtcEngine instance to collect multiple audio and video sources at the same time and publish them to the remote users by setting RtcEngineEx and ChannelMediaOptions. 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.
• Added a binary group 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 RtcEngineEx class to implement more multi-stream functions.

By setting ChannelMediaOptions, agora_rtc_engine 6.x supports 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 use-cases. For example:

• Simultaneously publish multiple video streams captured by the camera and screen-sharing streams.
• Simultaneously publish a media player stream, a screen-sharing stream, and a video stream captured by the camera.
• 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 and RtcEngine of agora_rtc_engine 5.x are partially duplicated and overlap in their functionality, so agora_rtc_engine 6.x hides the RtcChannel and RtcChannelEventHandler classes. See the JoinMultiChannel sample project for more details on how to replace RtcChannel with joinChannel and ChannelMediaOptions. The expected migration cost is one day or less.

If you need to continue to use the RtcChannel and RtcChannelEventHandler 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 agora_rtc_engine 6.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.

Warning codes

In agora_rtc_engine 5.x, the SDK returns warning codes through the warning callbacks.

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

• onConnectionStateChanged: 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, agora_rtc_engine 6.x removes the warning callbacks.

In addition to the breaking changes listed here relative to agora_rtc_engine 5.x, agora_rtc_engine 6.x has a small number of breaking changes relative to the agora_rtc_engine: ^6.0.0-beta.2 release. For example:

• Replaces publishAudioTrack in ChannelMediaOptions with publishMicrophoneTrack.
• Removes joinChannelWithOptions.
• Adds options and remove info in joinChannel. See joinChannel for details.

If you used this feature in agora_rtc_engine: ^6.0.0-beta.2 and wish to upgrade to agora_rtc_engine 6.x, 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

Because the interactive streaming profile supports seamless switching from one-to-one calls to multi-user interaction, since agora_rtc_engine 5.x, 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 agora_rtc_engine 6.x, Agora also changed the default channel profile to ChannelProfileLiveBroadcasting (the interactive streaming profile).

Default log file

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

Fast channel switching

In agora_rtc_engine 5.x, you need to call switchChannel to quickly switch a channel.

In agora_rtc_engine 6.x, you can achieve the same switching speed as switchChannel in agora_rtc_engine 5.x by switching a channel through leaveChannel and joinChannel. Therefore, agora_rtc_engine 6.x removes switchChannel. If you call switchChannel to quickly switch a channel in agora_rtc_engine 5.x, you need to call leaveChannel to leave the current channel in agora_rtc_engine 6.x and joinChannel to join the second channel instead.

(Windows) Local audio and video recording

In agora_rtc_engine 5.x, if you want to enable local audio and video recording, you need to call the MediaRecorder.getMediaRecorder method to get the MediaRecorder object.

In agora_rtc_engine 6.x, if you want to enable local audio and video recording, you call the RtcEngine.getMediaRecorder method to get the MediaRecorder 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 agora_rtc_engine 5.x, call the configRhythmPlayer, and set publish to false.
• In agora_rtc_engine 6.x, 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 agora_rtc_engine 5.x and agora_rtc_engine 6.x, as follows:

• In agora_rtc_engine 5.x, 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 agora_rtc_engine 6.x, 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 agora_rtc_engine 5.x and agora_rtc_engine 6.x:

• In agora_rtc_engine 5.x, the SDK immediately stops reporting the local user's volume indication callback.
• In agora_rtc_engine 6.x, the SDK continues to report the local user's volume indication callback.

Device permissions

In agora_rtc_engine 5.x, AudioLocalError.DeviceNoPermission in localAudioStateChanged reports that there is no permission to start the capture device, and LocalVideoStreamError.DeviceNoPermission in localAudioStateChanged reports that there is no permission to start the video capture device.

In agora_rtc_engine 6.x, 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 agora_rtc_engine 5.x, you can call enableLastmileTest to start the network quality test. If you want to stop the network test, you need to call disableLastmileTest.
• In agora_rtc_engine 6.x, you can call startLastmileProbeTest to enable network quality testing. If you want to stop network testing, you need to call stopLastmileProbeTest.

Remote media event triggering mechanism

In the following use-cases, the mechanism of triggering remote media events is changed:

• Use-case 1: When the host calls muteLocalAudioStream or muteLocalVideoStream outside the channel to change the publishing status of the local audio or video stream and then joins the channel.
• Use-case 2: When the host calls muteLocalAudioStream or muteLocalVideoStream 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 the SDK between ^5.x and ^6.0.0 are listed as follow:

• In ^5.x, the local user receives the onRemoteAudioStateChanged or onRemoteVideoStateChanged callback, which reports the status changes of the remote host's audio or video streams.
• In ^6.0.0, instead of the onRemoteAudioStateChanged or onRemoteVideoStateChanged callback, the local user receives the onUserMuteAudio or onUserMuteVideo 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 in ChannelMediaOptions to false, it will stop publishing the local audio stream within the channel.
• In agora_rtc_engine: ^6.0.0, if you set publishMicrophoneTrack in ChannelMediaOptions to false, it will not only stop publishing the local audio stream within the channel but also stop local microphone capture.

Video information change event (iOS)

If the video capture device is adjusted to landscape or portrait mode during video capture, in agora_rtc_engine: ^5.x and agora_rtc_engine: ^6.0.0, the following differences exit in the video information change events reported by the SDK:

• In agora_rtc_engine: ^5.x, the rotation parameter in the videoSizeChanged callback displays the current device rotation information.
• In agora_rtc_engine: ^6.0.0, the rotation parameter in the onVideoSizeChanged callback is always 0.

Function gaps

This section introduces functions that were supported in agora_rtc_engine: Voice Calling 5.x but are no longer supported or behave inconsistently in agora_rtc_engine 6.x. Plans exist to support them or make them consistent in a future release.

Audio application scenarios

agora_rtc_engine 6.x reconstructs the audio application scenarios, which can replace most of the audio application scenarios of agora_rtc_engine 5.x. The following table shows the correspondence of audio application scenarios in the two releases:

Unsupported functions

Compared to agora_rtc_engine 5.x, some features are not supported or only partially supported in agora_rtc_engine 6.x. This section shows the APIs currently unsupported but for which support is planned in a future release.

Remote video stream fallback:

• setRemoteUserPriority

Screen sharing:

• onScreenCaptureInfoUpdated

Removed APIs

The agora_rtc_engine 6.x 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.
• userSuperResolutionEnabled: Use the remoteVideoStats member of the superResolutionType class instead.
• setAudioMixingPlaybackSpeed: Use the relevant API under the MediaPlayerController class instead.
• setExternalAudioSourceVolume: Use adjustCustomAudioPublishVolume instead.
• getAudioFileInfo and requestAudioFileInfo: Use getDuration instead.
• audioDeviceTestVolumeIndication: Use onAudioVolumeIndication instead.
• setLocalPublishFallbackOption and localPublishFallbackToAudioOnly: Rarely used in agora_rtc_engine 5.x.
• FILL(4) in VideoRenderMode: This mode can cause image overstretch and is not recommended.
• The following enumerations in AudioMixingReason: Rarely used in agora_rtc_engine 5.x:
  • StartedByUser
  • StartNewLoop
  • PausedByUser
  • ResumedByUser
• audioMixingFinished: Use onAudioMixingStateChanged 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 onSnapshotTaken: The parameter is redundant.
• setDefaultMuteAllRemoteVideoStreams: Use autoSubscribeVideo in the ChannelMediaOptions instead.
• setDefaultMuteAllRemoteAudioStreams: Use autoSubscribeAudio in the ChannelMediaOptions instead.
• LocalVideoStreamErrorScreenCaptureWindowNotSupported in LocalVideoStreamError: Deprecated in agora_rtc_engine 5.x.
• The replace parameter in startAudioMixing: Use publishMicrophoneTrack in the ChannelMediaOptions instead.

Naming changes

The naming changes in agora_rtc_engine 6.x cause error messages in the IDE when you compile your project. You need to update the code of your app according to each error message.

The main API and parameter name changes are as follows:

• (Windows and macOS) adjustLoopbackRecordingSignalVolume is changed to adjustLoopbackSignalVolume.
• firstLocalAudioFrame is changed to onFirstLocalAudioFramePublished.
• The fileSize member in LogConfig is renamed to fileSizeInKB.
• The report_vad parameter in enableAudioVolumeIndication is changed to reportVad.

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 Get started 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 use-case.

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

Initialize engine

In v3.7.0, the SDK provides the create and createWithContext 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.

Register event listener

Take onError as an example:

In v3.7.0, the SDK provides the addListener method to register event listener.

this.engine.addListener('Error', (errorCode) => {});

In v4.0.0, the SDK provides the registerEventHandler method to register event listener.

this.engine.registerEventHandler({
  onError(err: ErrorCodeType, msg: string) {},
});
this.engine.addListener('onError', (err: ErrorCodeType, msg: string) => {});

Multiple channels

In v3.7.0, the SDK provides the RtcChannel and RtcChannelEvents 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 provides the 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.
• Added a binary group 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:

• 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 and IRtcEngine of v3.7.0 are partially duplicated and overlap in their functionality, so v4.0.0 hides the RtcChannel and RtcChannelEvents classes. See the JoinMultiChannel sample project for more details on how to replace RtcChannel with joinChannel and ChannelMediaOptions. The expected migration cost is one day or less.

If you need to continue to use the RtcChannel and RtcChannelEvents 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 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.

Warning codes

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:

• onConnectionStateChanged: 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.

Breaking changes - v4.0.0 Beta to v4.0.0

This section introduces the breaking changes in upgrading the SDK from v4.0.0 Beta to v4.0.0.

SDK package name

After upgrading from v4.0.0 Beta to v4.0.0, the SDK package name has changed from react-native-agora-rtc-ng to react-native-agora, see Integrate the SDK.

Join channel

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;

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

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

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

Local audio and video recording

In v3.7.0, if you want to enable local audio and video recording, you need to call the startRecording method. 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 LocalAudioStateChanged reports that there is no permission to start the capture device, and LocalVideoStreamError in LocalVideoStateChanged 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.

Remote media event triggering mechanism

In the following use-cases, the mechanism of triggering remote media events is changed:

• Use-case 1: When the host calls muteLocalAudioStream or muteLocalVideoStream outside the channel to change the publishing status of the local audio or video stream and then joins the channel.
• Use-case 2: When the host calls muteLocalAudioStream or muteLocalVideoStream 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 remoteAudioStateChangedOfUid or remoteVideoStateChangedOfUid callback, which reports the status changes of the remote host's audio or video streams.
• In v4.0.0, instead of the remoteAudioStateChangedOfUid or remoteVideoStateChangedOfUid callback, the local user receives the didAudioMuted or didVideoMuted callback, which reports the changes in the remote host's publishing status.

Video information change event (iOS)

If the video capture device is adjusted to landscape or portrait mode during video capture, in v3.7.0 and v4.0.0, the following differences exist in the video information change events reported by the SDK:

• In v3.7.0, the rotation parameter in the videoSizeChanged callback displays the current device rotation information.
• In v4.0.0, the rotation parameter in the onVideoSizeChanged callback is always 0.

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:

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.
• UserSuperResolutionEnabled: Use the onRemoteVideoStats member of the superResolutionType class instead.
• setAudioMixingPlaybackSpeed: Use the relevant API under the IMediaPlayer class instead.
• getAudioFileInfo and RequestAudioFileInfo: Use getDuration instead.
• setLocalPublishFallbackOption and LocalPublishFallbackToAudioOnly: Rarely used in v3.7.0.
• The following enumerations in AudioMixingReason: Rarely used in v3.7.0.
  • AudioMixingReasonStartedByUser
  • AudioMixingReasonStartNewLoop
  • AudioMixingReasonPausedByUser
  • AudioMixingReasonResumedByUser
• AudioMixingFinished: Use onAudioMixingStateChanged 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 onSnapshotTaken: The parameter is redundant.
• setDefaultMuteAllRemoteVideoStreams: Use autoSubscribeVideo in the ChannelMediaOptions instead.
• setDefaultMuteAllRemoteAudioStreams：Use autoSubscribeAudio in the ChannelMediaOptions instead.
• The replace parameter in startAudioMixing: Use publishMicrophoneTrack in the ChannelMediaOptions 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:

• FirstLocalAudioFrame is changed to onFirstLocalAudioFramePublished.
• The fileSize member in LogConfig is renamed to fileSizeInKB.
• The report_vad parameter in enableAudioVolumeIndication is changed to reportVad.

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 Product overview.

This page introduces the main steps to upgrade the SDK from v3.x (v3.7.0.3 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

When you have downloaded the Agora v4.0.0 Unity SDK, you see a .unitypackage file which can be imported directly into your project in Unity Editor. Once the SDK is successfully integrated, you see an Agora-Video-SDK-Plugin directory in the Assets of your project.

Refer to the quickstart to integrate 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.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 is based on v3.x and introduces the main changes of v4.0.0 compared to v3.x in the following categories. You need to update the code of your app according to your business use-case.

• 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.x 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.x 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.x 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.x, the SDK provides the AgoraChannel class and Channel delegate to implement multi-channel control. The v3.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.

v4.0.0 introduces the following changes:

• The SDK supports one IRtcEngine instance to collect multiple audio and video sources at the same time and publish them to the remote users by setting IRtcEngineEx and ChannelMediaOptions.
• 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.
• You can simultaneously publish multiple sets of video streams captured by multiple cameras or screen sharing by setting publishSecondaryCameraTrack and publishSecondaryScreenTrack in ChannelMediaOptions. (Windows)

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.

AgoraChannel and IRtcEngine of v3.x are partially duplicated and overlap in their functionality, so v4.0.0 hides the IChannel and IChannelEventHandler classes. See the sample project for more details on how to replace AgoraChannel with JoinChannel and ChannelMediaOptions. The expected migration cost is one day or less.

If you need to continue to use the AgoraChannel class and Channel delegate, 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 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.

Warning codes

In v3.x, the SDK returns warning codes through the OnWarning 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:

• OnConnectionStateChanged: 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 OnWarning callback.

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

• In v4.0.0, replace publishAudioTrack in ChannelMediaOptions 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.

Behavior changes

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

Initialize the IRtcEngine

In v3.x, you obtain and initialize the IRtcEngine through the GetEngine (appId) or GetEngine (engineConfig) method.

In v4.0.0, you create an IRtcEngine instance through CreateAgoraRtcEngine or RtcEngine.Instance. You initialize the IRtcEngine through the Initialize method and at the same time, you can also set the channel profile and audio scenario, and config the log files through RtcEngineContext.

Register callback events

In v3.x, you can register callback events with C# delegates.

In v4.0.0, delegates are encapsulated in Agora.Rtc.RtcEngineEventHandler. You can also register callback events through the InitEventHandler method: you need to inherited Agora base classes and implement your own EventHandler class, and register an EventHandler instance through the InitEventHandler.

Release resources

If you need to release all the resources used by the Agora Unity SDK:

In v3.x, you need to call the Destroy method.

In v4.0.0, you need to call the Dispose method.

Channel profile

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

Default log file

In v3.x, 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.x, 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.x 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.x, you need to call LeaveChannel to leave the current channel in v4.0.0 and JoinChannel to join the second channel instead.

Media options

There are differences in the behavior of the SDK when setting channel media options while joining a channel between v3.7.0 and v4.0.0:

• In v3.7.0, if you set publishLocalAudio in ChannelMediaOptions to false, it will stop publishing the local audio stream within the channel.
• In v4.0.0, if you set publishMicrophoneTrack in ChannelMediaOptions to false, it will not only stop publishing the local audio stream within the channel but also stop local microphone capture.

Video information change event (iOS)

If the video capture device is adjusted to landscape or portrait mode during video capture, in v3.7.0 and v4.0.0, the following differences exist in the video information change events reported by the SDK:

• In v3.7.0, the rotation parameter in the OnVideoSizeChanged callback displays the current device rotation information.
• In v4.0.0, the rotation parameter in the OnVideoSizeChanged callback is always 0.

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.

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.x, 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.x and v4.0.0, as follows:

In v3.x, 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.x and v4.0.0:

In v3.x, 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.x, LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION in OnLocalAudioStateChanged reports that there is no permission to start the capture device, and LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION in OnLocalVideoStateChanged 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.x, 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.

Raw audio and video data

In v3.x, you can manage raw audio and video data through the APIs in AudioRawDataManager and VideoRawDataManager respectively.

In v4.0.0, you call the RegisterAudioFrameObserver or RegisterVideoFrameObserver in the IRtcEngine class to register an audio or video frame observer and monitor the audio or video data, or you can also inherit the IRtcEngine class to implement data monitoring.

Remote media event triggering mechanism In the following use-cases, the mechanism of triggering remote media events is changed:

• Use-case 1: When the host calls MuteLocalAudioStream or MuteLocalVideoStream outside the channel to change the publishing status of the local audio or video stream and then joins the channel.
• Use-case 2: When the host calls MuteLocalAudioStream or MuteLocalVideoStream 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 or OnRemoteVideoStateChanged callback, which reports the status changes of the remote host's audio or video streams.
• In v4.0.0, instead of the OnRemoteAudioStateChanged or OnRemoteVideoStateChanged callback, the local user receives the OnUserMuteAudio or OnUserMuteVideo callback, which reports the changes in the remote host's publishing status.

Function gaps

This section introduces functions that were supported in v3.x 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.x. The following table shows the correspondence of audio application scenarios in the two releases:

Unsupported functions

Compared to v3.x, 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

Screen sharing:

• OnScreenCaptureInfoUpdated

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:

• VideoRawDataManager: Use the APIs in the IVideoFrameObserver class instead.

• AudioRawDataManager: Use the APIs in the IAudioFrameObserver class instead.

• PacketObserver: Rarely used in v3.x.

• EnableFilpTextureApply: Agora recommends you implementing this function by yourself.

• SetGameFps: Agora recommends you implementing this function by yourself.

• VirtualBackgroundSourceEnabled: Use the return value of EnableVirtualBackground instead.

• OnUserSuperResolutionEnabled: Use the OnRemoteVideoStats member of the superResolutionType class instead.

• SetAudioMixingPlaybackSpeed: Use the relevant API under the IMediaPlayer class instead.

• SetExternalAudioSourceVolume: Use AdjustCustomAudioPublishVolume instead.

• GetAudioFileInfo and OnRequestAudioFileInfo: Use GetDuration instead.

• OnAudioDeviceTestVolumeIndication：Use OnAudioVolumeIndication instead.

• SetLocalPublishFallbackOption and OnLocalPublishFallbackToAudioOnly: Rarely used in v3.x.

• RENDER_MODE_FILL(4) in RENDER_MODE_TYPE: This mode can cause image overstretch and is not recommended.

• The following enumerations in AUDIO_MIXING_REASON_TYPE: Rarely used in 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: Use OnAudioMixingStateChanged 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 OnSnapshotTaken: The parameter is redundant.

• SetDefaultMuteAllRemoteVideoStreams: UseautoSubscribeVideo 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.x.

• The replace parameter in StartAudioMixing: Use publishMicrophoneTrack in the ChannelMediaOptions 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.

Namespace

• namespace agora_gaming_rtc is renamed as namespace Agora.Rtc

Classes

• AudioPlaybackDeviceManager and AudioRecordingDeviceManager are both included in IAudioDeviceManager
• VideoDeviceManager is changed to IVideoDeviceManager
• MediaRecorder is changed to IMediaRecorder
• MetadataObserver is changed to IMetadataObserver
• AgoraCallback is changed to IRtcEngineEventHandler

APIs and parameters

• AdjustLoopbackRecordingSignalVolume is changed to AdjustLoopbackSignalVolume.
• OnFirstLocalAudioFrame is changed to OnFirstLocalAudioFramePublished.
• The fileSize member in LogConfig is renamed to fileSizeInKB.
• The options parameter in JoinChannel[2/2] is changed to mediaOptions.
• The report_vad parameter in enableAudioVolumeIndication is changed to reportVad.

This page introduces the main steps to upgrade the Video SDK for Unreal Engine from v3.x (v3.5.0.4) to v4.x, as well as the related changes.

1. Integrate the SDK

To integrate Video SDK for Unreal Engine v4.2.1 into your project, see SDK quickstart.

2. Update the Agora code in your app

This section explains the main changes between Video SDK for Unreal Engine v3.x and v4.x. Use this information to upgrade your app.

Basic changes

Video SDK for Unreal Engine v4.x is based on Video SDK for C++ v4.x. First follow the steps in Migrate from Video SDK 3.x for Windows.

Other changes

• The agora::rtc::ue4::AgoraRtcEngine* interface class is renamed to agora::rtc::ue::RtcEngineProxy*. Rename agora::rtc::ue4::AgoraRtcEngine* to agora::rtc::ue::RtcEngineProxy* in your app.
• The v4.x SDK simplifies the implementation steps for video rendering. The OnTick function is handled by the VideoRenderingManager. Remove all code related to OnTick from your project files.
• To directly import Video SDK for Unreal Engine v4.x objects, include AgoraPluginInterface.h into all your classes. You may also need AgoraPlugin\Private\AgoraCppPlugin\include\AgoraHeaderBase.h.