Release Notes

This page provides the release notes for the Agora Video SDK for Android.

v3.7.1

v3.7.1 was released on August 4, 2022.

Compatibility changes

To facilitate troubleshooting, as of this release, the SDK no longer catches exceptions that are thrown by your own code implementation when triggering callbacks in the IRtcEngineEventHandler class. You need to catch and handle the exceptions yourself; otherwise, it can cause a crash.

Improvements

1. Super resolution (beta)

This release deprecates the previous enableRemoteSuperResolution method, and adds a method with the same name to support super resolution. If the original resolution of a remote user's video is a × b, the local user's device can render the remote video at a resolution of 2a × 2b after you enable this feature.

Compared to the deprecated method, the new enableRemoteSuperResolution method adds a parameter mode that can be set as either of following values:

• SR_MODE_MANUAL(0): Enables super resolution for the remote user you specify.
• SR_MODE_AUTO(1): Enables super resolution for the remote user corresponding to the largest rendering window in the channel.
  Before using super resolution, ensure that you have integrated the libagora_super_resolution_extension.so dynamical library. For other requirements, see the enableRemoteSuperResolution documentation.

2. Co-hosting across channels

This release enhances the connection mechanism between the SDK and the server of co-hosting across channels and therefore reduces the failure rate.

Fixed issues

• Occasional crashes occurred.
• The captured volume was too low on specific devices such as Samsung Galaxy S20+ and Note10+.
• When the local user switched the front and rear cameras after enabling image enhancement, remote users occasionally saw the local user's video upside down for an instant.
• The local user received the onRemoteAudioStateChanged(2,6) callback after disconnecting from and reconnecting to a network even though the remote user had not changed the audio state.
• gatewayRtt reported by the onRtcStats callback was inaccurate when the network latency was too high or the router did not respond to ICMP packets.
• The uplink network quality reported by the onNetworkQuality callback was inaccurate for the user who was sharing a screen.
• Occasionally, it took users longer than normal to join a channel for the first time.
• When the local user shared audio played by a third-party app using the screen sharing feature, remote users heard echoes.

API changes

Added

• enableRemoteSuperResolution
• SR_STATE_REASON_INSUFFICIENT_PERFORMANCE(4)
• VBS_STATE_REASON_INSUFFICIENT_PERFORMANCE(4)

Deprecated

• enableRemoteSuperResolution

v3.7.0.2

v3.7.0.2 was released on June 6, 2022.

This release fixed the following issues:

• Compiling or running a project failed after you integrated the screen sharing extension AgoraScreenShareExtension and set targetSdkVersion as 31. (Android)
• Native clients saw video freeze on web clients when web clients published H.264 video streams.

v3.7.0.1

v3.7.0.1 was released on May 9, 2022.

This release fixed echoes and compatibility issues that occasionally occurred on some devices.

v3.7.0

v3.7.0 was released on April 11, 2022.

Compatibility changes

1. JND library integration change

As of v3.7.0, the JND library is statically compiled in the SDK by default and no longer provided as an extension library. If you have integrated the JND library, remove the JND extension library from your project dependencies and recompile your project when upgrading to v3.7.0. For the description of the JND library, see extension libraries.

2. Changes to the implementation fields of dynamic libraries

When you integrate the Android SDK with Maven Central, you can reduce the size of your app after integrating the SDK by modifying the implementation field in dependencies in the /Gradle Scripts/build.gradle(Module: .app) file to specify the desired dynamic libraries. See Reduce App Size for details.

To align the implementation fields of the same dynamic library in the Video and Audio SDKs, this release changes the implementation fields of the following dynamic libraries:

Dynamic libraries	implementation field (v3.6.2)	implementation field  （v3.7.0 and later)
Noise suppression library: libagora_ai_denoise_extension.so	The Video SDK: io.agora.rtc:full-ains The Voice SDK: io.agora.rtc:voice-ains	io.agora.rtc::ains
Full-format audio decoding library: libagora_full_audio_format_extension.so	The Video SDK: io.agora.rtc:full-full-audio-format The Voice SDK: io.agora.rtc:voice-full-audio-format	io.agora.rtc:full-audio-format

New features

1. Spatial audio effect

This release adds the feature of spatial audio effect, which can add a sense of space to remote users' audio and simulate the audio transmission process in the real world. This enables the local user to hear remote users with the spatial audio effect.

To use this feature, contact support@agora.io.

2. Screen sharing

This release supports screen sharing on this platform and provides the startScreenCapture, stopScreenCapture, and updateScreenCaptureParameters methods for this purpose. For the implementation method, see Share the Screen.

3. Local voice pitch

This release adds the enableLocalVoicePitchCallback method and the onLocalVoicePitchInHz callback, to allow the SDK to report the voice pitch of the local user at the set time interval to the app.

4. Reporting the first remote video frame rendered

This release adds the onFirstRemoteVideoFrame callback to the IRtcChannelEventHandler class to report to the local user that the first video frame of the remote user has been rendered in a multichannel scenario. You can also get the remote user ID, the width and height (in pixels) of the video, and the time (in milliseconds) to render the first video frame from this callback.

5. Reporting the user role switch failure

This release adds the onClientRoleChangeFailed callback to report the reason for a user role switch failure and the current user role in the interactive live streaming.

6. Reasons for connection state changes

To help users better understand the cause of connection state changes, this release adds the following enumerators:

• CONNECTION_CHANGED_SAME_UID_LOGIN(19): Join the same channel from different devices using the same user ID.
• CONNECTION_CHANGED_TOO_MANY_BROADCASTERS(20): The number of hosts in the channel reaches the upper limit. This enumerator is reported only after the support for 128 hosts is enabled.

Improvements

1. Channel capacity improvement

As of this release, a single channel can support up to 128 concurrent online hosts, who can publish audio and video streams at the same time. The number of audience members in a channel is unlimited. Each host or audience member can subscribe to a maximum of 50 hosts at the same time.

To experience this improvement, contact support@agora.io.

2. Virtual background

Test results and user feedback show that the effect of the virtual background feature improves when a user is against a complex background and adopts a more casual pose. As a result, virtual background is converted from a beta feature to an official feature as of v3.7.0.

3. A new version of noise suppression

Agora has added the option of using a new version of noise suppression to further improve audio quality. To experience this feature, contact support@agora.io

4. playEffect improvements

This release improves the internal implementation logic of playEffect to avoid blocking and reduce freezing when playing an audio effect file.

5. Transmission upgrade

This release upgrades transmission protocols and algorithms to enhance the SDK's ability to counter poor network conditions. At the same time, this release optimizes the scalable video coding capability for multi-user video scenarios to improve user video experience.

API changes

Added

• startScreenCapture
• stopScreenCapture
• updateScreenCaptureParameters
• enableLocalVoicePitchCallback
• onLocalVoicePitchInHz
• onFirstRemoteVideoFrame in the IRtcChannelEventHandler class
• onClientRoleChangeFailed
• CONNECTION_CHANGED_SAME_UID_LOGIN(19) and CONNECTION_CHANGED_TOO_MANY_BROADCASTERS(20)
• The following error codes:
  • ERR_SCREEN_CAPTURE_SYSTEM_NOT_SUPPORTED(2)
  • ERR_SCREEN_CAPTURE_SYSTEM_AUDIO_NOT_SUPPORTED(3)
  • ERR_SCREEN_CAPTURE_PERMISSION_DENIED(16)

Deprecated

• Warning code WARN_SET_CLIENT_ROLE_NOT_AUTHORIZED. Use reason reported in onClientRoleChangeFailed instead.

v3.6.2

v3.6.2 was released on February 22, 2022.

New features

1. Removing extension libraries when using Maven Central

Extension libraries are dynamic libraries that can be optionally integrated into a project. As of v3.6.2, when you integrate the Android SDK with Maven Central, Agora supports reducing the size of your app after integrating the SDK by modifying dependencies in the /Gradle Scripts/build.gradle(Module: .app) file to specify the desired dynamic libraries and exclude unnecessary extension libraries. For details about the sample code and the implementation field in dependencies, see Reduce App Size.

2. Video enhancement

In addition to the image enhancement feature, Agora adds support for more video enhancement features:

• Video noise reduction: This feature reduces video noise and improves video quality. You can use the setVideoDenoiserOptions method to enable/disable video noise reduction and set the options of the video noise reduction effect.
• Low-light enhancement: This feature adaptively adjusts the brightness value of the video captured in situations with low or uneven lighting, such as backlit, cloudy, or dark scenes. It restores or highlights the image details and improves the overall visual effect of the video. You can use the setLowLightEnhanceOptions method to enable/disable low-light enhancement and set the options of the low-light enhancement effect.
• Color enhancement: This feature intelligently adjusts video characteristics such as saturation and contrast to enhance the video color richness and color reproduction, making the video more vivid. You can use the setColorEnhanceOptions method to enable/disable color enhancement and set the options of the color enhancement effect.

3. Loading .so files dynamically

This release adds the setAgoraLibPath method for setting the directory of .so files. After a successful method call, the SDK dynamically loads .so files based on your specified directory when the app is running. This feature can help reduce the size of your app package. For detailed instructions, see Reduce App Size.

4. Passing in native TextureView

This release adds support for directly using Android native TextureView. You can pass a native TextureView directly to VideoCanvas.view instead of calling CreateTextureView to get a TextureView object and then passing it to VideoCanvas.view. After setting VideoCanvas, you can call setupLocalVideo and setupRemoteVideo to initialize the local and remote user views.

Improvements

1. Cloud proxy

To enrich application scenarios of the Agora Cloud Proxy, this release updates the cloud proxy types as follows:

• Changes the meaning of TRANSPORT_TYPE_NONE_PROXY(0) from "Do not use the cloud proxy" to "Automatic mode". In this mode, the SDK attempts a direct connection to SD-RTN™ and automatically switches to TLS 443 if the attempt fails. As of v3.6.2, the SDK has this mode enabled by default.
• Adds TRANSPORT_TYPE_TCP_PROXY(2), which is the TCP (encrypted) mode. In this mode, the SDK always transmits data over TLS 443.

In addition, this release adds the onProxyConnected callback to report the proxy connection state. For example, when a user calls setCloudProxy and joins a channel successfully, the SDK triggers this callback to report the user ID, the proxy type connected, and the time elapsed from the user calling joinChannel until this callback is triggered.

2. Audio recording

This release extends startAudioRecording with support for setting recording with dual channels and higher audio quality.

• By adding recordingChannel to AudioRecordingConfiguration, it enables you to set the recorded audio channel to be mono or dual. Because the actual recorded audio channel is related to the captured audio channel and the integration scheme affects the final recorded audio channel, contact technical support for assistance with stereo recording using startAudioRecording.
• By adding AUDIO_RECORDING_QUALITY_ULTRA_HIGH(3) to AudioRecordingConfiguration.recordingQuality, it enables you to set the recorded audio quality to ultra-high. Ultra-high quality is the highest quality available in recordingQuality. When you record a 10-minute AAC audio file at a sample rate of 32,000 Hz and ultra-high quality, the file size is approximately 7.5 MB.

3. Music file playback

This release optimizes the experience of calling startAudioMixing to play music files as follows:

• Reduces issues of audio freezes or no audio when playing music files.
• Increases the accuracy of the audio duration reported by getAudioFileInfo.
• Supports more audio file formats. See Which audio file formats does the Agora RTC SDK support.

If you want to experience these improvements, ensure that you have integrated the libagora-full-audio-format-extension.so dynamic library. Given the large size of this library, if you have limitations on app size and do not need these improvements, you can remove this dynamic library when integrating the SDK. For more instructions, see Reduce App Size.

Fixed issues

This release fixed the issue that under certain circumstances, zipping noises occurred when using a Redmi 4A phone for live streaming.

API changes

Added

• setVideoDenoiserOptions
• setLowLightEnhanceOptions
• setColorEnhanceOptions
• setAgoraLibPath
• recordingChannel in AudioRecordingConfiguration
• AUDIO_RECORDING_QUALITY_ULTRA_HIGH(3) in AudioRecordingConfiguration.recordingQuality
• onProxyConnected
• TRANSPORT_TYPE_TCP_PROXY(2)

Modified

• The behavior of TRANSPORT_TYPE_NONE_PROXY(0)

v3.6.1.1

v3.6.1.1 was released on January 16, 2022.

This release fixed the following audio issue:

When an end user muted and unmuted audio from an application using the Agora Web SDK, end users using an application with Native SDK version 3.6.0 might not hear audio from this end user.

v3.6.1

v3.6.1 was released on January 14, 2022.

Improvements

This release provides the following improvements:

• After a remote user using a Mac device leaves a channel due to the leaveChannel method call, network interruption, or other reasons, the local user sees the remote view stay on the last video frame instead of the remote view directly disappearing as in previous versions.
• Adds the fallback to software encoding when hardware encoding fails for the custom video in texture format, in order to improve the usability of video functions.

Fixed issues

This release fixed the following issues:

• The CDN live streaming failed because of the abnormal resolution of the RTMP streaming URL with a port number.

• On some devices, occasional crashes occurred after you enabled the virtual background.

• On some devices, occasional noises occurred when you used OpenSL.

• Occasional crashes occurred.

v3.6.0.1

v3.6.0.1 was released on December 10, 2021.

This release fixed the issue that v3.6.0 incorrectly renamed the dynamic library libagora_fdkaac.so to libagora_fdkaac_extension.so.

v3.6.0

v3.6.0 was released on December 7, 2021.

Compatibility changes

Media Push

To reduce the difficulty of integrating Media Push, this release optimizes the API design of Media Push and improves the handling of network issues within Media Push clients and servers. You can experience the optimized Media Push functionality with the following new methods:

• startRtmpStreamWithoutTranscoding: Starts pushing media streams to a CDN without transcoding. This method works the same as the old method addPublishStreamUrl(false).
• startRtmpStreamWithTranscoding: Starts pushing media streams to a CDN and sets the transcoding configuration. This method works the same as calling the old methods setLiveTranscoding and addPublishStreamUrl(true) in sequence.
• updateRtmpTranscoding: Updates the transcoding configuration. This method works the same as the non-first call to the old method setLiveTranscoding.
• stopRtmpStream: Stops pushing media streams to a CDN. This method works the same as the old method removePublishStreamUrl.

This release deprecates three old methods for Media Push: addPublishStreamUrl, setLiveTranscoding, and removePublishStreamUrl. Agora recommends that you use the new methods for Media Push and update your code logic by referring to Media Push.

Also, as of this release, whether you use the new or old methods for Media Push, you can experience the following improvements:

• Reporting streaming states, errors, and events:

  • In the RTMP_STREAM_PUBLISH_STATE state code, adding RTMP_STREAM_PUBLISH_STATE_DISCONNECTING(5): The SDK is disconnecting from the Agora streaming server and CDN. When you call remove or stop to stop the streaming normally, the SDK reports the streaming state as DISCONNECTING, IDLE in sequence.

  • Adding the following to the RTMP_STREAM_PUBLISH_ERROR error code:

    • RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER(11): The user role is not host, so the user cannot use the Media Push function. Check your application code logic.
    • RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM(13): The update or setLiveTranscoding method is called to update the transcoding configuration in a scenario where there is streaming without transcoding. Check your application code logic.
    • RTMP_STREAM_PUBLISH_ERROR_NET_DOWN(14): Errors occurred in the host's network.
    • RTMP_STREAM_PUBLISH_ERROR_INVALID_APPID(15): Your App ID does not have permission to use the Media Push function. Refer to Prerequisites to enable the Media Push permission.

  • Adding the following to the RTMP_STREAMING_EVENT event code:

    • RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT(3): The feature is not supported.
    • RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN(4): Reserved.
    To ensure the quality of the Media Push, make sure to handle the business logic according to the state code, error code, and event code.

• Adding multiple watermarks and background images during streaming with transcoding: This is achieved by adding addWatermark and addBackgroundImage to the LiveTranscoding class.

• Setting the layer number and transparency of each watermark and background image during streaming with transcoding: This is achieved by adding zOrder and alpha to the AgoraImage structure.

• Using the HE-AAC v2 audio codec during streaming with transcoding: This is achieved by adding HE_AAC_V2 to AudioCodecProfileType.

Improvements

1. Image enhancement

This release updates the Agora image enhancement algorithm to improve the image enhancement effects that you can enable by calling setBeautyEffectOptions. To balance these image enhancement effects, this release changes the default value of lighteningLevel from 0.7 to 0.6 and adds sharpnessLevel to the BeautyOptions structure to support setting the sharpness level.

