Documentation
Video Call v4.0.0 Beta
Console Agora.io Community Submit ticket
English
search-icon

Migrate from 3.6.2 to 4.0.0 Beta

Last updated 2022/06/21 02:41:33

Agora SDK v4.0.0 Beta is a new 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.6.2 to v4.0.0 Beta, as well as the related changes.

Migration steps

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

1. Integrate the SDK

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

2. Update the Agora code in your app

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

  • Breaking changes: Introduces API compatibility changes that have a big impact. You need to spend significant time modifying the related implementation.
  • Behavior changes: Introduces changes caused by reasonable optimization of the SDK default behavior and API behavior. Less time is required to modify the related implementation, if any.
  • Function gaps: Introduces functions that were supported in v3.6.2 but are not supported in v4.0.0 Beta. However, these functions are intended to be added in a future release.
  • Removed APIs: Introduces APIs that were supported in v3.6.2 but removed in v4.0.0 Beta. Most of these APIs have alternatives in v4.0.0 Beta. 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.6.2 to v4.0.0 Beta, 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.6.2, the SDK provides the AgoraRtcChannel and AgoraRtcChannelDelegate classes to implement multi-channel control. The v3.6.2 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 Beta 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.6.2) 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.0.0 Beta 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 scenarios. 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.6.2 are partially duplicated and overlap in their functionality, so v4.0.0 Beta 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.6.2, the SDK uses the publishLocalAudio and publishLocalVideo members in AgoraRtcChannelMediaOptions to control the audio and video publishing state in the channel.

In v4.0.0 Beta, 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.6.2, 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 Beta 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.6.2 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:

Error codes and warning codes

In v3.6.2, the SDK returns error codes and warning codes through the didOccurError and didOccurWarning callbacks.

To facilitate locating and troubleshooting issues, v4.0.0 Beta 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.0.0 Beta 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.6.2, the default channel profile is AgoraChannelProfileCommunication (the communication profile).

Because the interactive live streaming profile supports seamless switching from one-to-one calls to multi-user interaction, since v3.0.0, Agora has changed the internal transmission protocol and the ability to resist poor network conditions in the communication profile to be consistent with the interactive live streaming profile. In v4.0.0 Beta, Agora also changed the default channel profile to AgoraChannelProfileLiveBroadcasting (the interactive live streaming profile).

Network quality callback

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

Default log file

In v3.6.2, 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 Beta modified the naming format to agorasdk.x.log, such as agorasdk.1.log. Additionally, v4.0.0 Beta adds the agoraapi.log file to record API logs.

Fast channel switching

In v3.6.2, you need to call switchChannel to quickly switch a channel.

In v4.0.0 Beta, you can achieve the same switching speed as switchChannel in v3.6.2 by switching a channel through leaveChannel and joinChannelByToken. Therefore, v4.0.0 Beta removes switchChannel. If you call switchChannel to quickly switch a channel in v3.6.2, see the QuickSwitchChannel sample project to update the code in your app.

Function gaps

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

Audio application scenarios

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

v3.6.2 v4.0.0 Beta
AgoraAudioScenarioDefault AgoraAudioScenarioDefault
AgoraAudioScenarioChatRoomEntertainment AgoraAudioScenarioChatRoom
AgoraAudioScenarioEducation AgoraAudioScenarioDefault
AgoraAudioScenarioGameStreaming AgoraAudioScenarioGameStreaming or AgoraAudioScenarioHighDefinition
AgoraAudioScenarioShowRoom AgoraAudioScenarioDefault
AgoraAudioScenarioChatRoomGaming AgoraAudioScenarioChatRoom
AgoraAudioScenarioIot AgoraAudioScenarioDefault
AgoraAudioScenarioMeeting None

Audio route

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

API v3.6.2 v4.0.0 Beta
setDefaultAudioRouteToSpeakerphone
  • You can only set the audio route before joining a channel.
  • This method only controls the initial state of the audio route and does not change the default audio route of the system. For example, regardless of whether you set the parameter of setDefaultAudioRouteToSpeakerphone to YES or NO, calling setEnableSpeakerphone(NO) changes the audio route to the earpiece.
    		•
  • You can set the audio route either before or after joining a channel.
  • This method is a steady API and can change the default audio route of the system. For example, after calling setDefaultAudioRouteToSpeakerphone(YES) to set the initial audio route to the speakerphone, calling setEnableSpeakerphone(NO) cannot change the audio route to the earpiece.
    		•
    setEnableSpeakerphone After connecting external playback devices such as Bluetooth and wired headphones, calling setEnableSpeakerphone cannot switch the audio route to the speakerphone or earpiece. Not recommended.

    Also, when an external playback device is removed, for example, by disconnecting the Bluetooth headset, the audio route change is different between v3.6.2 and v4.0.0 Beta:

    • In v3.6.2, 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.0.0 Beta, 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.6.2, 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.0.0 Beta, 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

    v4.0.0 Beta modifies the calling logic of enableVirtualBackground. Before calling enableVirtualBackground, you need to do the following:

    1. Integrate the AgoraVideoSegmentationExtension.xcframework dynamic library in the project.
    2. Call enableExtension("agora_segmentation", "PortraitSegmentation", "YES") before joining a channel to enable the virtual background extension.
    3. Call enableVideo to enable the video module.

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

    Image enhancement

    v4.0.0 Beta 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.6.2, some features are not supported or only partially supported in v4.0.0 Beta. 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
      getVideoFormatPreference is added in 4.0.0.beta-2.

    Audio and video statistics:

    • qualityChangedReason member in AgoraRtcRemoteAudioStats

      qualityChangedReason is added in 4.0.0.beta-2.

    • 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)
    • setExternalAudioSourceVolume

    Removed APIs

    The v4.0.0 Beta 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. See How to enable the video enhancement extensions.
    • virtualBackgroundSourceEnabled: Use the return value of enableVirtualBackground instead.
    • superResolutionEnabledOfUid: Use the superResolutionType member of the AgoraRtcRemoteVideoStats class instead.
    • setAudioMixingPlaybackSpeed: Use setPlaybackSpeed instead.
    • setAudioMixingDualMonoMode: Use setAudioDualMonoMode instead.
    • getEffectCurrentPosition: Use getPosition instead.
    • setEffectPosition: Use seekToPosition instead.
    • getEffectDuration: Use getDuration instead.
    • getAudioFileInfo and didRequestAudioFileInfo: Use getDuration 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.6.2.
    • AgoraVideoRenderModeFill(4) in AgoraVideoRenderMode: This mode might cause image overstretch and is not recommended.
    • The following enumerations in AgoraAudioMixingReasonCode: Rarely used in v3.6.2.
      • AgoraAudioMixingReasonStartedByUser
      • AgoraAudioMixingReasonOneLoopCompleted
      • AgoraAudioMixingReasonStartNewLoop
      • AgoraAudioMixingReasonAllLoopsCompleted
      • AgoraAudioMixingReasonStoppedByUser
      • AgoraAudioMixingReasonPausedByUser
      • AgoraAudioMixingReasonResumedByUser
    • rtcEngineLocalAudioMixingDidFinish: Rarely used in v3.6.2.
    • The info parameter in joinChannelByToken [2/2]: This parameter is optional and rarely used in v3.6.2.
    • 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: The parameter is redundant.

    Naming changes

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

    • 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.
    • localAudioMixingStateDidChanged is changed to audioMixingStateChanged.