As of this release, ensure that you have integrated the libagora_video_process_extension.so dynamic library before calling setBeautyEffectOptions; otherwise, you cannot experience the optimized image enhancement effects and sharpness adjustment brought out by the updated Agora image enhancement algorithm, but only the image enhancement effects brought out by the older Agora image enhancement algorithm.

2. Rendering of the first remote video frame

This release speeds up rendering of the first remote video frame under poor network conditions to enhance user video experience.

Fixed issues

This release fixed the following issues:

• The SDK caused the Bluetooth to restart and triggered the prompt to turn off the bluetooth when the SDK detected incorrect settings of the Bluetooth.
• Occasionally, the video received by remote users froze after you enabled media stream encryption.
• When you were playing an original song, calling setAudioMixingPitch to adjust the pitch caused the played song to switch to accompaniment.
• In the EDUCATION scenario, occasionally the volume became unstable when the user called enableLocalAudio to enable and disable the local audio capture.

API changes

Added

• startRtmpStreamWithoutTranscoding

• startRtmpStreamWithTranscoding

• updateRtmpTranscoding

• stopRtmpStream

• RTMP_STREAM_PUBLISH_STATE_DISCONNECTING(5) in the state parameter of onRtmpStreamingStateChanged

• The followin code in the errCode parameter of onRtmpStreamingStateChanged:

  • RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER(11)
  • RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM(13)
  • RTMP_STREAM_PUBLISH_ERROR_NET_DOWN(14)
  • RTMP_STREAM_PUBLISH_ERROR_INVALID_APPID(15)

• The following code in the errorparameter of onRtmpStreamingEvent:

  • RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT(3)
  • RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN(4)

• The following methods in the LiveTranscoding class:

  • addWatermark
  • removeWatermark
  • getWatermarkList
  • addBackgroundImage
  • removeBackgroundImage
  • getBackgroundImageList

• zOrder and alpha in the AgoraImage class

• HE_AAC_V2 in AudioCodecProfileType

• setAVSyncSource

• sharpnessLevel in the BeautyOptions class

Modified

• Changed the default value of lighteningLevel from 0.7 to 0.6

v3.5.2

v3.5.2 was released on November 25, 2021.

Compatibility changes

Error codes returned when the request to join a channel is rejected

To more accurately report the reason for the failure to join a channel, as of this release, the SDK returns the error code -17 (ERR_JOIN_CHANNEL_REJECTED) in the return value of the joining channel method in the following situations:

• When a user who has already joined an RtcEngine channel calls the joining channel method of the RtcEngine class with a valid channel name.

• When a user who has already joined an RtcChannel channel calls the joining channel method of this RtcChannel object.

In the SDK earlier than v3.5.2, when the above errors occur, the SDK might report the error code 17 through the onErrorcallback, or return the error code -5 (ERR_REFUSED) in the return value of the joining channel method.

New features

1. Audio and video recording on the client

To enable users to record local audio and video on their client, this release adds the AgoraMediaRecorder class, which supports recording the following content:

• The audio captured by the local microphone and encoded in AAC format by the SDK.
• The video captured by the local camera and encoded by the SDK.

The generated recording files are saved in the local path specified by the user.

After successfully initializing the RtcEngine object, you can call the following methods and callbacks in the AgoraMediaRecorder class to implement the local audio and video recording function:

• getMediaRecorder: Registers the callbacks and gets the AgoraMediaRecorder object.
• startRecording: Sets the recording content, duration, format of generated files, and callback interval, and enables the local audio and video recording.
• stopRecording: Stops recording the local audio and video.
• release: Releases the AgoraMediaRecorder object.
• onRecorderStateChanged: Occurs when the recording state changes.
• onRecorderInfoUpdated: Occurs when the recording information is updated.

2. Video snapshot

This release adds the takeSnapshot method for taking a snapshot of a video stream from the specified user, generating a JPG image, and saving it to the specified path. After a successful method call, the SDK triggers the onSnapshotTaken callback to report whether the snapshot is successfully taken as well as the details of the snapshot taken.

3. Testing audio and video call loop

To check whether the local audio device, video device, and network conditions can guarantee the proper sending and receiving of audio and video streams, this release adds the startEchoTest [3/3] method. You can call this method before joining a channel to test whether the loop of a user's audio and video devices and network conditions are working properly.

Compared to startEchoTest [2/3], startEchoTest [3/3] can test video devices and secure the test, but cannot support setting the time interval for reporting test results.

Improvements

1. Performance improvements

This release slightly reduces CPU usage in video scenarios by optimizing the FEC (Forward Error Correction) codec.

2. Experience improvements

This release improves video sharpness and smoothness under poor network conditions by optimizing the congestion control algorithm.

Fixed issues

This release fixed the following issues:

• The video bitrate failed to climb when a user joined a channel in poor network conditions with high packet loss.
• The video sharpness and smoothness degraded significantly due to a cliff-like drop in video bitrate under certain poor network conditions.
• Remote users heard slightly unsynchronized voice and music when a user called startAudioMixing on some Android devices.
• After a local user called enableDualStreamMode(false), a dual stream (high-quality and low-quality video stream) was nevertheless sent when the user switched from custom video capture using setVideoSource with the custom video source in the SCREEN type to SDK capture.

API changes

This release adds the following APIs:

• startEchoTest [3/3]

• getMediaRecorder

• onRecorderStateChanged

• onRecorderInfoUpdated

• startRecording

• stopRecording

• release

• takeSnapshot

• onSnapshotTaken

v3.5.1

v3.5.1 was released on October 14, 2021.

New features

1. Super resolution (beta)

To effectively boost the resolution of a remote user's video seen by the local user, this release adds support for the super resolution feature. You can call enableRemoteSuperResolution to enable super resolution. The SDK triggers the onUserSuperResolutionEnabled callback to report whether this feature has been successfully enabled. If it is not enabled successfully, use the reason code to troubleshoot issues.

2. Background blurring

To enrich the virtual background effects, this release adds support for setting background blur when a user enables the virtual background function by calling enableVirtualBackground. You need to set the type of the custom background image as BACKGROUND_BLUR and set blur_degree according to the degree of blurring that the user desires.

3. Enabling device flash

To support calling the C++ APIs to enable the flash of a device on Android platform, this release adds the following APIs to C++:

• isCameraTorchSupported: Determine whether the device supports enabling the flash.
• setCameraTorchOn: Set whether to enable the flash.

4. Pausing and resuming the media stream relay across channels

In order to enable the host to quickly pause or resume a cross-channel media stream relay, this release adds the following methods and event code:

• pauseAllChannelMediaRelay: Pauses the media stream relay to all destination channels.
• resumeAllChannelMediaRelay: Resumes the media stream relay to all destination channels.
• RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS (12): The SDK successfully pauses relaying the media stream to destination channels.
• RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED (13): The SDK fails to pause relaying the media stream to destination channels.
• RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS (14): The SDK successfully resumes relaying the media stream to destination channels.
• RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED (15): The SDK fails to resume relaying the media stream to destination channels.

After a successful method call of pauseAllChannelMediaRelay or resumeAllChannelMediaRelay, the SDK triggers the onChannelMediaRelayEvent callback to report whether the media stream relay is successfully paused or resumed.

5. Pushing the external audio frame to a specified position

To meet the different processing requirements of external audio frames in different scenarios, this release deprecates pushExternalAudioFrame [1/2] and adds pushExternalAudioFrame [2/2] with sourcePos instead. You can push the external audio frame to one of three positions: after audio capture, before audio encoding, or before local playback. For example, in the KTV scenario, you can push the singing voice to after audio capture, and push the accompaniment to before audio encoding, so that the singing voice is processed by the SDK audio module, but the accompaniment is not affected by the SDK audio module.

This release also adds setExternalAudioSourceVolume, which enables you to set the volume of external audio frames at a specified position.

6. Advanced settings of the music file

To set the playback speed, audio track, and channel mode of a music file, this release adds the following methods:

• setAudioMixingPlaybackSpeed: Sets the playback speed of the current music file. Agora recommends a value range of [50,400], where 100 represents the original speed.
• getAudioTrackCount: Gets the number of audio tracks of the current music file.
• selectAudioTrack: Specifies the playback audio track of the current music file. The range of index is [0, getAudioTrackCount()).
• setAudioMixingDualMonoMode: Sets the channel mode of the current music file to original mode, left channel mode, right channel mode, or mixed channel mode.

7. Getting audio file information

To get the information of any audio file, this release deprecates getAudioMixingDuration and adds getAudioFileInfo instead. After joining a channel, you can call getAudioFileInfo and get information such as duration for the specified audio file in onRequestAudioFileInfo.

Improvements

1. Adapting OpenSL

This release adapts OpenSL to reduce the audio delay. It also adds a blacklist to disable OpenSL and enable Java adm on some devices that do not support OpenSL in order to improve the stability of audio functions.

2. Identification and quality testing for 5G mobile networks

This release adds identification and connection quality testing for 5G mobile networks:

• Adds NETWORK_TYPE_MOBILE_5G (6). When the local network changes to 5G, the SDK triggers the onNetworkTypeChanged callback to report this network connection type.
• Supports calling enableLastmileTest or startLastmileProbeTest to test the connection quality of the 5G mobile network.

3. Other improvements

This release also provides the following improvements:

• Adds continuous optimization of the portrait edge effect of the virtual background.
• After enabling noise suppression, the audio experience is improved when using some Bluetooth headsets.

Fixed issues

This release has fixed the following issues:

• In the GAME_STREAMING scenario, occasional echo or noise that was caused by inaccurate music detection occurred.
• The local user occasionally saw the remote user with a short black screen after the remote user called enableLocalVideo(false), enableLocalVideo(true) to disable and enable local video capture or called muteLocalVideoStream(true), muteLocalVideoStream(false) to stop and resume sending local video in sequence within a few seconds.
• Updating the transcoding layout in Media Push occasionally failed under certain circumstances.
• When the local user called muteAllRemoteAudioStreams and received onRemoteAudioStateChanged (REMOTE_AUDIO_REASON_LOCAL_MUTED), onRemoteAudioStateChanged (REMOTE_AUDIO_REASON_REMOTE_MUTED) was incorrectly received after 15 seconds.
• When using an app integrated with the SDK for real-time communication, if a user answered a system call and returned to the app, the audio route of the SDK changed. For example, when the audio was played through the speaker in the app, if a user answered a system call through the earpiece and returned to the app, the audio route of the SDK changed to the earpiece.
• Crashes occasionally occurred in audio scenarios.
• As of v3.4.5, the return value was inaccurate when you called joinChannel multiple times in a row.
• When a user with the audio profile MUSIC_HIGH_QUALITY_STEREO (5) talked to a user with another audio profile, the latter was likely to hear a zipping noise.
• When the host used a specific low-end device under certain circumstances, the audience watching the host's video occasionally experience lag.
• Under certain circumstances, when the sender used certain Xiaomi or Redmi devices, the receiver occasionally saw a mosaic square on the received video.
• When the sender used certain Android emulators, the local video or the video received by the receiver was abnormal.
• The method call of setExternalAudioSource before joining the channel did not take effect.
• When a Bluetooth headset and a wired headset were connected to the audio playback device at the same time, the SDK did not trigger onAudioRouteChanged after plugging and unplugging the wired headset multiple times.
• The SDK additionally triggered the onLocalAudioStateChanged callback to report LOCAL_AUDIO_STREAM_STATE_CAPTURING(1) when you called enableLocalAudio(false) after joining a channel.

API changes

Added

• enableRemoteSuperResolution
• onUserSuperResolutionEnabled
• isCameraTorchSupported (C++)
• setCameraTorchOn (C++)
• blur_degree and BLUR_DEGREE in VirtualBackgroundSource
• BACKGROUND_BLUR in backgroundSourceType
• pushExternalAudioFrame [2/2]
• setExternalAudioSourceVolume
• setAudioMixingPlaybackSpeed
• getAudioTrackCount
• selectAudioTrack
• setAudioMixingDualMonoMode
• pauseAllChannelMediaRelay
• resumeAllChannelMediaRelay
• The following RELAY_EVENT enumerators:
  • RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS
  • RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED
  • RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS
  • RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED
• getAudioFileInfo
• onRequestAudioFileInfo
• NETWORK_TYPE_MOBILE_5G(6)

Deprecated

• pushExternalAudioFrame [1/2]
• getAudioMixingDuration

v3.5.0.4

v3.5.0.4 was released on September 26, 2021.

Improvements

To improve audio quality when a user uses a Bluetooth headset, this release optimizes the logic for selecting Bluetooth profiles and volume types.

• Bluetooth profile: As of this release, the Bluetooth profile used by the SDK is only affected by the user role.

  • If a user in the communication profile or a host in the interactive live streaming profile uses a Bluetooth headset, the Bluetooth headset captures and plays audio through the Hands-Free Profile (HFP).
  • If an audience member in the interactive live streaming profile uses a Bluetooth headset, the Bluetooth headset plays audio through the Advanced Audio Distribution Profile (A2DP).

• Volume type: This release regulates the volume type. When a user uses a Bluetooth headset, the SDK uses the following volume type:

  Audio scenario	User in the communication profile/Host in the interactive live streaming profile	Audience in the interactive live streaming profile
  DEFAULT	In-call volume	Media volume
  CHATROOM_GAMING	In-call volume	In-call volume
  GAME_STREAMING	In-call volume	Media volume
  CHATROOM_ENTERTAINMENT	In-call volume	In-call volume
  EDUCATION	In-call volume	Media volume
  SHOWROOM	In-call volume	Media volume
  MEETING	In-call volume	Media volume

Fixed issues

This release fixed the following issues:

• When you used raw video data, the SDK incorrectly triggered the onRenderVideoFrame and onRenderVideoFrameEx callbacks when capturing a local video frame to be rendered.
• Occasional crashes occurred when you used raw video data.
• On some Xiaomi devices, the user could not use the device's volume button to adjust the volume after calling setEnableSpeakerphone.
• On some devices, the main thread got stuck for 1 or 2 seconds after the setEnableSpeakerphone method call.
• The SoundTouch open-source library occasionally caused crashes when you used setLocalVoiceChanger and setLocalVoicePitch.
• When a third-party in-ear monitoring library and custom audio source were used and in-ear monitoring was enabled before joining a channel, in-ear monitoring did not take effect.
• After you successfully registered the raw video data observer, the app implemented time-consuming tasks in the onCaptureVideoFrame callback and caused video freezes for remote users.
• On some Samsung devices, the adjustRecordingSignalVolume(0) method call occasionally failed.
• After you successfully registered the raw video data observer and set the return value of getObservedFramePosition as POSITION_PRE_ENCODER (1 << 2), the SDK incorrectly triggered a onCaptureVideoFrame callback that did not match the set observation position.
• When using previously released 3.5.x versions of the SDK, the local user could not be heard by remote users when the local user used custom audio capture by the Push method.

v3.5.0.3

v3.5.0.3 was released on September 6, 2021 and improved the stability of the SDK.

v3.5.0.2

v3.5.0.2 was released on August 11, 2021.

This release fixed black screen issues that occurred when setupLocalVideo or setupRemoteVideo was called under certain circumstances, such as the following:

• setupLocalVideo(null) or setupRemoteVideo(null) was called to disable the local or remote video view, and then setupLocalVideo or setupRemoteVideo was called to initialize the local or remote video view.
• setupRemoteVideo was called in the onRemoteVideoStateChanged callback to initialize the remote video view.

v3.5.0.1

v3.5.0.1 was released on August 4, 2021. This release fixed the following issue:

The user could not receive the onRenderVideoFrame callback from the registered raw video data observer when the setupLocalVideo and setupRemoteVideo methods were not called.

v3.5.0

v3.5.0 was released on July 20, 2021.

Compatibility changes

1. Support for SDK Integration with mavenCentral

As of this release, Agora publishes the SDK package to mavenCentral. To integrate the SDK with mavenCentral, see Other approches to integrating the SDK.

2. Changes to audio route behavior

To improve user experience, this release improves the following SDK behavior:

• When the SDK uses the media volume, the audio route is affected as follows:

  • With versions earlier than v3.5.0, the SDK cannot set the audio route as the earpiece.
  • With v3.5.0 and later versions, the SDK can set the audio route as the earpiece. At the same time, the volume type becomes in-call volume. If you switch the audio route to the speakerphone, the SDK sets the volume type back to the media volume.
  To learn about the scenarios where the SDK uses the media volume, see What is the difference between the in-call volume and the media volume.

• If multiple external audio devices are connected, when the user removes the current playback device, the audio route is affected as follows:

  • With versions earlier than v3.5.0, the SDK does not play audio through any audio route, which causes a no-audio issue.
  • With v3.5.0 and later versions, the SDK sets the audio route as follows (in order of priority): the external device connected next to last > ... > the external device connected first > setEnableSpeakerphone > setDefaultAudioRouteToSpeakerphone > the default audio route of the SDK.

See Set the Audio Route.

New features

Virtual background (beta)

This release adds the enableVirtualBackground method, with which you can enable and set a virtual background for users as either a solid color or an image in PNG or JPG format. You can use the onVirtualBackgroundSourceEnabled callback to learn whether the virtual background is successfully enabled or the reason for an error.

Improvements

1. Video quality

The following improvements have been made to the quality of captured and received video in this release:

• Enhance the video contrast of captured and received video by adapting the color range to moderate the video whiteness.
• Enhance the color richness of captured and received video by adapting the color space to further restore video colors.

2. Additional improvements

This release also improves the following:

• The CPU usage and end-to-end video delay in high-resolution (720P and higher) scenarios are reduced.
• In scenarios where the AGC is enabled, the convergence time for noise reduction is shortened, which reduces noise fluctuations.
• The smoothness of output frames in the custom video rendering scenario is improved.

Fixed issues

This release fixed the following issues:

• Occasional failure to update the transcoding layout in Media Push under certain circumstances.
• After a remote user called enableLoopbackRecording, occasionally the local user heard an echo of their own audio.
• After calling muteLocalAudioStream(true) to stop publishing a local audio stream, the local user could hear remote users when the local user joined a channel for the first time. After leaving the channel and joining another channel, occasionally the local user could not hear remote users.
• When the local network quality was poor, the downlink network quality rating (rxQuality) of remote users reported by the SDK was not accurate.

API changes

Added

• enableVirtualBackground
• onVirtualBackgroundSourceEnabled

Modified

• setEnableSpeakerphone
• setDefaultAudioRouteToSpeakerphone

v3.4.6

v3.4.6 was released on July 15, 2021.

Improvements

To improve the accuracy of face detection results, as of this release, the SDK triggers the onFacePositionChanged callback immediately after detecting the disappearance of the human face.

Fixed issues

This release fixed the following issues:

• Failed to enable the camera on certain Android 4.4 TV models.
• Low-volume issues occurred when the user used Type-C headphones.
• The interface xxx is not visible from class loader error when running a project on some Android devices.

v3.4.5

v3.4.5 was released on June 22, 2021.

Compatibility changes

1. Support for GCM2 encryption

To further improve the security during real-time audio and video transmission process, this release adds the following:

• AES_128_GCM2 and AES_256_GCM2 encryption modes in EncryptionMode. The new GCM encryption modes use a more secure KDF (Key Derivation Function) and support setting the key and salt.
• The encryptionKdfSalt member in EncryptionConfig to add the salt for the AES_128_GCM2 and AES_256_GCM2 encryption modes.

This release also changes the default encryption mode from AES_128_XTS to AES_128_GCM2. If you use the default encryption mode in earlier versions, after upgrading the SDK to v3.4.5, ensure that you call enableEncryption and set EncryptionMode to AES_128_XTS.

See Media Stream Encryption.

2. Media stream publishing behavior changes

To flexibly control the publishing state in multiple channels, this release optimizes the RtcChannel class as follows:

• Deprecates the publish and unpublish methods, and adds muteLocalAudioStream and muteLocalVideoStream instead. You can set the publishing state of the audio stream and video stream separately.
• Adds the publishLocalAudio and publishLocalVideo members in ChannelMediaOptions. The default value is true. You can set the publishing state when joining a channel. If a user publishes streams in a channel, regardless of whether the user is a host or an audience member, you need to set publishLocalAudio and publishLocalVideo to false when the user joins other channels; otherwise, the user fails to join the channel.You can set the publishing state when joining a channel.
• After calling setClientRole(BROADCASTER), the local user publishes audio and video streams by default. You no longer need to call publish.

The above improvements bring the following changes in the RtcEngine class:

• muteLocalAudioStream and muteLocalVideoStream of RtcEngine do not take effect for channels created by the RtcChannel class, so you need to use the muteLocalAudioStream and muteLocalVideoStream of the RtcChannel class instead.
• When a user joins a channel by using joinChannel with the options parameter, you can set the publishing state.
• If a user joins a channel by calling joinChannel with the options parameter, muteLocalAudioStream or muteLocalVideoStream only takes effect when it is called after joinChannel.

If you upgrade the SDK to v3.4.5 or later, to avoid affecting your service, Agora recommends modifying the implementation of muteLocalAudioStream, muteLocalVideoStream, publish, and unpublish.

See Set the Publishing State and Join Multiple Channels.

3. Raw audio data

The raw audio data function enables you to implement custom audio pre- and post-processing functions, such as audio recording and audio mixing. To conserve system resources on devices, reduce the development difficulty, and support the accurate observation of audio data at a specific node, this release optimizes the IAudioFrameObserver class as follows:

• Changes the data type of the samples parameter from byte[] to DirectByteBuffer in the following callbacks:

  • onRecordFrame
  • onPlaybackFrame
  • onPlaybackFrameBeforeMixing
  • onMixedFrame
  • onPlaybackFrameBeforeMixingEx

  This change reduces the copy operation when you call the Agora C++ interfaces to get the raw audio data through JNI.

• Encapsulates the samples, numOfSamples, bytesPerSample, channels, and samplesPerSec parameters in the preceding on callbacks as the AudioFrame class to simplify the interfaces and enhance API extensibility.

• Adds the following callbacks for you to get the raw audio data at different audio transmission stages and in your expected format:

  • getObservedAudioFramePosition: Sets the audio observation positions.
  • getRecordAudioParams: Sets the audio recording format for the onRecordFrame callback.
  • getPlaybackAudioParams: Sets the audio playback format for the onPlaybackFrame callback.
  • getMixedAudioParams: Sets the audio mixing format for the onMixedFrame callback.

If you upgrade the SDK to v3.4.5 or later, to avoid affecting your service, ensure that you modify the implementation of IAudioFrameObserver.

4. startAudioMixing changes

To avoid blocking, this release changes the startAudioMixing from a synchronous call to an asynchronous call.

New features

1. Raw video data and local encoded video data

To reduce system-resource consumption on devices and the development difficulty of using C++ APIs across platforms, this release adds the following APIs to the Android/iOS platform for you to implement a raw video data observer and a local encoded video data observer. You can use them to implement custom functions, such as recording video, taking screenshots, and image enhancement.

• Raw video data observer:

  • registerVideoFrameObserver: Registers a raw video data observer.
  • onCaptureVideoFrame: Gets the video data captured by the local camera.
  • onPreEncodeVideoFrame: Gets the local pre-encoded video data.
  • onRenderVideoFrame: Gets the incoming remote video data.
  • getVideoFormatPreference: Sets the format of the raw video data output by the SDK.
  • getRotationApplied: Sets whether to rotate the raw video data output by the SDK.
  • getMirrorApplied: Sets whether to mirror the raw video data output by the SDK.
  • getObservedFramePosition: Sets the video observation position.
  • isMultipleChannelFrameWanted: Sets whether the SDK outputs remote video data received in multiple channels.
  • onRenderVideoFrameEx: Gets the remote video data received in multiple channels.

• Local encoded video data observer:

  • registerVideoEncodedFrameObserver: Registers a local encoded video data observer.
  • onVideoEncodedFrame: Gets the local encoded video data.

Improvements

1. Media Push

To be more transparent to users about errors and events in Media Push, this release adds the following codes:

• To onRtmpStreamingStateChanged: Error code RTMP_STREAM_UNPUBLISH_ERROR_OK (100), which reports that the streaming has been stopped normally. After you call removePublishStreamUrl to stop streaming, the SDK returns this error code and state code RTMP_STREAM_PUBLISH_STATE_IDLE (0).
• To onRtmpStreamingEvent: Event code RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE (2), which reports that the streaming URL is already being used for Media Push. If you want to start new streaming, use a new streaming URL.

2. Music file state

When you call startAudioMixing after pauseAudioMixing, this release adds the onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_STOPPED,AUDIO_MIXING_REASON_STOPPED_BY_USER)state, which indicates the music file is stopped, before reporting onAudioMixingStateChanged(MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY,AUDIO_MIXING_REASON_STARTED_BY_USER).

3. Audio device errors

To convey the impact of a system call on the audio sampling, this release adds LOCAL_AUDIO_STREAM_ERROR_INTERRUPTED (8) in LOCAL_AUDIO_STREAM_ERROR, which reports that the audio sampling is interrupted by a system call.

Fixed issues

This release fixed the following issues:

• Under poor network conditions, when you called startAudioMixing to play an online music file, occasionally the SDK response time was too long and caused a freeze.
• Under poor network conditions, when you frequently called startAudioMixing to play an online music file, an ANR pop-up window occasionally appeared.
• On some Android devices, after connecting a Bluetooth headset, the speaker still played audio.
• After switching the audio route to Bluetooth, the Bluetooth device occasionally failed to sample audio.
• Under poor network conditions, users were occasionally unable to switch roles.
• Under certain network conditions, when the host used a Xiaomi phone to custom capture video in texture format, other users in the channel saw the host’s video as a black screen.

API changes

Added

• RTMP_STREAM_UNPUBLISH_ERROR_OK (100) in RTMP_STREAM_PUBLISH_ERROR
• RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE (2) in RTMP_STREAMING_EVENT
• AES_128_GCM2 (7) and AES_256_GCM2 (8) in EncryptionMode
• encryptionKdfSalt in EncryptionConfig
• muteLocalAudioStream and muteLocalVideoStream in RtcChannel
• publishLocalAudio and publishLocalVideo in ChannelMediaOptions
• LOCAL_AUDIO_STREAM_ERROR_INTERRUPTED (8) in LOCAL_AUDIO_STREAM_ERROR
• registerVideoFrameObserver
• onCaptureVideoFrame
• onPreEncodeVideoFrame
• onRenderVideoFrame
• getVideoFormatPreference
• getRotationApplied
• getMirrorApplied
• getObservedFramePosition
• isMultipleChannelFrameWanted
• onRenderVideoFrameEx
• registerVideoEncodedFrameObserver
• onVideoEncodedFrame
• The following callbacks in the IAudioFrameObserver class:
  • getObservedAudioFramePosition
  • getRecordAudioParams
  • getMixedAudioParams
  • getPlaybackAudioParams

Modified

• The following callbacks in the IAudioFrameObserver class:

  • onRecordFrame
  • onPlaybackFrame
  • onPlaybackFrameBeforeMixing
  • onMixedFrame
  • onPlaybackFrameBeforeMixingEx
  • startAudioMixing

Deprecated

• publish and unpublish in RtcChannel

v3.4.3

v3.4.3 was released on June 16, 2021. This release fixed the following issues:

• Under certain circumstances, the PCM dump file could not be printed.
• Using third-party in-ear monitoring libraries caused crashes.
• On some Android devices, hardware encoding issues caused a black screen.
• Occasional crashes occurred on some Vivo devices.
• The startAudioMixing method could not play the MP3 local music files with the .m4a filename extension.
• After a user of the SDK v3.0.0+ left a communication channel that had any user of the SDK versions earlier than 3.0.0 and switched the channel profile to live streaming, the user of the SDK v3.0.0+ set user role to host before joining the next channel, but the client role setting did not take effect.
• Under certain circumstances, an audio delay occasionally occurred 10 minutes after a user joined the channel.

v3.4.2

v3.4.2 was released on May 12, 2021.

Improvements

To meet the requirements of Google Play Store, this release supports accessing a local file through URIs. When you call startAudioMixing, getAudioMixingDuration, preloadEffect, playEffect, getEffectDuration or addVideoWatermark and need to access a local file, Agora recommends the following steps:

1. Use Storage Access Framework to get the URI of the local file.
2. Call Uri.toString to convert the URI to a string.
3. Pass the string in the filePath or watermarkUrl parameter.

Fixed issues

This release fixed the interoperability issues between v3.4.0 or v3.4.1 and versions earlier than v3.0.0:

• With the COMMUNICATION channel profile, users of the v3.4.0 or v3.4.1 Native SDK experienced video freezes if they subscribed to videos from users of the Native SDK with versions earlier than v3.0.0.
• With the LIVE_BROADCASTING channel profile, users of the v3.4.0 or v3.4.1 Native SDK experienced video freezes if they subscribed to videos from users of the Windows or macOS SDK with versions earlier than v3.0.0.

v3.4.1

v3.4.1 was released on April 22, 2021. This release fixed the following issues:

• Crashes occurred in a certain voice conversion scenario.
• Under extremely poor network conditions, the host's video sent from the Web clients was corrupted on the Native clients.

v3.4.0

v3.4.0 was released on April 16, 2021.

Compatibility changes

Integration changes

1. SDK package publishing platform

Because JCenter is about to retire, as of this release, Agora publishes the SDK package to JitPack instead of JCenter. To integrate the SDK with JitPack, see Integrate the SDK.

2. Extension libraries

To reduce the app size after integrating the SDK, this release packages some features as extension libraries (with the Extension suffix). For details, see Extension libraries. If you do not need to use the related features, you can remove the corresponding extension libraries and recompile the project.

Behavior changes

To monitor the reason why the playback state of a music file changes, this release modifies the onAudioMixingStateChanged callback as follows:

• Replaces the errorCode parameter with the reason parameter.
• Deprecates the following constants and replace them with constants prefixed with AUDIO_MIXING_REASON:
  • MEDIA_ENGINE_AUDIO_ERROR_MIXING_OPEN
  • MEDIA_ENGINE_AUDIO_ERROR_MIXING_TOO_FREQUENT
  • MEDIA_ENGINE_AUDIO_EVENT_MIXING_INTERRUPTED_EOF

Using constants prefixed with AUDIO_MIXING_REASON, you can get the reason for the change of the playback state, such as start, pause, stop or fail.

• Modifies some logic of reporting MEDIA_ENGINE_AUDIO_EVENT_MIXING. For example, as of this release, when looping music, the SDK triggers the MEDIA_ENGINE_AUDIO_EVENT_MIXING_PLAY state when each loop is completed or starts.

If you upgrade the SDK to v3.4.0 or later, to avoid affecting your service, Agora recommends that you modify the implementation of onAudioMixingStateChanged.

New features

1. Virtual metronome

To meet the needs of online teaching scenarios that would benefit from a metronome, this release adds the following methods:

• startRhythmPlayer: Enables the virtual metronome.
• stopRhythmPlayer: Disables the virtual metronome.
• configRhythmPlayer: Reconfigures the virtual metronome after it is enabled.

2. Playback progress of audio effect files

To control the playback progress of audio effect files, this release adds the following methods:

• playEffect[3/3]: Sets the playback position when starting playback of an audio effect file by using the startPos parameter.
• setEffectPosition: Sets the playback position after starting playback of an audio effect file.
• getEffectDuration: Gets the duration of a local audio effect file.
• getEffectCurrentPosition: Gets current playback progress of an audio effect file.

Also, this release deprecates the playEffect[2/3] method. You can use playEffect[3/3] instead.

Improvements

1. Video encoding

The Agora SDK allows you to use degradationPrefer to set the degradation preference of local video encoding under limited bandwidth, for example, reducing the video frame rate while maintaining video quality, or reducing the video quality while maintaining the video frame rate. As of this release, degradationPrefer can be set as MAINTAIN_BALANCED, which reduces the video frame rate and video quality simultaneously to strike a balance between smoothness and video quality. MAINTAIN_BALANCED is suitable for scenarios where both smoothness and video quality are a priority, such as one-to-one calls, one-to-one online teaching, and multi-user online meetings.

2. Raw video data (C++)

The getRotationApplied and getMirrorApplied callbacks can rotate and mirror the raw video data. To improve the user experience, this release expands the video-data formats supported by these callback functions from RGBA to RGBA and YUV 420.

3. Playback progress of music files

To control the playback progress of music files, this release deprecates the startAudioMixing method and adds a new method with the same name in its place. The new startAudioMixing method allows you to set the playback position when starting playback of a music file by using the startPos parameter.

4. Audio recording

To set the recording configuration during audio recording, this release adds a new startAudioRecording method and deprecates the old method with the same name. The config parameter of the new startAudioRecording method allows you to set the audio recording quality, content, sample rate, and storage path of the recording file.

This release also adds a new error code: ERR_ALREADY_IN_RECORDING(160). If you call the new startAudioRecording[3/3] method again before the current recording ends, the SDK reports this error code.

5. Media device errors

To help users better understand the cause of local video errors, this release adds a new error code to LOCAL_VIDEO_STREAM_ERROR: LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(8), which indicates that the SDK cannot find the local video-capture device.

Fixed issues

This release fixed the following issues:

• The video was upside down after you used getMirrorApplied to set the mirror mode under certain circumstances.
• You could not get the video data in the RGBA format from onPreEncodeVideoFrame.
• You could not use getMirrorApplied and getRotationApplied to process the local video data before encoding.
• Crashes occurred when the audio sample rate exceeded 4.8 kHz.
• The onAudioVolumeIndication callback returned incorrect volume information after you called enableSoundPositionIndication(true).
• The local user would see the remote video upside down for an instant when the remote user switched between the front and rear cameras.

API changes

Added

• getAudioMixingDuration[2/2]
• startAudioRecording[3/3]
• getEffectDuration
• setEffectPosition
• getEffectCurrentPosition
• playEffect[3/3]
• startAudioMixing[2/2]
• LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(8) in LOCAL_VIDEO_STREAM_ERROR
• Error code: ERR_ALREADY_IN_RECORDING(160)

Modified

• onAudioMixingStateChanged

Deprecated

• getAudioMixingDuration[1/2]
• startAudioRecording[2/3]
• playEffect[1/2]
• startAudioMixing[1/2]
• The following constants:
  • MEDIA_ENGINE_AUDIO_ERROR_MIXING_OPEN
  • MEDIA_ENGINE_AUDIO_ERROR_MIXING_TOO_FREQUENT
  • MEDIA_ENGINE_AUDIO_EVENT_MIXING_INTERRUPTED_EOF

v3.3.2

v3.3.2 was released on March 29, 2021. This release fixed the following issues:

• Remote users saw a distorted image when the local user minimized the shared screen with the genie effect on Mac devices.
• The received custom video frame was rotated under certain circumstances.

v3.3.1

v3.3.1 was released on March 4, 2021.

New features

Voice Conversion

This release adds the setVoiceConversionPreset method to set a voice conversion effect (to disguise a user's voice). You can use this method to make a male-sounding voice sound steady or deep, and a female-sounding voice sound gender-neutral or sweet. See Set the Voice Effect.

Improvements

1. AES-GCM encryption mode

For scenarios requiring high security, to guarantee the confidentiality, integrity, and authenticity of data, and to improve the computational efficiency of data encryption, this release adds the following enumerators in encryptionMode:

• AES_128_GCM: 128-bit AES encryption, GCM mode.
• AES_256_GCM: 256-bit AES encryption, GCM mode.

2. Remote audio statistics

To monitor quality of experience (QoE) of the local user when receiving a remote audio stream, this release adds mosValue to onRemoteAudioStats, which reports the quality of the remote audio stream as determined by the Agora real-time audio MOS (Mean Opinion Score) measurement system.

Issues fixed

This release fixed the following issues:

• After enabling the sound position indication, you could not get the remote user's volume by the onAudioVolumeIndication callback.
• Occasional abnormality with the hardware encoders on certain devices after continuously encoding key frames for a short period of time.

API changes

This release adds the following APIs:

• setVoiceConversionPreset
• AES_128_GCM and AES_256_GCM in encryptionMode
• mosValue in onRemoteAudioStats

v3.3.0

v3.3.0 was released on January 22, 2021.

Compatibility changes

1. Integration change

This release adds libagora-core.so, the Agora basic calculation framework. To integrate the SDK into your project, see Integrate the SDK.

2. Changes to subscribing behavior

This release deprecates setDefaultMuteAllRemoteAudioStreams and setDefaultMuteAllRemoteVideoStreamsand changes the behavior of mute-related methods as follows:

• mute-related methods must be called after joining or switching to a channel; otherwise, the method call does not take effect.
• Methods with the prefix muteAll are no longer the master switch, and each mute-related method independently controls the user's subscribing state. When you call methods with the prefixes muteAll and muteRemote together, the method that is called later takes effect.
• Methods with the prefix muteAll set whether to subscribe to the audio or video streams of all remote users, including all subsequent users, which means methods with the prefix muteAll contain the function of methods with the prefix setDefaultMute. Agora recommends not calling methods with the prefixes muteAll and setDefaultMute together; otherwise, the setting may not take effect.

See details in Set the Subscribing State.

3. Changes to voice activity behavior

In the remote users' onAudioVolumeIndication callback, this release changes the value of the vad member from always 0 to always 1.

New features

1. Channel media options

To help developers control media subscription more flexibly, this release adds the joinChannel[2/2] and switchChannel[2/2] methods to set whether users subscribe to all remote audio or video streams in a channel when joining and switching channels.

2. Cloud proxy

To improve the usability of the Agora Cloud Proxy, this release adds the setCloudProxy method to set the cloud proxy and allows you to select a cloud proxy that uses the UDP protocol. For details, see Cloud Proxy.

3. Noise suppression

To eliminate non-stationary noise based on traditional noise reduction, this release adds enableDeepLearningDenoise to enable noise suppression.

4. Singing beautifier

To beautify the voice and add reverberation effects in a singing scenario, this release adds the setVoiceBeautifierParameters method and adds the SINGING_BEAUTIFIER enumeration value to VOICE_BEAUTIFIER_PRESET.

You can call setVoiceBeautifierPreset(SINGING_BEAUTIFIER) to beautify the male voice and add the reverberation effect for a voice in a small room. For more settings, you can call setVoiceBeautifierParameters(SINGING_BEAUTIFIER, param1, param2) to beautify male or female voices and add reverberation effects for a voice in a small room, large room, or hall.

5. Log files

To ensure the integrity of log content, this release adds the mLogConfig member variable to RtcEngineConfig. You can use mLogConfig to set the log files output by the Agora SDK when you initialize RtcEngine. See How can I set the log file? for details.

As of v3.3.0, Agora does not recommend using the setLogFile, setLogFileSize, or setLogFilter methods to set the log files.

6. Quality of captured video

To control the quality of video captured by the local camera, this release adds support for customizing the capture resolution and listening for abnormalities.

• Customize the capture resolution: Call the setCameraCapturerConfiguration method to set the capture preference to MANUAL(3) and set the width and height of the captured video image.
• Listen for abnormalities:
  • The abnormal brightness level of captured video images: Use captureBrightnessLevel in the onLocalVideoStats callback.
  • The camera fails to output the captured video: Use the onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE) callback.
  • The camera repeatedly outputs the captured video: Use the onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE) callback.

7. Data streams

To support scenarios such as lyrics synchronization and courseware synchronization, this release deprecates the previous createDataStream method and replaces it with a new method of the same name. You can use this new method to create a data stream and set whether to synchronize the data stream with the audio stream sent to the Agora channel and whether the received data is ordered.

Improvements

1. Raw audio data

This release adds raw audio data APIs for Android platforms. Once you obtain raw audio data through the following APIs, you can pre-process or post-process it for desired playback effects:

• onPlaybackFrameBeforeMixing
• onMixedFrame
• isMultipleChannelFrameWanted
• onPlaybackFrameBeforeMixingEx

2. Remote audio statistics

To monitor quality of experience (QoE) of the local user when receiving a remote audio stream, this release adds qoeQuality and qualityChangedReason to onRemoteAudioStats, which report QoE of the local user and the reason for poor QoE, respectively.

Fixed issues

• The audio sampling failed on some Android devices after a headset was plugged in.
• Local audio sampling occasionally failed on Android 10.
• Occasionally, a video rendering issue occurred when you used MediaIO to customize a video source in the texture format.

API changes

Added

• setVoiceBeautifierParameters
• SINGING_BEAUTIFIER
• enableDeepLearningDenoise
• joinChannel[2/2]
• switchChannel[2/2]
• createDataStream
• The mLogConfig member variable in the RtcEngineConfig class
• onPlaybackFrameBeforeMixing
• onMixedFrame
• isMultipleChannelFrameWanted
• onPlaybackFrameBeforeMixingEx
• qoeQuality and qualityChangedReason in the RemoteAudioStats class
• setCloudProxy
• captureBrightnessLevel in the LocalVideoStats class
• width and height in the CameraCapturerConfiguration class
• CAPTURER_OUTPUT_PREFERENCE_MANUAL(3) in the CAPTURER_OUTPUT_PREFERENCE enum
• Error code: ERR_MODULE_NOT_FOUND(157)

Modified

• onAudioVolumeIndication

Deprecated

• setDefaultMuteAllRemoteVideoStreams
• setDefaultMuteAllRemoteAudioStreams
• setLogFile
• setLogFileSize
• setLogFilter
• createDataStream

v3.2.1

v3.2.1 was released on December 17, 2020. This release fixed the following issues:

• Crashes occurred when using IPv6.
• After you called enableEncryption, the SDK did not trigger the onFirstLocalVideoFramePublished callback.

v3.2.0

v3.2.0 was released on November 30, 2020.

Compatibility changes

1. Integration change

SDK package change

Since v3.2.0, the following files have been added to the SDK package:

• libagora-fdkaac.so: The Fraunhofer FDK AAC dynamic library.
• libagora-mpg123.so: The mpg123 dynamic library.
• libagora-soundtouch.so: The SoundTouch dynamic library.
• libagora-ffmpeg.so: The FFmpeg dynamic library.

If you upgrade the SDK to v3.2.0 or later, ensure that you have copied the above files to the folder where the libagora-rtc-sdk.so file is located.

This release also merges libagora-crypto.so into libagora-rtc-sdk.so. After integrating libagora-rtc-sdk.so, you can use built-in encryption directly.

Spelling correction

This release renames USER_PRIORITY_NORANL to USER_PRIORITY_NORMAL.

2. Cloud proxy

This release optimizes the Agora cloud proxy architecture. If you are already using cloud proxy, to avoid compatibility issues between the new SDK and the old cloud proxy, please contact support@agora.io before upgrading the SDK. See Cloud Proxy.

3. Security and compliance

Agora has passed ISO 27001, ISO 27017, and ISO 27018 international certifications, providing safe and reliable real-time interactive cloud services for users worldwide. See ISO Certificates.

This release supports transport layer encryption by adding TLS (Transport Layer Security) and UDP (User Datagram Protocol) encryption methods.

4. Media Push with transcoding

This release adds the videoCodecType member to the LiveTranscoding class for setting the codec type of the transcoded video stream to H.264 or H.265.

New features

Interactive live streaming standard

This release adds setClientRole for setting the latency level of an audience member. You can use this method to switch between Interactive Live Streaming Premium and Interactive Live Streaming Standard as follows:

• Set the latency level as ultra low latency to use Interactive Live Streaming Premium.
• Set the latency level as low latency to use Interactive Live Streaming Standard.

For details, see the product overview of Interactive Live Streaming Standard.

Improvements

1. Meeting scenario

To improve the audio experience for multi-person meetings, this release adds AUDIO_SCENARIO_MEETING(8) in setAudioProfile.

2. Voice beautifier and audio effects

To improve the usability of the APIs related to voice beautifier and audio effects, this release deprecates setLocalVoiceChanger and setLocalVoiceReverbPreset, and adds the following methods instead:

• setVoiceBeautifierPreset: Compared with setLocalVoiceChanger, this method deletes audio effects such as a little boy’s voice and a more spatially resonant voice.
• setAudioEffectPreset: Compared with setLocalVoiceReverbPreset, this method adds audio effects such as the 3D voice, the pitch correction, a little boy’s voice and a more spatially resonant voice.
• setAudioEffectParameters: This method sets detailed parameters for a specified audio effect. In this release, the supported audio effects are the 3D voice and pitch correction.

3. Interactive streaming delay

This release reduces the latency on the audience's client during an interactive live streaming by about 500 ms.

Issues fixed

Audio

• Occasional audio sampling issues with Xiaomi speakers.

Video

• When a remote user called with vivo X30, the local user saw a black screen.
• When a remote user frequently joined and left a channel on an Android TV, the local user occasionally saw a black screen.

API changes

Added

• setClientRole
• setAudioEffectPreset
• setVoiceBeautifierPreset
• setAudioEffectParameters
• AUDIO_SCENARIO_MEETING(8)
• videoCodecType in the LiveTranscoding class

Deprecated

• setLocalVoiceChanger
• setLocalVoiceReverbPreset
• getSmoothRenderingEnabled (C++)

v3.1.3

v3.1.3 was released on October 13, 2020. This release fixed the occasional crashes when leaving a channel.

v3.1.2

v3.1.2 was released on September 14, 2020. This release fixed the following issues:

• When you use MediaIO to switch to a different video source, the screen gets frozen.
• The onFirstLocalVideoFrame and onFirstRemoteVideoFrame callbacks are not triggered at the right time.

v3.1.1

v3.1.1 was released on August 27, 2020. This release changes the AreaCode for regional connection. The latest area codes are as follows:

• AREA_CODE_CN: Mainland China.
• AREA_CODE_NA: North America.
• AREA_CODE_EU: Europe.
• AREA_CODE_AS: Asia, excluding Mainland China.
• AREA_CODE_JP: Japan.
• AREA_CODE_IN: India.
• AREA_CODE_GLOB: (Default) Global.

If you have specified a region for connection when calling create, ensure that you use the latest area code when migrating from an earlier SDK version.

v3.1.0

v3.1.0 was released on August 11, 2020.

New features

1. Publishing and subscription states

This release adds the following callbacks to report the current publishing and subscribing states:

• onAudioPublishStateChanged: Reports the change of the audio publishing state.
• onVideoPublishStateChanged: Reports the change of the video publishing state.
• onAudioSubscribeStateChanged: Reports the change of the audio subscribing state.
• onVideoSubscribeStateChanged: Reports the change of the video subscribing state.

2. First local frame published callback

This release adds the onFirstLocalAudioFramePublished and onFirstLocalVideoFramePublished callbacks to report that the first audio or video frame is published. The onFirstLocalAudioFrame callback is deprecated from v3.1.0.

3. Support for TextureView

This release adds the CreateTextureView method to return the Android TextureView, enabling you to zoom, rotate, and move the video view. This feature applies to scenarios such as screen sharing. You can use either CreateRendererView or CreateTextureView to implement a video scenario according to your needs.

4. Custom data report

This release adds the sendCustomReportMessage method for reporting customized messages. To try out this function, contact support@agora.io and discuss the format of customized messages with us.

Improvement

1. Regional connection

This release adds the following regions for regional connection. After you specify the region for connection, your app that integrates the Agora SDK connects to the Agora servers within that region.

• AREA_CODE_JAPAN: Japan.
• AREA_CODE_INDIA: India.

2. Advanced screen sharing

This release adds the following callbacks in the IVideoSource interface for screen sharing:

• getCaptureType: Gets the capture type of the custom video source.
• getContentHint: Gets the content hint of the custom video source.

3. Media Push

This release adds the onRtmpStreamingEvent callback to report events during Media Push, such as failure to add a background image or watermark image.

4. Encryption

This release adds the enableEncryption method for enabling built-in encryption, and deprecates the following methods:

• setEncryptionSecret
• setEncryptionMode

5. More in-call statistics

This release adds the following attributes to provide more in-call statistics:

• Adds txPacketLossRate in LocalAudioStats, which represents the audio packet loss rate (%) from the local client to the Agora edge server before applying anti-packet loss strategies.
• Adds the following attributes in LocalVideoStats:
  • txPacketLossRate: The video packet loss rate (%) from the local client to the Agora edge server before applying anti-packet loss strategies.
  • captureFrameRate: The capture frame rate (fps) of the local video.
• Adds publishDuration in RemoteAudioStats and RemoteVideoStats, which represents the total publish duration (ms) of the remote media stream.

6. Audio profile

To improve audio performance, this release adjusts the maximum audio bitrate of each audio profile as follows:

Profile	v3.1.0	Earlier than v3.1.0
AUDIO_PROFILE_DEFAULT	For the interactive streaming profile: 64 Kbps For the communication profile: 18 Kbps	For the interactive streaming profile: 52 Kbps For the communication profile: 18 Kbps
AUDIO_PROFILE_SPEECH_STANDARD	18 Kbps	18 Kbps
AUDIO_PROFILE_MUSIC_STANDARD	64 Kbps	48 Kbps
AUDIO_PROFILE_MUSIC_STANDARD_STEREO	80 Kbps	56 Kbps
AUDIO_PROFILE_MUSIC_HIGH_QUALITY	96 Kbps	128 Kbps
AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO	128 Kbps	192 Kbps

7. Log files

This release increases the default number of log files that the Agora SDK outputs from 2 to 5, and increases the default size of each log file from 512 KB to 1024 KB. By default, the SDK outputs five log files, agorasdk.log, agorasdk_1.log, agorasdk_2.log, agorasdk_3.log, agorasdk_4.log. The SDK writes the latest logs in agorasdk.log. When agorasdk.log is full, the SDK deletes the log file with the earliest modification time among the other four, renames agorasdk.log to the name of the deleted log file, and creates a new agorasdk.log to record the latest logs.

8. In-ear monitoring improvement on OPPO models (Android)

This release reduces the delay of in-ear monitoring on the following OPPO models:

• Reno4 Pro 5G
• Reno4 5G

9. Video experience under poor network conditions

• Starting with this release, the SDK automatically reduces video resolution under poor network conditions in order to improve the smoothness of the video.
• This release improves video quality by ensuring that the video does not become blurry due to changing network conditions.

10. Others

• Reduces the audio delay.
• Reduces the playback time of the first remote audio frame.

Issues fixed

This release fixed the following issues:

• setAudioMixingPitch did not work when setting the pitch parameter to certain values.
• Occasional video freeze.
• Occasional crashes when using external video source.

API changes

Added

• onAudioPublishStateChanged
• onVideoPublishStateChanged
• onAudioSubscribeStateChanged
• onVideoSubscribeStateChanged
• onFirstLocalAudioFramePublished
• onFirstLocalVideoFramePublished
• CreateTextureView
• enableEncryption
• txPacketLossRate in LocalAudioStats
• txPacketLossRate and captureFrameRate in LocalVideoStats
• publishDuration in RemoteAudioStats and RemoteVideoStats
• getCaptureType and getContentHint callbacks in IVideoSource
• onRtmpStreamingEvent
• Error code: ERR_NO_SERVER_RESOURCES(103)
• Warning code:
  • WARN_ADM_RECORD_IS_OCCUPIED(1033)
  • WARN_ADM_RECORD_ABNORMAL_FREQUENCY(1021)
  • WARN_ADM_PLAYOUT_ABNORMAL_FREQUENCY(1020)
  • WARN_APM_RESIDUAL_ECHO(1053)

Deprecated

• setEncryptionSecret
• setEncryptionMode
• onFirstLocalAudioFrame

v3.0.1.1

v3.0.1.1 was released on Jun 18, 2020. This release fixed the following issues:

• Crashes on x86 phones running on Android 6 and later.
• Crashes after calling registerVideoRenderFactory (deprecated).
• The image enhancement feature does not work.
• Occasional failures to capture the external video source.

v3.0.1

v3.0.1 was released on May 27, 2020.

Compatibility changes

Frame position for the video observer (C++)

As of this release, to get the video frame from the onPreEncodeVideoFrame callback, you must set POSITION_PRE_ENCODER(1<<2) in getObservedFramePosition as the frame position to observe, as well as implementing the onPreEncodeVideoFrame callback.

New features

1. Audio mixing pitch

To set the pitch of the local music file during audio mixing, this release adds setAudioMixingPitch. You can set the pitch parameter to increase or decrease the pitch of the music file. This method sets the pitch of the local music file only. It does not affect the pitch of a human voice.

2. Voice enhancement

To improve the audio quality, this release adds the following enumerate elements in setLocalVoiceChanger and setLocalVoiceReverbPreset:

• VOICE_CHANGER_PRESET adds several elements that have the prefixes VOICE_BEAUTY and GENERAL_BEAUTY_VOICE. The VOICE_BEAUTY elements enhance the local voice, and the GENERAL_BEAUTY_VOICE enumerations add gender-based enhancement effects.
• AUDIO_REVERB_PRESET adds the enumeration AUDIO_VIRTUAL_STEREO and several enumerations that have the prefix AUDIO_REVERB_FX. The AUDIO_VIRTUAL_STEREO enumeration implements reverberation in the virtual stereo, and the AUDIO_REVERB_FX enumerations implement additional enhanced reverberation effects.

See Set the Voice Changer and Reverberation Effects for more information.

3. Face detection

This release enables local face detection. After you call enableFaceDetection to enable this function, the SDK triggers the onFacePositionChanged callback in real time to report the detection results, including the distance between the human face and the device screen. This function can remind users to keep a certain distance from the screen.

4. Fill mode

To improve the user experience of watching videos, this release adds a video display mode RENDER_MODE_FILL. This mode zooms and stretches the video to fill the display window. You can select this mode when calling the following methods:

• setupLocalVideo
• setupRemoteVideo
• setLocalRenderMode
• setRemoteRenderMode

5. Remote video renderer in multiple channels

This release adds setRemoteVideoRenderer in the RtcChannel class to enable users who join the channel using the RtcChannel object to customize the remote video renderer.

6. Data post-processing in multiple channels (C++)

This release adds support for post-processing remote audio and video data in a multi-channel scenario by adding the following C++ methods:

• The IAudioFrameObserver class: isMultipleChannelFrameWanted and onPlaybackAudioFrameBeforeMixingEx.
• The IVideoFrameObserver class: isMultipleChannelFrameWanted and onRenderVideoFrameEx.

After successfully registering the audio or video observer, if you set the return value of isMultipleChannelFrameWanted as true, you can get the corresponding audio or video data from onPlaybackAudioFrameBeforeMixingEx or onRenderVideoFrameEx. In a multi-channel scenario, Agora recommends setting the return value as true.

Improvements

Frame position (C++)

After successfully registering the video observer, you can observe and get the video frame at each node of video processing. To conserve power consumption, this release enables customizing the frame position for the video observer. Set the return value of the getObservedFramePosition callback to set the position to observe:

• The position after capturing the video frame.
• The position before receiving the remote video frame.
• The position before encoding the frame.

Others

• Implements low in-ear device latency on Huawei phones with EMUI v10 and above.
• Improves in-call audio quality. When multiple users speak at the same time, the SDK does not decrease volume of any speaker.
• Reduces overall CPU usage of the device.

Fixed issues

• Inaccurate report of the onRemoteAudioStateChanged callback, no audio, audio mixing and audio freezing.
• An occasional black screen issue.
• Failure to end a call, inaccurate report of the onClientRoleChanged callback, occasional crashes, and interoperability when using encryption.

API changes

This release adds the following APIs:

• setAudioMixingPitch
• The enumeration AUDIO_VIRTUAL_STEREO and several elements that have the prefixes VOICE_BEAUTY, GENERAL_BEAUTY_VOICE, and AUDIO_REVERB_FX
• enableFaceDetection
• onFacePositionChanged
• RENDER_MODE_FILL
• setRemoteVideoRenderer in RtcChannel
• totalActiveTime in RemoteAudioStats
• totalActiveTime in RemoteVideoStats

v3.0.0.2

v3.0.0.2 was released on Apr 22, 2020.

New features

Specifying the area of connection

This release adds create for specifying the area of connection when creating an RtcEngine instance. This advanced feature applies to scenarios that have regional restrictions. You can choose from areas including Mainland China, North America, Europe, Asia (excluding Mainland China), and global (default).

After specifying the area of connection:

• When the app that integrates the Agora SDK is used within the specified area, it connects to the Agora servers within the specified area under normal circumstances.
• When the app that integrates the Agora SDK is used out of the specified area, it connects to the Agora servers either in the specified area or in the area where the SDK is located.

Issues fixed

This release fixed the occasional no-audio issue.

API changes

Added

create

v3.0.0

v3.0.0 was released on Mar 4, 2020.

On Mar 24, 2020, we fixed occasional issues relating to no audio, audio mixing, multiple onClientRoleChanged callbacks, and SDK crashes.

In this release, Agora improves the user experience under poor network conditions for both the COMMUNICATION and LIVE_BROADCASTING profiles through the following measures:

• Adopting a new architecture for the COMMUNICATION profile.
• Upgrading the last-mile network strategy for both the COMMUNICATION and LIVE_BROADCASTING profiles, which enhances the SDK's anti-packet-loss capacity by maximizing the net bitrate when the uplink and downlink bandwidth are insufficient.

To deal with any incompatibility issues caused by the architecture change, Agora uses the fallback mechanism to ensure that users of different versions of the SDKs can communicate with each other: if a user joins the channel from a client using a previous version, all clients using v3.0.0 automatically fall back to the older version. This has the effect that none of the users in the channel can enjoy the improved experience. Therefore we strongly recommend upgrading all your clients to v3.0.0.

We also upgrade the On-premise Recording SDK to v3.0.0. Ensure that you upgrade your On-premise Recording SDK to v3.0.0 so that all users can enjoy the improvements brought by the new architecture and network strategy.

Compatibility changes

1. Dual-stream mode not enabled in the COMMUNICATION profile

As of v3.0.0, the native SDK does not enable the dual-stream mode by default in the COMMUNICATION profile. Call the enableDualStreamMode (true) method after joining the channel to enable it. In video scenarios with multiple users, we recommend enabling the dual-stream mode.

2. Default log file path change

To avoid privilege issues, this release changes the default log file path from /storage/emulated/0/<package name>/ to /storage/emulated/0/Android/data/<package name>/files/.

New features

1. Multiple channel management

To enable a user to join an unlimited number of channels at a time, this release adds the RtcChannel and IRtcChannelEventHandler classes. By creating multiple RtcChannel objects, a user can join the corresponding channels at the same time.

After joining multiple channels, users can receive the audio and video streams of all the channels, but publish one stream to only one channel at a time. This feature applies to scenarios where users need to receive streams from multiple channels, or frequently switch between channels to publish streams. See Join multiple channels for details.

2. Raw video data
Adds the following C++ callbacks to the IVideoFrameObserver class to provide raw video data at different video transmission stages, and to accommodate more scenarios.

• onPreEncodeVideoFrame: Gets the video data after pre-processing and prior to encoding. This method applies to the scenarios where you need to pre-process the video data.
• getSmoothRenderingEnabled: Sets whether to smooth the acquired video frames. The smoothed video frames are more evenly spaced, providing a better rendering experience.

3. Adjusting the playback volume of the specified remote user

Adds adjustUserPlaybackSignalVolume for adjusting the playback volume of a specified remote user. You can call this method as many times as necessary in a call or the interactive live streaming to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.

4. Agora Mediaplayer Kit

To enrich the playability of the interactive live streaming, Agora releases the Mediaplayer Kit plug-in, which supports the host playing local or online media resources and sharing them with all users in the channel during the interactive live streaming. See Mediaplayer Kit release notes for details.

Improvements

1. Audio profiles

To meet the need for higher audio quality, this release adjusts the corresponding audio profile of AUDIO_PROFILE_DEFAULT (0) in the LIVE_BROADCASTING profiles.

SDK	AUDIO_PROFILE_DEFAULT (0)
v3.0.0	A sample rate of 48 KHz, music encoding, mono, and a bitrate of up to 52 Kbps.
Earlier than v3.0.0	A sample rate of 32 KHz, music encoding, mono, and a bitrate of up to 44 Kbps.

2. Mirror mode

The mirror mode determines how the SDK mirrors the video in different stages of transmission. To improve user experience with the mirror mode, this release updates the following methods:

• Setting a mirror mode for the stream to be encoded: This release adds the mirrorMode member to the VideoEncoderConfiguration struct for setting a mirror effect for the stream to be encoded and transmitted.
• Setting a mirror mode for the streams to be rendered:
  • We add the mirrorMode member to the VideoCanvas struct. You can use setupLocalVideo to set the mirror effect for the local view or use setupRemoteVideo to set the mirror effect for the remote view.
  • This release also adds the setLocalRenderMode and setRemoteRenderMode methods, both of which take an extra mirrorMode parameter. During a call, you can use setLocalRenderMode to update the mirror effect of the local view or setRemoteRenderMode to update the mirror effect of the remote view on the local device.

3. Quality statistics

Adds the following members in the RtcStats class for providing more in-call statistics, making it easier to monitor the call quality and memory usage in real time:

• gatewayRtt
• memoryAppUsageRatio
• memoryTotalUsageRatio
• memoryAppUsageInKbytes

Others

This release enables interoperability between the RTC Native SDK and the RTC Web SDK by default, and deprecates the enableWebSdkInteroperability method.

Issues fixed

• Audio issues relating to audio mixing, audio encoding, and echoing.
• Video issues relating to the watermark, aspect ratio, video sharpness, black outline appearing while screen sharing and toggling to full-screen.
• Other issues relating to app crashes, log file, and unstable service during Media Push.

API changes

Behavior change

• Calling enableLocalAudio(false) does not change the in-call volume to media volume.
• When the device is connected to the earpiece or Bluetooth, calling setEnableSpeakerphone(true) does not route the audio to the speakerphone.

Added

• setLocalRenderMode
• setRemoteRenderMode
• mirrorMode in VideoEncoderConfiguration
• channelId and mirrorMode in VideoCanvas
• channelId in AudioVolumeInfo
• gatewayRtt, memoryAppUsageRatio, memoryTotalUsageRatio, and memoryAppUsageInKbytes in RtcStats
• createRtcChannel
• RtcChannel
• IRtcChannelEventHandler

Deprecated

• enableWebSdkInteroperability.
• setLocalRenderMode¹, replaced by setLocalRenderMode.
• setRemoteRenderMode¹, replaced by setRemoteRenderMode.
• setLocalVideoMirrorMode, replaced by mirrorMode in setupLocalVideo and setupRemoteVideo.
• onStreamPublished and onStreamUnpublished, replaced by onRtmpStreamingStateChanged.

v2.9.4

v2.9.4 was released on Feb 17, 2020.

This release fixed some abnormal behaviors on Android devices.

v2.9.3

v2.9.3 was released on Feb 10, 2020.

This release fixed the following issues:

• The setRemoteSubscribeFallbackOption method, which should work in the LIVE_BROADCASTING profiles only, also works in the COMMUNICATION profile.
• In some one-to-one communication, the downlink media stream falls back to audio-only under poor network conditions.
• On some devices, the camera fails to capture the video after a system upgrade.

v2.9.2

v2.9.2 is released on Oct 18, 2019.

This release fixed crashes on some Android device.

v2.9.1

v2.9.1 is released on Sep 19, 2019.

New features

1. Detecting local voice activity
This release adds the report_vad(bool) parameter to the enableAudioVolumeIndication method to enable local voice activity detection. Once it is enabled, you can check the AudioVolumeInfo struct of the onAudioVolumeIndication callback for the voice activity status of the local user.

2. Choosing front and rear cameras
Users can select the front or rear camera before joining a channel. This release adds the cameraDirection member variable to the CameraCapturerConfiguration class to accomplish this. Choose the front or rear camera by selecting CAMERA_FRONT (1) or CAMERA_REAR (0) respectively.

3. Supporting RGBA raw video data
This release supports RGBA raw video data. Use the C++ method getVideoFormatPreference to set the format of the raw video data format.

You can also rotate or mirror the RGBA raw data using the C++ methods getRotationApplied or getMirrorApplied methods respectively.

4. Removing the event handler
This release adds the removeHandler method to remove specified IRtcEngineEventHandler objects when you want to stop listening for specific events.

Improvements

1. Improving the watermark function in the interactive live streaming
This release adds a new addVideoWatermark method with the following settings:

• The visiblePreview member sets whether the watermark is visible in the local preview.
• The positionInLandscapeMode/positionInPortraitMode member sets the watermark position when the encoding video is in landscape/portrait mode.

This release optimizes the watermark function, reducing the CPU usage by 5% to 20%.

The original addVideoWatermark method is deprecated.

2. Supporting more audio sample rates for recording
To enable more audio sample rate options for recording, this release adds a new startAudioRecording method with a sampleRate parameter. In the new method, you can set the sample rate as 16, 32, 44.1 or 48 kHz. The original method supports only a fixed sample rate of 32 kHz and is deprecated.

3. Adding error codes

This release adds the following error codes in the ErrorCode class:

• ERR_ALREADY_IN_USE(19)
• ERR_WATERMARK_PATH(125)
• ERR_INVALID_USER_ACCOUNT(134)
• ERR_AUDIO_BT_SCO_FAILED(1030)
• ERR_ADM_NO_RECORDING_DEVICE(1359)
• ERR_VCM_UNKNOWN_ERROR(1600)
• ERR_VCM_ENCODER_INIT_ERROR(1601)
• ERR_VCM_ENCODER_ENCODE_ERROR(1602)
• ERR_VCM_ENCODER_SET_ERROR(1603)

For detailed descriptions for each error, see Error Codes.

Issues fixed

Audio

• A user makes a call after connecting to a Bluetooth device. After the call ends, the user watches YouTube and cannot hear any sound.
• The audio route is different from the settings in the setEnableSpeakerphone method when Bluetooth is connected in the COMMUNICATION profile.
• Exceptions occur in the audio route when a user is in the channel.
• The app crashes when using external audio sources in the push mode.
• Audio freezes.
• After turning off the Bluetooth headset, the audio route becomes the earpiece instead of the loudspeaker.
• Echoes occur when a user is in the channel.
• Occasional noise occurs in the LIVE_BROADCASTING profile.
• The app fails to play online music files using the startAudioMixing method on devices running Android 10.

Miscellaneous

• The OpenSSL version is outdated.

API Changes

Added

• startAudioRecording
• addVideoWatermark
• getVideoFormatPreference
• getRotationApplied
• getMirrorApplied
• removeHandler
• The report_vad parameter in enableAudioVolumeIndication
• The vad member in AudioVolumeInfo
• The cameraDirection member in CameraCapturerConfiguration

Deprecated

• startAudioRecording
• addVideoWatermark

v2.9.0

v2.9.0 is released on Aug 16, 2019.

Compatibility changes

1. Media Push

In this release, we deleted the following methods:

• configPublisher
• setVideoCompositingLayout
• clearVideoCompositingLayout

If your app implements Media Push with the methods above, ensure that you upgrade the SDK to the latest version and use the following methods for the same function:

• setLiveTranscoding
• addPublishStreamUrl
• removePublishStreamUrl
• onRtmpStreamingStateChanged

For how to implement the new methods, see Media Push.

2. Reporting the state of the remote video

This release extends the onRemoteVideoStateChanged callback with more states of the remote video: STOPPED(0), STARTING(1), DECODING(2), FROZEN(3), and FAILED(4). It adds a reason parameter to the callback to indicate why the remote video state changes. The original onRemoteVideoStateChanged callback is deleted. If you upgrade your Native SDK to the latest version, ensure that you re-implement the onRemoteVideoStateChanged callback.

3. Disabling/enabling the local audio

To improve the audio quality in the COMMUNICATION profile, this release sets the system volume to the media volume after you call the enableLocalAudio(true) method. Calling enableLocalAudio(false) switches the system volume back to the in-call volume.

New features

1. Faster switching to another channel

This release adds the switchChannel method to enable the audience in a live-streaming channel to quickly switch to another channel. With this method, you can achieve a much faster switch than with the leaveChannel and joinChannel methods. After the audience successfully switches to another channel by calling the switchChannel method, the SDK triggers the onLeaveChannel and onJoinChannelSuccess callbacks to indicate that the audience has left the original channel and joined a new one.

2. Channel media stream relay

This release adds the following methods to relay the media streams of a host from a source channel to a destination channel. This feature applies to scenarios such as online singing contests, where hosts of different live-streaming channels interact with each other.

• startChannelMediaRelay
• updateChannelMediaRelay
• stopChannelMediaRelay

During the media stream relay, the SDK reports the states and events of the relay with the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks.

For more information on the implementation, API call sequence, sample code, and considerations, see Co-host across Channels.

3. Reporting the local and remote audio state

This release adds the onLocalAudioStateChanged and onRemoteAudioStateChanged callbacks to report the local and remote audio states. With these callbacks, the SDK reports the following states for the local and remote audio:

• The local audio: STOPPED(0), RECORDING(1), ENCODING(2), or FAILED(3). When the state is FAILED(3), see the error parameter for troubleshooting.
• The remote audio: STOPPED(0), STARTING(1), DECODING(2), FROZEN(3), or FAILED(4). See the reason parameter for why the remote audio state changes.

4. Reporting the local audio statistics

This release adds the onLocalAudioStats callback to report the statistics of the local audio during a call, including the number of channels, the sending sample rate, and the average sending bitrate of the local audio.

5. Pulling the remote audio data

To improve the experience in audio playback, this release adds the following methods to pull the remote audio data. After getting the audio data, you can process it and play it with the audio effects that you want.

• setExternalAudioSink
• pullPlaybackAudioFrame

The difference between the onPlaybackFrame callback and the pullPlaybackAudioFrame method is as follows:

• onPlaybackFrame: The SDK sends the audio data to the app once every 10 ms. Any delay in processing the audio frames may result in an audio delay.
• pullPlaybackAudioFrame: The app pulls the remote audio data. After setting the audio data parameters, the SDK adjusts the frame buffer and avoids problems caused by jitter in external audio playback.

Improvements

1. Reporting more statistics of the in-call quality

This release adds the following statistics in the RtcStats, LocalVideoStats, and RemoteVideoStats classes:

• RtcStats: The total number of the sent audio bytes, sent video bytes, received audio bytes, and received video bytes during a session.
• LocalVideoStats: The encoding bitrate, the width and height of the encoding frame, the number of frames, and the codec type of the local video.
• RemoteVideoStats: The packet loss rate of the remote video.

2. Improving the video quality of the live streaming

This release minimizes the video freeze rate under poor network conditions, improves the video sharpness, and optimizes the video smoothness when the packet loss rate is high.

3. Other Improvements

• Reduces the earpiece delay.
• Improves the audio quality when the audio scenario is set to Game Streaming.
• Improves the audio quality after the user disables the microphone in the COMMUNICATION profile.

Issues fixed

Audio

• When interoperating with a Web app, voice distortion occurs after the native app enables the remote sound position indication.
• The audience cannot hear the host after the host sets the in-ear monitoring volume to 0.
• Failure to play the audio file by calling the startAudioMixing method.
• The audio route cannot be set to Bluetooth on some devices.
• Crashes occur when using the raw audio data.
• The audio route does not conform to the default settings after the device disconnects from Bluetooth.

Video

• Occasional crashes occur when using the external video source.
• The audience sees a black screen for the host's view.

Miscellaneous

• Occasionally mixed streams in CDN streaming.
• Occasional crashes occur after joining the channel on some devices.

API Changes

To improve the user experience, we made the following changes in v2.9.0:

Added

• setExternalAudioSink
• pullPlaybackAudioFrame
• onLocalAudioStateChanged
• onRemoteAudioStateChanged
• onRemoteVideoStateChanged
• onLocalAudioStats
• switchChannel
• startChannelMediaRelay
• updateChannelMediaRelay
• stopChannelMediaRelay
• onChannelMediaRelayStateChanged
• onChannelMediaRelayEvent
• RtcStats: txAudioBytes, txVideoBytes, rxAudioBytes, and rxVideoBytes
• LocalVideoStats: encodedBitrate, encodedFrameWidth, encodedFrameHeight, encodedFrameCount, and codedType
• RemoteVideoStats: packetLossRate

Deprecated

• onMicrophoneEnabled. Use LOCAL_AUDIO_STREAM_STATE_CHANGED(0) or LOCAL_AUDIO_STREAM_STATE_RECORDING(1) in the onLocalAudioStateChanged callback instead.
• onRemoteAudioTransportStats. Use the onRemoteAudioStats callback instead.
• onRemoteVideoTransportStats. Use the onRemoteVideoStats callback instead.

Deleted

• configPublisher
• setVideoCompositingLayout
• clearVideoCompositingLayout
• onRemoteVideoStateChanged

v2.8.2

v2.8.2 is released on Aug 1, 2019.

This release fixed the interoperating problem with the Agora Web SDK.

v2.8.1

v2.8.1 is released on Jul. 20, 2019.

New features

• Support for the x86-64 architecture.
• Support for Android Q.

v2.8.0

v2.8.0 is released on Jul. 8, 2019.

New features

1. Supporting string user IDs

Many apps use string user IDs. This release adds the following methods to enable apps to join an Agora channel directly with string user IDs as user accounts:

• registerLocalUserAccount
• joinChannelWithUserAccount

For other methods, Agora uses the integer uid parameter. The Agora Engine maintains a mapping table that contains the user ID and string user account, and you can get the corresponding user account or ID by calling the getUserInfoByUid or getUserInfoByUserAccount method.

To ensure smooth communication, use the same parameter type to identify all users within a channel, that is, all users should use either the integer user ID or the string user account to join a channel.

Note:

• Do not mix parameter types within the same channel. The following Agora SDKs support string user accounts:

  • The Native SDK: v2.8.0 and later.
  • The Web SDK: v2.5.0 and later.

  If you use SDKs that do not support string user accounts, only integer user IDs can be used in the channel.

• If you change your user IDs into string user accounts, ensure that all app clients are upgraded to the latest version.

• If you use string user accounts, ensure that the token generation script on your server is updated to the latest version. If you join the channel with a user account, ensure that you use the same user account or its corresponding integer user ID to generate a token. Call the getUserInfoByUserAccount method to get the user ID that corresponds to the user account.

2. Adding remote audio and video statistics

To monitor the audio and video transmission quality during a call or the interactive live streaming , this release adds the totalFrozenTime and frozenRate members in the RemoteAudioStats and RemoteVideoStats classes, to report the audio and video freeze time and freeze rate of the remote user.

This release also adds the numChannels, receivedSampleRate, and receivedBitrate members in the RemoteAudioStats class.

Improvements

This release adds a CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT(14) member to the reason parameter of the onConnectionStateChanged callback. This member indicates a connection state change caused by the timeout of the connection keep-alive between the SDK and Agora's edge server.

Issues Fixed

Audio

• Occasional audio freezes.

Video

• When the user resumes receiving the remote video streams, the video stream switches to a low stream (low-resolution and low-bitrate video stream), and takes a long time to switch to a high stream.

Miscellaneous

• When the log file path specified in the setLogFile method does not exist, no log file is generated and the default log file is incomplete.

API Changes

To improve your experience, we made the following changes to the APIs:

Added

• registerLocalUserAccount
• joinChannelWithUserAccount
• getUserInfoByUid
• getUserInfoByUserAccount
• onLocalUserRegistered
• onUserInfoUpdated
• The numChannels, receivedSampleRate, receivedBitrate, totalFrozenTime, and frozenRate members in the RemoteAudioStats class
• The totalFrozenTime and frozenRate members in the RemoteVideoStats class

Deprecated

• The lowLatency member in the LiveTranscoding class

v2.4.1

v2.4.1 is released on Jun 12, 2019.

Compatibility changes

Ensure that you read the following SDK behavior changes if you migrate from an earlier SDK version.

1. Publishing streams to the CDN

To improve the usability of the CDN streaming service, v2.4.1 defines the following parameter limits:

Class / Interface	Parameter Limit
LiveTranscoding	videoFrameRate: Frame rate (fps) of the CDN live output video stream. The value range is [0, 30], and the default value is 15. Agora adjusts all values over 30 to 30. videoBitrate: Bitrate (Kbps) of the CDN live output video stream. The default value is 400. Set this parameter according to the Video Bitrate Table. If you set a bitrate beyond the proper range, the SDK automatically adapts it to a value within the range. videoCodecProfile: The video codec profile. Set it as BASELINE, MAIN, or HIGH (default). If you set this parameter to other values, Agora adjusts it to the default value of HIGH. width and height: Pixel of the video. The minimum value of width x height is 16 x 16.
AgoraImage	url: The maximum length of this parameter is 1024 bytes.
addPublishStreamUrl	url: The maximum length of this parameter is 1024 bytes.
removePublishStreamUrl	url: The maximum length of this parameter is 1024 bytes.

This release also adds the audioCodecProfile parameter in the LiveTranscoding class to set the audio codec profile type. The default type is LC-AAC, which means the low-complexity audio codec profile.

v2.4.1 also adds five error codes to the error parameter in the onStreamPublished method for quick troubleshooting.

2. Renaming the receivedFrameRate parameter in the RemoteVideoStats class

v2.4.1 renames the receivedFrameRate parameter to rendererOutputFrameRate in the RemoteVideoStats class to more accurately describe the statistics of the remote video stream.

New features

1. Adding media metadata

In live streaming scenarios, the host can send shopping links, digital coupons, and online quizzes to the audience for more diversified live interactions. v2.4.1 adds the registerMediaMetadataObserver interface and the IMediaMetadataObserver class, allowing the host to add metadata to the output video and to send media attached information.

2. State of the local video

v2.4.1 adds the onLocalVideoStateChanged callback to indicate the local video state. In this callback, the SDK returns the STOPPED,CAPTURING, ENCODING, or FAILED state. When the state is FAILED, you can use the error code for troubleshooting. This callback indicates whether or not the interruption is caused by capturing or encoding. This release deprecates the onCameraReady and onVideoStopped callbacks.

3. State of the Media Push

v2.4.1 adds the onRtmpStreamingStateChanged callback to indicate the state of the Media Push and help you troubleshoot issues when exceptions occur. In this callback, the SDK returns the IDLE, CONNECTING, RUNNING, RECOVERING, or FAILURE state. When the state is FAILURE, you can use the error code for troubleshooting. You can still use the onStreamPublished and onStreamUnpublished callbacks, but we do not recommend using them.

4. More reasons for a network connection state change

In the onConnectionStateChanged callback, v2.4.1 adds error codes to the reason parameter to help you troubleshoot issues when exceptions occur. The SDK returns the onConnectionStateChanged callback whenever the connection state changes. This release also deprecates WARN_LOOK_UP_CHANNEL_REJECTED(105), ERR_TOKEN_EXPIRED(109), and ERR_INVALID_TOKEN(110).

*5. State of the local network type *

v2.4.1 adds the onNetworkTypeChanged callback to indicate the local network type. In this callback, the SDK returns the UNKNOWN, DISCONNECTED, LAN, WIFI, 2G, 3G, or 4G type. When the network connection is interrupted, this callback indicates whether or not the interruption is caused by a network type change or poor network conditions.

6. Getting the audio mixing volume

v2.4.1 adds the getAudioMixingPlayoutVolume and getAudioMixingPublishVolume methods, which respectively gets the audio mixing volume for local playback and remote playback, to help you troubleshoot audio volume related issues.

7. Reporting when the first remote audio frame is received and decoded

To get the more accurate time of the first audio frame from a specified remote user, v2.4.1 adds the onFirstRemoteAudioDecoded callback to report to the app that the SDK decodes first remote audio. This callback is triggered in either of the following scenarios:

• The remote user joins the channel and sends the audio stream.
• The remote user stops sending the audio stream and re-sends it after 15 seconds.

The difference between the onFirstRemoteAudioDecoded and onFirstRemoteAudioFrame callbacks is that the onFirstRemoteAudioFrame callback occurs when the SDK receives the first audio packet. It occurs before the onFirstRemoteAudioDecoded callback.

Improvements

1. Playing multiple online audio effect files simultaneously

v2.4.1 adds the support for playing multiple online audio effect files simultaneously by allowing you to call the playEffect method multiple times with the URLs of the online audio effect files.

2. Reporting more statistics

• v2.4.1 adds the txPacketLossRate and rxPacketLossRate parameters in the RtcStats class. These parameters return the packet loss rate from the local client to the server and vice versa.

• To provide more accurate statistics of the local and remote video, v2.4.1 makes the following changes to the following classes:

  • LocalVideoStats: Adds the encoderOutputFrameRate and rendererOutputFrameRate parameters.
  • RemoteVideoStats: Adds thedecoderOutputFrameRate parameter, and renames the receivedFrameRate parameter to the rendererOutputFrameRate parameter.

3. Image enhancement

v2.4.1 assigns default values to various parameters in the BeautyOptions class to improve the image enhancement experience. This release also optimizes the image enhancement algorithm. Test results from Agora Lab suggest that the updated algorithm leads to lower GPU and CPU consumption. The power consumption is optimized by over 30%.

4. Miscellaneous

• Improved the sound quality of the GAME_STREAMING audio scenario.
• Reduced the audio and video latency.
• Reduced the SDK package size by 0.5 M.
• Improved the accuracy of the network quality after users change the video bitrate.
• Enabled the audio quality notification callback by default, that is, enabled the onRemoteAudioStats callback without calling the enableAudioVolumeIndication method.
• Improved the stability of video services.
• Improved the stability of CDN streaming services.

Issues fixed

Audio

• The audio stream is played through the loudspeaker even after the user plugs in the earphone.
• The user cannot hear the audio mixing file through Bluetooth in the single-host scenario.
• Exceptions occur when playing the audio mixing file in the LIVE_BROADCASTING profile.

Video

• In the LIVE_BROADCASTING profile, the view of the host is a black screen.

Miscellaneous

• Users still receive the onNetworkQuality callback after leaving the channel.
• Occasional crashes.
• The app quits after calling joinChannel.

API changes

To improve your experience, we made the following changes to the APIs:

Unified the C++ interface for all platforms

v2.4.1 unifies the behavior of the C++ interfaces across different platforms so that you can apply the same code logic on different platforms. v2.4.1 implements the methods of the RtcEngineParameters class in the IRtcEngine class. Refer to Agora C++ API Reference for All Platforms home page for the applicable platforms and considerations of each interface.

Added

• getAudioMixingPlayoutVolume
• getAudioMixingPublishVolume
• onFirstRemoteAudioDecoded
• onLocalVideoStateChanged
• onNetworkTypeChanged
• onRtmpStreamingStateChanged
• registerMediaMetadataObserver
• The IMetadataObserver class
• The audioCodecProfile parameter in the LiveTranscoding class
• The txPacketLossRate and rxPacketLossRate parameters in the RtcStats class
• The encoderOutputFrameRate and rendererOutputFrameRate parameters in the LocalVideoStats class
• The decoderOutputFrameRate and rendererOutputFrameRate parameters in the RemoteVideoStats class

Deprecated

• enableAudioQualityIndication
• onCameraReady. Use LOCAL_VIDEO_STREAM_STATE_CAPTURING(1) in the onLocalVideoStateChanged callback instead.
• onVideoStopped. Use in LOCAL_VIDEO_STREAM_STATE_STOPPED(0) the onLocalVideoStateChanged callback instead.
• The WARN_LOOKUP_CHANNEL_REJECTED(105) warning code. Use CONNECTION_CHANGED_REJECTED_BY_SERVER(10) in the onConnectionStateChanged callback instead.
• The ERR_TOKEN_EXPIRED(109) error code. Use CONNECTION_CHANGED_TOKEN_EXPIRED(9) in the onConnectionStateChanged callback instead.
• The ERR_INVALID_TOKEN(110) error code. Use CONNECTION_CHANGED_INVALID_TOKEN(8) in the onConnectionStateChanged callback instead.
• The ERR_START_CAMERA(1003) error code. Use LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE(4) in the onLocalVideoStateChanged callback instead.

v2.4.0 and Earlier

v2.4.0

v2.4.0 is released on April 1, 2019.

New Features

1. Image enhancement

In scenarios such as the video chat, interactive streaming, and online education, basic beautification is a popular feature. v2.4.0 adds the setBeautyEffectOptions method, allowing you to adjust the contrast, brightness, smoothness and red saturation of an image. For more information, see Image Enhancement.

2. Voice changer and voice reverberation

Adding voice changer and reverberation effects in an audio chat room brings much more fun. v2.4.0 adds the setLocalVoiceChanger and setLocalVoiceReverbPreset methods, allowing you to change your voice or reverberation by choosing from the preset options. See Voice changer.

3. Tracking the sound position of a remote user

v2.4.0 adds the enableSoundPositionIndication and setRemoteVoicePosition methods. Call the enableSoundPositionIndication method before joining a channel to enable stereo panning for the remote users, and then you can call the setRemoteVoicePosition method to track the position of a remote user.

4. Pre-call last-mile network probe test

Conducting a last-mile probe test before joining the channel helps the local user to evaluate or predict the uplink network conditions. v2.4.0 adds the startLastmileProbeTest, stopLastmileProbeTest, and onLastmileProbeResult APIs, allowing you to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).

5. Setting the priority of a remote user's stream

v2.4.0 adds the setRemoteUserPriority method for setting the priority of a remote user's media stream. You can use this method with the setRemoteSubscribeFallbackOption method. If the fallback function is enabled for a remote stream, the SDK ensures the high-priority user gets the best possible stream quality.

6. State of an audio mixing file

v2.4.0 adds the onAudioMixingStateChanged callback to report any change of the audio-mixing file playback state (playback succeeds or fails) and the corresponding reason. This release also adds the warning code 701, which is triggered if the local audio-mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL when playing the audio-mixing file.

7. Setting the log file size

The SDK has two log files, each with a default size of 512 KB. In case some customers require more than the default size, v2.4.0 adds the setLogFileSize method for setting the log file size (KB).

8. Cloud proxy

Supports the cloud proxy service. See Use Cloud Proxy for details.

Improvements

1. Accuracy of call quality statistics

• v2.4.0 adds the intervalInSeconds parameter to the startEchoTest method, allowing you to set the interval between when you speak and when the recording plays back.
• v2.4.0 adds three parameters to the LocalVideoStats class: targetBitrate for setting the target bitrate of the current encoder, targetFrameRate for setting the target frame rate, and qualityAdaptIndication for reporting the quality of the local video since last count.

2. Video encoder preferences

v2.4.0 provides the following options for setting video encoder preferences:

• Setting preferences under limited bandwidth. v2.4.0 adds two parameters to the VideoEncoderConfiguration class: minFrameRate and degradationPrefer. You can use these parameters together to set the minimum video encoder frame rate and the video encoding degradation preference under limited bandwidth. For more information, see Set the Video Profile.

• Setting the camera capture preference. v2.4.0 adds the setCameraCapturerConfiguration method, allowing you to set the camera capture preference. You can choose system performance over video quality or vice versa as needed. For more information, see the API Reference.

3. Core quality improvements

• Reduces the audio delay.
• Improves the video quality and stability.
• Shortens the time to render the first remote video frame.
• Reduces the time delay when playing through the earpiece and minimizes the echo.

Issues Fixed

Audio

• Calling the enableLocalAudio method disconnects all connected Bluetooth devices.
• The SDK does not support audio mixing URLs with Chinese characters.
• Volume levels of the high-pitch sound are lowered.
• Sounds are occasionally played fast.
• The app cannot adjust the volume on some devices.

Video

• If you skip the renderMode setting, the video stretches due to a mismatch with the display.
• Video freezes on some lower-end devices.
• It takes too long to render the first received video frame.

Miscellaneous

• The user drop-offline time between Android and iOS is not unified.
• The SEI information does not synchronize with the media stream when publishing transcoded streams to the CDN.

API Changes

To improve your experience, we made the following changes to the APIs:

Added

• setBeautyEffectOptions
• setLocalVoiceChanger
• setLocalVoiceReverbPreset
• enableSoundPositionIndication
• setRemoteVoicePosition
• startLastmileProbeTest
• stopLastmileProbeTest
• setRemoteUserPriority
• startEchoTest
• setCameraCapturerConfiguration
• setLogFileSize
• onAudioMixingStateChanged
• onLastmileProbeResult

Deprecated

• startEchoTest
• setVideoQualityParameters

Miscellaneous

v2.4.0 changes the type of the frameRate parameter in the VideoEncoderConfiguration class from enum to int.

v2.3.3

v2.3.3 is released on January 24, 2019.

Issues Fixed

• Occasional inaccurate statistics returned in the onNetworkQuality callback.
• Occasional crashes on Huawei P9.

v2.3.2

v2.3.2 is released on January 16, 2019.

Compatibility changes

Besides the new features and improvements mentioned below, it is worth noting that v2.3.2:

• Improves the SDK's ability to counter packet loss under unreliable network conditions.
• Improves the communication smoothness.
• Reduces video freezes in the LIVE_BROADCASTING profile.

Before upgrading your SDK, ensure that the version is:

• Native SDK v1.11 or later.
• Web SDK v2.1 or later.

New Features

1. Automatic exposure at a point of interest

v2.3.2 adds the following methods and callback to support camera exposure and improve the captured video quality:

• isCameraExposurePositionSupported: Checks whether the device supports camera exposure.
• setCameraExposurePosition: Sets the camera exposure position.
• onCameraExposureAreaChanged: Occurs when the camera exposure area changes.

You can send the touch point coordinates in the view to the SDK for automatic exposure.

2. Video quality in the interactive live streaming

v2.3.2 adds the minBitrate parameter (minimum encoding bitrate) in the setVideoEncoderConfiguration method. The SDK automatically adjusts the encoding bitrate to adapt to the network conditions. Using a value greater than the default value forces the video encoder to output high-quality images but may cause more packet loss and hence sacrifice the smoothness of the video transmission. Agora does not recommend changing this value unless you have special requirements for image quality.

3. Independent audio mixing volume adjustments for local playback and remote publishing

v2.3.2 adds the adjustAudioMixingPlayoutVolume and adjustAudioMixingPublishVolume methods to complement the adjustAudioMixingVolume method, allowing you to independently adjust the audio mixing volume for local playback and remote publishing.

This release also changes the behavior of the adjustPlaybackSignalVolume method to control only the voice volume. Therefore, to mute the local audio playback, call both the adjustPlaybackSignalVolume(0) and adjustAudioMixingVolume(0) methods.

See Adjust the Volume for the scenarios and corresponding APIs.

Improvements

1. Improves the accuracy of the call quality statistics

v2.3.2 deprecates the onAudioQuality callback and replaces it with the onRemoteAudioStats callback to improve the accuracy of the call quality statistics. The onRemoteAudioStats callback returns parameters such as the audio frame loss rate, end-to-end audio delay, and jitter buffer delay at the receiver, which are more closely linked to the real user experience. In addition, v2.3.2 optimizes the algorithm of the onNetworkQuality callback for the uplink and downlink network qualities.

• onRemoteAudioStats: Reports the statistics of the remote audio stream from each user/host. This callback replaces the onAudioQuality callback.
• onNetworkQuality: Reports the last mile network quality of each user in the channel.

We plan to improve the following callback in subsequent versions:

• onLastmileQuality: Reports the last mile network quality of the local user before the user joins a channel.

For the list of API methods related to the call quality statistics and on how and when to use them, see Report In-call Statistics.

2. New network connection policy

v2.3.2 adds the following API method and callback to get the current network connection state and the reason for a connection state change:

• getConnectionState: Gets the connection state of the SDK.
• onConnectionStateChanged: Occurs when the connection state of the SDK to the server changes.

v2.3.2 deprecates the onConnectionInterrupted and onConnectionBanned callbacks.

In the new API method, the network connection states are "disconnected", "connecting", "connected", "reconnecting", and "failed". The SDK triggers the onConnectionStateChanged callback when the network connection state changes. The SDK also triggers the onConnectionInterrupted and onConnectionBanned callbacks under certain circumstances, but we do not recommend using them.

3. Improves the call rating system

v2.3.2 changes the rating parameter in the rate method to "1 to 5" to encourage more feedback from end-users on the quality of a call or the interactive live streaming. You can use this feedback for future product improvement. We strongly recommend integrating this method in your app.

4. Other improvements

• Minimizes packet loss under unreliable network conditions in the LIVE_BROADCASTING profile.
• Accelerates the video quality recovery under network congestion.
• Improves the stability in pushing streams.
• Improves the performance of the SDK on Android 6.0 or later.
• Optimizes the API calling threads.
• Checks the headset and Bluetooth device connection.
• Reduces the audio delay.
• Supports Smartisan camera.

Issues Fixed

The following issues are fixed in v2.3.2:

SDK

• Crashes on emulators, such as Yeshen and mumu.
• Crashes on Android 6.0+ due to x86 .so relocation.

Audio

• A user joins a live-streaming channel with a Bluetooth headset. The audio is not played through the Bluetooth headset when the user leaves the channel and opens another app.
• Crashes when calling the startAudioMixing method to play music files.
• A previously disabled microphone becomes enabled when the device connects to a headset.
• On Huawei Mate 20 X, a remote user cannot hear any voice when the app switches to the background and the user opens another app.
• Echo on Pixel 2.
• Cannot adjust the volume of the speaker when users change roles, join and leave channels, or a system phone or Siri interrupts.
• Users do not hear any voice for a while when an app switches back from the background.

Video

• Occasional issues when using an external video source.
• The cursor on the remote side is not in the same position as the local side when sharing the desktop.

API Changes

To improve your experience, we made the following changes to the APIs:

Added:

• isCameraExposurePositionSupported
• setCameraExposurePosition
• getConnectionState
• adjustAudioMixingPlayoutVolume
• adjustAudioMixingPublishVolume
• onConnectionStateChanged
• onCameraExposureAreaChanged
• onRemoteAudioStats

Deprecated

• onAudioQuality
• onConnectionInterrupted
• onConnectionBanned

v2.3.1

v2.3.1 is released on October 12, 2018.

New features

Disables/Re-enables the Local Audio Function

When a user joins a channel, the audio function is enabled by default.
To receive audio streams without sending any audio stream after joining a channel, this version adds the enableLocalAudio method is to disable or re-enable the local audio function.
Once the local audio function is disabled or re-enabled, the SDK returns the onMicrophoneEnabled callback, and the local audio capturing stops.
This method does not affect receiving or playing the remote audio streams.

The difference between this method and the muteLocalAudioStream method is that the enableLocalAudio method does not capture or send any audio stream, while the muteLocalAudioStream method captures but does not send audio streams.

Improvements

• Improves the SDK's adaptiveness to the Android video encoder.

Issues Fixed

• Occasional crashes when switching between front and rear cameras.
• Occasionally, failing to render the video on some Android devices.
• Occasional image freezes on some Android devices.
• Occasionally on some Android devices, a user hears a popping sound if the user leaves the channel at the same time another user is speaking.
• Communication profile: If a user disables the video and re-enables it during a one-to-one call, it takes a long time for the other user to see the image.
• LIVE_BROADCASTING profiles: Delay at the client due to incorrect statistics.
• LIVE_BROADCASTING profiles: Occasional crashes on some Android devices after a user repeats the process of switching roles between BROADCASTER and AUDIENCE.
• The timestamp in the captured raw video frames does not refresh with the frame.

v2.3.0

v2.3.0 is released on August 31, 2018.

Compatibility changes

• To support video rotation and enable better quality for the custom video source, this version deprecates the setVideoProfile method and uses the setVideoEncoderConfiguration method instead to set the video encoding configurations. You can still use the setVideoProfile method, but Agora recommends using the setVideoEncoderConfiguration method to set the video profile because:

  • During the interactive live streaming, users can set the video orientation mode as adaptive, under which the SDK can transfer rotated video frames without cropping them, thus avoiding the “big headshot” or blurry images at the player.
  • In scenarios involving external video sources, the SDK adjusts the width and height of the output video frames based on the inputting video frames, avoiding unnecessary cropping and thereby rendering more image frames at the player.

• From v2.3.0, the LiveTranscoding class is moved from the io.agora.live package to the io.agora.rtc.live package.

• Fixed a typo in the constants.java API in v2.3.0.

  • Before:

  public static final int SOFEWARE_ENCODER = 1;

  • After:

  public static final int SOFTWARE_ENCODER = 1;

• The security keys are improved and updated in v2.1.0. If you are using an Agora SDK version below v2.1.0 and wish to migrate to the latest version, see Token Migration Guide.

New Features

1. Fallback options for the interactive live streaming under unreliable network conditions

The audio and video quality of the interactive live streaming deteriorate under unreliable network conditions. To improve the efficiency of the interactive live streaming, the setLocalPublishFallbackOption and setRemoteSubscribeFallbackOption methods are added. These interfaces allow the SDK to automatically disable the video stream when the network conditions cannot support both audio and video, and enable the video when the network conditions improve. The SDK triggers the onLocalPublishFallbackToAudioOnly or onRemoteSubscribeFallbackToAudioOnly callback when the stream falls back to audio-only or when the stream switches back to the video.

2. Notifies the user that the token expires in 30 seconds

The SDK returns the onTokenPrivilegeWillExpire callback 30 seconds before a token expires to notify the app to renew it. When this callback is received, you need to generate a new token on your server and call the renewToken method to pass the newly-generated token to the SDK.

3. Returns user-specific upstream and downstream statistics, including the bitrate, frame rate, packet loss rate, and time delay

The onRemoteAudioTransportStats and onRemoteVideoTransportStats callbacks are added to provide user-specific upstream and downstream statistics, including the bitrate, frame rate, and packet loss rate. During a call or the interactive live streaming, the SDK triggers these callbacks once every two seconds after the user receives audio/video packets from a remote user. The callbacks include the user ID, audio bitrate at the receiver, packet loss rate, and time delay (ms).

4. Sets the video encoder configurations

To support scenarios with video rotation and enable better quality for the custom video source, this version deprecates the setVideoProfile method and uses the setVideoEncoderConfiguration method instead to set the video encoding configurations. You can still use the setVideoProfile method, but Agora recommends using the setVideoEncoderConfiguration method to set the video profile because:

• During the interactive live streaming, users can set the video orientation mode as adaptive, under which the SDK can transfer rotated video frames without cropping them, thus avoiding the “big headshot” or blurry images at the player.

• In scenarios involving external video sources, the SDK adjusts the width and height of the output video frames based on the inputting video frames, avoiding unnecessary cropping and thereby rendering more image frames at the player.

The VideoEncoderConfiguration class provides a set of configurable video parameters, including the dimension, frame rate, bitrate, and orientation. For more information on the API, see Set the Video Encoder Configuration.

5. Adds support for background image settings in setLiveTranscoding

The backgroundImage parameter is added to the setLiveTranscoding method allowing you to set the background image in the combined video of the interactive live streaming.

Improvements

• Improves the quality for one-on-one voice/video scenarios with optimized latency and smoothness, especially for areas like Southeast Asia, South America, Africa, and the Middle East.
• Improves the audio encoder efficiency in the interactive live streaming to reduce user traffic while ensuring the call quality.
• Improves the audio quality during a call or the interactive live streaming using the deep-learning algorithm.

Issues Fixed

• The users on the Web client cannot see the video sent from the Native client due to codec bugs.
• Excessive increase in memory usage when multiple delegated hosts start streaming in the channel.
• Occasional crashes on some Android devices.
• The remote view does not display on some devices.
• The local video cannot be enabled on some Android devices.
• Occasional ghost images.
• Occasional green lines at the bottom of the video when a user switches from a low stream to a high stream video in the COMMUNICATION profile.
• Occasional crashes after interoperating with devices of other platforms for some Android devices.
• Excessive increase in the memory usage for the host when the host frequently joins and leaves a channel that has multiple delegated hosts.
• Occasional black screens on some Android devices.
• Occasionally, the remote user cannot hear the host when the host switches between AUDIENCE and BROADCASTER.
• Occasionally, the settings applied to the background image in live transcoding do not take effect.
• Occasionally on some devices, the video height and width are swapped in the COMMUNICATION profile.
• Occasionally, the destroy method does not respond after a user enables the video and joins a channel.
• Occasional crashes on Android devices when remote users frequently join and leave the channel.
• Black screen due to failure to render the remote video on some Android devices.
• Occasionally, the audience cannot adjust the channel volume.
• Occasionally, apps do not respond on some Android devices.
• Occasional crashes on some Android devices when switching video resolutions in the interactive live streaming.
• A delegated host cannot see the video of the other hosts in the channel on some Android devices.
• The bitrates cannot reach the target values on some Android devices when a user frequently joins and leaves the communication channel with different video profiles.
• Occasional failures to capture the video of the delegated host when the hosts and the audience members frequently change roles.
• Occasional failures to capture video or publish streams on some Android devices when a user frequently joins and leaves a communication channel with different video profiles.
• Occasional crashes when calling the setCameraFocusPositionInPreview method on some devices.
• Occasional failures to enable the camera during communication on some Android devices.
• Occasional video freezes and stream publishing hangs on some Android devices after a user joins a communication or live-streaming channel.
• Occasional crashes when one of the two hosts mutes or disables the local audio while playing the background music.
• A user cannot join a communication channel after frequently changing the video encoder profiles.
• Occasional crashes on some devices when preloading the sound effects.
• Failure to render videos of lower resolutions on some Android devices.
• Occasionally, an Android client still interoperates in a communication channel when removed from Console.
• Video resolution inconsistencies between the encoder and the decoder in the LIVE_BROADCASTING profiles.
• Failure to enable the hardware encoder on some Android devices.
• Occasional video freezes in the Communication or LIVE_BROADCASTING profiles.
• Occasional crashes when calling the muteRemoteVideoStream method after joining the channel.
• Occasional video freezes on some Android devices when switching from the COMMUNICATION profile to the LIVE_BROADCASTING profiles.
• Occasional crashes on some Android devices when frequently turning on and off the camera flash during the interactive live streaming.
• The host cannot receive the audio/video stream of the delegated host on some Android devices.
• Occasional crashes on some Android devices when setting the video encoder profile of an external video source during the interactive live streaming.
• Incorrect video orientation on some Android devices when setting the video profile of an external video source during the interactive live streaming.
• Occasionally on some Android devices, the video fallback option does not take effect under poor network conditions.
• Occasional crashes on some Android devices when a user frequently changes the token.
• Occasional failures to split the screen on some Android devices.
• The CDN audience on some Android devices cannot see the video of the host.
• Occasional video freezes when switching from multiple hosts to a single host.
• Occasional inter-operational failures between SIP devices and the SDK.
• Occasionally on Mi 8, the local video cannot be seen locally or remotely.
• Occasionally on some Android devices, users cannot see each other.
• Occasional echo issues when using a specific audio card.
• Occasional video delays on some Android devices.
• Occasional crashes on some Android devices when transmitting the video streams.

API Changes

To improve your experience, we made the following changes to the APIs:

To avoid adding too many users with the same uid into the CDN publishing channel, the following API method is deleted in v2.3.0, and the return value type of addUser is changed from void to int.

• setUser

The following API methods are deleted and no longer supported in v2.3.0. Agora provides the Recording SDK for better recording services. For more information on the Recording SDK, see Release Notes for Agora Recording SDK.

• startRecordingService
• stopRecordingService
• refreshRecordingServiceStatus

The following deprecated API methods are deleted and no longer supported from v2.3.0:

• monitorConnectionEvent
• monitorBluetoothHeadsetEvent
• monitorHeadsetEvent
• setPreferHeadset
• switchView
• setSpeakerphoneVolume

v2.2.3

v2.2.3 is released on July 5, 2018.

Compatiblity changes

The security keys are improved and updated in v2.1.0. If you are using an Agora SDK version below v2.1.0 and wish to migrate to the latest version, see Token Migration Guide.

Issues Fixed

• Occasional online statistics crashes.
• The host’s voice distorts occasionally on some Android devices.
• Occasional crashes during the interactive live streaming.
• Excessive increase in the memory usage when multiple delegated hosts start streaming in the channel.
• Receiving the onLeaveChannel callback long after a user has left the channel on some Android devices.
• Failing to report the uid and volume of the speaker in a channel.
• Unsteady voice volume of the host in the interactive live streaming.
• Occasional video freezes during the interactive live streaming.
• Occasional ANR (application no response) problem on some Android devices after a user turns off the camera to end a video session.
• Occasional video freeze after a view size change.

v2.2.2

v2.2.2 is released on June 21, 2018.

Issues Fixed

• Fixed occasional online statistics crashes.
• Fixed occasional audio crashes on some Android devices.
• Fixed the issue that the host’s voice distorts occasionally on some Android devices.
• Fixed the issue of failing to report the uid and volume of the speaker in a channel.
• Fixed the issue of receiving the onLeaveChannel callback long after a user has left the channel on some Android devices.
• Fixed the issue of occasional video freeze after a view size change.
• Fixed the occasional ANR (application no response) problem on some Android devices after the user turns off the camera to end a video session.

v2.2.1

v2.2.1 is released on May 30, 2018.

Issues Fixed

• Occasional crashes during gaming on some Android devices.
• The soundtrack pointer cannot be retrieved on some Android devices.
• Occasional crashes on some Android devices.
• The audio volume on some Android devices cannot be adjusted after a headset is plugged in.

v2.2.0

v2.2.0 is released on May 4, 2018.

New Features

1. Play the audio effect in the channel

Adds a publish parameter in the playEffect method for the remote user in the channel to hear the audio effect played locally.

If your SDK is upgraded to v2.2 from a previous version, pay attention to the functional changes of this API.

2. Deploy the proxy at the server

We provide a proxy package for enterprise users with corporate firewalls to deploy before accessing our services.

3. Get the remote video state

Adds the remoteVideoStateChangedOfUid method to get the state of the remote video stream.

4. Add watermarks on the streaming video

Adds the watermark function for users to add a PNG file to the local or CDN streaming as a watermark. Adds the addVideoWatermark and clearVideoWatermarks methods to add and delete watermarks in the local live streaming. Adds the watermark parameter in the LiveTranscording interface to add watermarks in CDN streaming.

Improvements

1. Audio volume indication

Improves the enableAudioVolumeIndication method. This method once enabled, sends the audio volume indication of the speaker in its callback at set intervals, regardless of whether anyone is speaking in the channel.

2. Network quality detection during a session

To meet the customers’ need for real-time network quality detection in the channel, the onNetworkQuality method improves its data accuracy.

3. Last mile network quality detection before joining a channel

To test if the customers’ network condition can support voice or video calls before joining the channel, the onLastmileQuality callback changes the detection from a fixed bitrate to the bitrate set by the customer in the setVideoProfile method to improve data accuracy. When the network condition is unknown, the SDK triggers this callback once every two seconds.

4. Audio quality enhancement

Improves the audio quality in scenarios that involve music playback.

Issues Fixed

• Occasional screen display abnormalities when a large number of audience members join as the host in a live-streaming channel.
• Fixes occasional CDN streaming abnormalities when some app switches to run in the background during the interactive live streaming.

v2.1.3

v2.1.3 is released on April 19, 2018.

In v2.1.3, Agora updates the bitrate values of the setVideoProfile method in the LIVE_BROADCASTING profiles. The bitrate values in v2.1.3 stay consistent with those in v2.0.

Issues Fixed

Occasional recording failures on some phones when a user leaves a channel and turns on the built-in recording device.

Improvements

Improves the performance of screen sharing by shortening the time interval between which users switch from screen sharing to the normal Communication or LIVE_BROADCASTING profiles.

v2.1.2

v2.1.2 is released on April 2, 2018.

If you upgrade the SDK to v2.1.2 from a previous version, the live-streaming video quality is better than the communication video quality in the same resolutions, resulting in the live streaming using more bandwidth.

New Features

Extends the setVideoProfile method to enable users to manually set the resolution, frame rate, and bitrate of the video.

Issues Fixed

Video freeze in DTX + AAC mode.

v2.1.1

v2.1.1 is released on March 16, 2018.

Agora has identified a critical issue in SDK v2.1. Upgrade to v2.1.1 if you are using Agora SDK v2.1.

v2.1.0

v2.1.0 is released on March 7, 2018.

New Features

1. Voice Optimization

Adds a scenario for the game chat room to reduce the bandwidth and cancel the noise with the setAudioProfile method.

2. Enhance the audio effect input from the built-in microphone

In an interactive streaming scenario, the host can enhance the local audio effects from the built-in microphone with the setLocalVoiceEqualization and setLocalVoiceReverb methods by implementing the voice equalization and reverberation effects.

3. Online statistics query

Adds RESTful APIs to check the status of the users in the channel, the channel list of a specific company, and whether the user is an audience or a host. For details, see Online Statistics Query API.

4. 17-way video

Adds the support of 17-way video in the interactive live streaming, see Video for 7+ Users.

5. Video source customization

Supports the default video-capturing features provided by the camera and the customized video source.

6. Renderer customization

Supports the default functions provided by the renderers to display the local and remote videos to meet your requirements. We provide a set of interfaces for customized renderers.

7. Injecting an external video stream

Adds the function of injecting an external video stream to the ongoing live streaming.

8. Camera focus change

Adds an onCameraFocusAreaChanged callback to report to the app when the camera focus area changes.

Improvements

Improvement	Description
Video Freeze Rate	Reduces the video freeze rate in the audience mode and for specific devices.
Authentication	Supports a new authentication mechanism. Each legacy Dynamic Key (Channel Key) corresponds to a single privilege (for example, joining a channel), but each token in the new authentication mechanism includes all privileges (for example, joining a channel, hosting in, and stream-pushing).
Hardware Encoder	Enables the H.264 hardware encoder on the Qualcomm, MTK, HiSilicon, and Orion chips.
Hardware Encoder	Improves the bitrate control for the hardware encoder.
Billing Optimization	Small video resolutions are charged according to the voice-only mode. For example, 16 × 16.

Issues Fixed

• Occasional playback noise on specific devices.
• Occasional crackling voice playback on specific devices.
• Occasional crashes.

v2.0.2

v2.0.2 is released on December 15, 2017, and fixes occasional audio routing issues.

v2.0

v2.0 is released on December 6, 2017.

New Features

• Adds the setRemoteVideoStreamType and enableDualStreamMode methods in the COMMUNICATION profile to support dual streams.

• Adds the camera management function in the COMMUNICATION and LIVE_BROADCASTING profiles by adding the following API methods:

  Name	Description
  isCameraZoomSupported	Checks whether the device supports camera zoom.
  isCameraTorchSupported	Checks whether the device supports camera flash.
  isCameraFocusSupported	Checks whether the device supports camera manual focus.
  isCameraAutoFocusFaceModeSupported	Checks whether the device supports camera auto-face focus.
  setCameraZoomFactor	Sets the camera zoom ratio.
  getCameraMaxZoomFactor	Gets the maximum zoom ratio of the camera.
  setCameraFocusPositionInPreview	Sets the position for manual focus and activates focusing.
  setCameraTorchOn	Sets the device to turn on the camera flash.
  setCameraAutoFocusFaceModeEnabled	Sets the device to start auto-face focusing.

• Supports external audio sources in the COMMUNICATION and LIVE_BROADCASTING profiles by adding the following API methods:

  Name	Description
  setExternalAudioSource	Enables the external audio source function.
  pushExternalAudioFrame	Pushes the external audio frame to the Agora SDK.

• Provides a set of RESTful APIs to ban a peer user from the server in the COMMUNICATION and LIVE_BROADCASTING profiles. Contact support@agora.io to enable this function, if required.
• Supports the following Android emulators: NOX, Lightning, and Xiaoyao.

Improvements

Optimizes the hardware encoder by supporting encoding resolutions as low as 64 x 64.

Issues Fixed

• Audio routing and Bluetooth issues.
• Optimizes the volume balance control.

v1.14

v1.14 is released on October 20, 2017.

New Features

• Adds the setAudioProfile method to set the audio parameters and scenarios
• Adds the setLocalVoicePitch method to set the local voice pitch
• LIVE_BROADCASTING: Adds the setInEarMonitoringVolume method to adjust the volume of the in-ear monitor

Improvements

• Optimizes the audio at high bitrates.
• LIVE_BROADCASTING: The audience can view the host within one second in a single-stream mode (226 ms on average, and 204 ms under good network conditions).
• Adds the ability to reduce the bandwidth.
  • Before v1.14: If you muted the audio of a specific user, the network still sent the stream.
  • Starting from v1.14: If you mute the audio of a specific user, the network will not send the stream of the user to reduce the bandwidth.
• Accurate control over the bitrate:
  • Before v1.14: Inaccurate control over the bitrate often caused huge fluctuations, leading to network congestion and higher rates of packet and frame loss. This affected the accuracy of the bandwidth estimation module, especially under poor network conditions.
  • Starting from v1.14: Accurate control over the bitrate prevents huge fluctuations avoiding network congestion and shortening the transmission latency.

Issues Fixed

Camera related issues on Android devices.

v1.13.1

v1.13.1 is released on September 28, 2017, and optimizes the echo issue under certain circumstances.

v1.13

v1.13 is released on September 4, 2017.

New Features

• Adds the function to dynamically enable and disable acquiring the sound card in the interactive live streaming.
• Adds the function to disable the audio playback.
• Supports the profile configuration for stream-pushing on the client side.
• Adds the onClientRoleChanged callback to report to the app on a user role switch between the host and the audience in the interactive live streaming.
• Supports the push-stream failure callback on the server side.

Improvements:

The video profile is controllable by the software codec.

Issues Fixed:

Occasional crashes on some devices

v1.12

v1.12 is released on July 25, 2017.

New Features:

• Adds the aes-128-ecb encryption mode in the setEncryptionMode method.
• Adds the quality parameter in the startAudioRecording method to set the recording audio quality.

Issues Fixed:

• Android: Bluetooth issues related to audio routing.
• Android/iOS/Mac/Windows: Occasional crashes.