Documentation
Interactive Live Streaming Premium
Agora.io Community
English
search-icon
Release Notes
Last updated 2021/10/14 03:43:27

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

v3.5.1

v3.5.1 was released on October 14, 2021.

New features

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

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

3. 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 pushAudioFrame[2/3] and adds pushAudioFrame[3/3] 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.

4. 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 track index of the current music file.
  • selectAudioTrack: Specifies the playback audio track of the current music file. The index value of the specified audio track must be smaller than or equal to the return value of getAudioTrackCount.
  • setAudioMixingDualMonoMode: Sets the channel mode of the current music file to original mode, left channel mode, right channel mode, or mixed channel mode.

5. 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. Audio device errors

This release adds the following error codes in LOCAL_AUDIO_STREAM_ERROR:

  • LOCAL_AUDIO_STREAM_ERROR_RECORD_INVALID_ID(9), which indicates that the ID of the audio capture device is invalid.
  • LOCAL_AUDIO_STREAM_ERROR_PLAYOUT_INVALID_ID(10), which indicates that the ID of the audio playback device is invalid.

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) to NETWORK_TYPE. 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.
  • In scenarios with high CPU usage, the audio experience is improved when the sound card is used for audio capture.
  • Adds support for audio playback devices with S/PDIF (Sony/Philips Digital Interface).
  • After enabling deep-learning noise reduction, 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.
  • Window sharing stopped after a user shared a QQ browser window and switched the browser tab.
  • 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.
  • The SDK repeatedly triggered the onAudioDeviceStateChanged callback when the user connected or disconnected an audio device.
  • As of v3.4.5, the return value was inaccurate when you called joinChannel multiple times in a row.
  • 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.
  • Echoes could occur when you used a fiber optic speaker.
  • 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

Deprecated

  • pushAudioFrame[2/3]
  • getAudioMixingDuration

v3.5.0.4

v3.5.0.4 was released on September 26, 2021.

This release fixed the following issues:

  • When you called startAudioDeviceLoopbackTest to start the audio device loopback test after joining and then immediately leaving a channel, the content of the AudioVolumeInfo array reported by the onAudioVolumeIndication callback was incorrect.
  • 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.
  • 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.
  • 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 issue where the user could not receive the onRenderVideoFrame callback from the registered raw video data observer when the setupLocalVideo and setupRemoteVideo methods were not called.

v.3.5.0

v3.5.0 was released on July 20, 2021.

New features

Custom video renderer

During a real-time audio and video interaction, the SDK enables the default renderer to render video. Starting from this release, Agora adds support for custom video rendering via the MediaIO method. If you want to customize the video rendering, you can use the IVideoSink class to customize the video renderer, and then call setLocalVideoRenderer or setRemoteVideoRenderer to render the local or remote video.

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. Virtual background (beta)

This release optimizes the portrait edge effect of the virtual background.

3. Audio error code

To help troubleshoot audio issues, this release adds the ERR_ADM_WIN_CORE_SERVRE_SHUT_DOWN (1735) error code, which reports that the Windows Audio service is disabled. You need to either enable the Windows Audio service or restart the device.

4. Additional improvements

This release also improves the following:

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

  • Occasionally, the received remote audio and video were out of sync when a user used the Push method to customize the video source.
  • 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

This release added the following APIs:

v3.4.6

v3.4.6 was released on July 15, 2021 and improved the stability of the SDK.

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 (7) and AES_256_GCM2 (8) encryption modes in ENCRYPTION_MODE. 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 (7) and AES_256_GCM2 (8) encryption modes.

This release also changes the default encryption mode from AES_128_XTS (1) to AES_128_GCM2 (7). 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 ENCRYPTION_MODE to AES_128_XTS (1).

See Media Stream Encryption.

Once you enable the built-in encryption, all users in the same channel must use the same encryption mode and key, including the server-side users such as the Agora recording service.

2. Media stream publishing behavior changes

To flexibly control the publishing state in multiple channels, this release optimizes the IChannel 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.
  • After calling setClientRole(BROADCASTER), the local user publishes audio and video streams by default. You no longer need to call publish.
The following APIs have the same function. If you call them together, the one called later takes effect.
  • publishLocalAudio = false serves the same function as muteLocalAudioStream(true).
  • publishLocalVideo = false serves the same function as muteLocalVideoStream(true).

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

  • muteLocalAudioStream and muteLocalVideoStream of IRtcEngine do not take effect for channels created by the IChannel class, so you need to use the muteLocalAudioStream and muteLocalVideoStream of the IChannel 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. startAudioMixing changes

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

New features

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

Before you use virtual backgrounds, ensure that the relevant dynamic library is integrated and that the device performance and user scenarios meet the requirements. See the enableVirtualBackground documentation.

2. Local encoded video data

This release adds the registerVideoEncodedFrameObserver method, which you can use to register the local encoded video data observer. You can get the local encoded video data from the onVideoEncodedFrame callback function to implement custom functions, such as recording video, taking screenshots, and image enhancement.

Improvements

1. Performance optimization

Agora has optimized internal threads of the SDK, which reduces CPU usage by about 20% on low-end devices.

2. CDN live streaming

To be more transparent to users about errors and events in CDN live streaming, 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 CDN live streaming. If you want to start new streaming, use a new streaming URL.

3. Custom video source

You can use the setVideoSource method to customize a video source, that is, use the MediaIO method for custom video capture. To enhance the flexibility of video capture, as of this release, Agora supports switching from custom video capture by MediaIO to SDK capture directly in the channel. See How can I switch from custom video capture to SDK capture.

4. Media device state

To report media device states more accurately, this release optimizes the enumerations of MEDIA_DEVICE_STATE_TYPE as follows:

  • Changes the definition of MEDIA_DEVICE_STATE_ACTIVE (1) from "The device is ready for use" to "The device is in use", which is more consistent with its name.
  • Adds MEDIA_DEVICE_STATE_IDLE (0), which reports the device is ready for use.

MEDIA_DEVICE_STATE_TYPE is reported in the onAudioDeviceStateChanged and onVideoDeviceStateChanged callbacks.

5. Music file state

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

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.
  • When the audio scenario was AUDIO_SCENARIO_CHATROOM_GAMING, after the local user played a video through the system media player, started screen sharing, and used a sound card to sample audio streams, the video sound heard by remote users contained noise.
  • Under poor network conditions, users were occasionally unable to switch roles.

API changes

Added

Modified

Deprecated

  • publish and unpublish in IChannel

v3.4.3

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

  • 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. This release fixed the following issues:

  • 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.
  • Occasional crashes after integrating the libagora_ai_denoise_extension.dll library.

v3.4.1

When the v3.4.0 or v3.4.1 SDK interoperates with the SDK earlier than v3.0.0, video freezes may occur. To interoperate with SDKs earlier than v3.0.0, Agora recommends that you upgrade the SDK to v3.4.2. For details, see v3.4.2.

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

When the v3.4.0 or v3.4.1 SDK interoperates with the SDK earlier than v3.0.0, video freezes may occur. To interoperate with SDKs earlier than v3.0.0, Agora recommends that you upgrade the SDK to v3.4.2. For details, see v3.4.2.

v3.4.0 was released on April 16, 2021.

Compatibility changes

Integration changes

  1. WGC library

This release adds the libagora-wgc.dll dynamic library, which is related to window sharing. To upgrade the SDK to v3.4.0 or later, ensure that you have copied this dynamic library to the folder where the agora_rtc_sdk.dll file is located.

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

  1. Music file playback state

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 AUDIO_MIXING_ERROR_TYPE and replaces it with AUDIO_MIXING_REASON_TYPE instead. Using AUDIO_MIXING_REASON_TYPE, you can get the reason for the change of the playback state, such as start, pause, stop or fail.
  • Modifies some logic of reporting AUDIO_MIXING_STATE_TYPE. For example, as of this release, when looping music, the SDK triggers the AUDIO_MIXING_STATE_PLAYING 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.

  1. Volume control of microphone

As of this release, the adjustRecordingSignalVolume method only adjusts the volume of the signal captured by the microphone. If you need to adjust the volume of the signal captured by the sound card, use the adjustLoopbackRecordingSignalVolume method instead.

New features

1. Volume control of sound cards

This release adds the adjustLoopbackRecordingSignalVolume method. You can call this method after calling enableLoopbackRecording to adjust the volume of the signal captured by the sound card.

2. Playback progress of audio effect files

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

  • playEffect[2/2]: 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[1/2] method. You can use playEffect[2/2] instead.

Improvements

1. Video encoding

The Agora SDK allows you to use degradationPreference 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, degradationPreference 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

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

This release optimizes window sharing as follows:

  • On Windows 10 1809 and later, the startScreenCaptureByWindowId method supports sharing most UWP (Universal Windows Platform) application windows and windows rendered using DirectX. During window sharing, a yellow border appears around the shared window, and calling captureMouseCursor(false) does not take effect.
  • On operating systems before Windows 10 1089, when sharing a specified window, the area overlapped by other windows is blacked out.

4. Playback progress of music files

To control the playback progress of music files, this release is optimized as follows:

  • 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.
  • Deprecates the getAudioMixingDuration method and adds a new method with the same name in its place. The new getAudioMixingDuration method allows you to get the duration of a local music file before playing it.

5. 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 method again before the current recording ends, the SDK reports this error code.

6. Media device errors

To help users better understand the cause of local video or audio errors, this release adds the following new error codes:

  • 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.
  • To LOCAL_AUDIO_STREAM_ERROR:
    • LOCAL_AUDIO_STREAM_ERROR_NO_RECORDING_DEVICE(6), which indicates that the SDK cannot find the local audio-capture device.
    • LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE(7), which indicates that the SDK cannot find the local audio-playback 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.
  • The onAudioVolumeIndication callback returned incorrect volume information after you called enableSoundPositionIndication(true).
  • When sharing a File Explorer window on certain Windows 10 devices, remote users saw the title bar of the window in an abnormal color.

API changes

Added

Modified

Deprecated

  • getAudioMixingDuration[1/2]
  • startAudioRecording[2/3]
  • playEffect[1/2]
  • startAudioMixing[1/2]
  • AUDIO_MIXING_ERROR_TYPE

v3.3.2

v3.3.2 was released on March 29, 2021. This release fixed the issue where remote users saw a distorted image when the local user minimized the shared screen with the genie effect on Mac devices.

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 ENCRYPTION_MODE:

  • AES_128_GCM: 128-bit AES encryption, GCM mode.
  • AES_256_GCM: 256-bit AES encryption, GCM mode.
Once you enable the built-in encryption, all users in the same channel must use the same encryption mode and key, including the server-side users such as the Agora recording service.

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.

API changes

This release adds the following APIs:

v3.3.0

v3.3.0 was released on January 22, 2021.

Compatibility changes

1. Integration change

This release adds the following frameworks:

  • libagora-core.dll: The Agora basic calculation framework.
  • av1.dll: The AV1 framework for screen sharing.

To integrate the SDK into your project, see Integrate the SDK.

2. Changes to subscribing behavior

This release deprecates setDefaultMuteAllRemoteAudioStreams and setDefaultMuteAllRemoteVideoStreams and 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. Deep-learning noise reduction

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

Before enabling deep-learning noise reduction, integrate the libagora_ai_denoise_extension.dll dynamic library into your project files.

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 logConfig member variable to RtcEngineContext. You can use logConfig 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. Screen Sharing

As of v3.3.0, the SDK automatically enables DXGI (DirectX Graphics Infrastructure) to capture the screen as appropriate, which significantly increases the video frame rate and resolution supported by screen sharing.

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

This release fixed the following issues:

  • Occasionally, local users could not play remote audio streams.
  • 360 Brain of Security (online shopping mode) automatically blocked the application program from running.

API changes

Added

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.
  • In scenarios where MediaIO was used to customize the video source and a user left the channel, occasional crashes occurred when the user joined or left the channel again.
  • After you called enableEncryption, the SDK did not trigger the onFirstLocalVideoFramePublished callback.
  • Occasional abnormalities occurred when a user used virtual cameras to capture the video.

v3.2.0

v3.2.0 was released on November 30, 2020.

Compatibility changes

1. Integration change

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

  • libagora-fdkaac.dll: The Fraunhofer FDK AAC dynamic library.
  • libagora-mpg123.dll: The mpg123 dynamic library.
  • libagora-soundtouch.dll: The SoundTouch dynamic library.
  • libagora-ffmpeg.dll: 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.dll file is located.

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.

Transport layer encryption affects the following indicators:
  • Size of the SDK package: For details, see Product Overview.
  • The rendering time of the first video frame: The rendering time (median) of the first video frame increases by 0 ~ 70 ms compared to that in v3.1.0.

    • 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 user experience in the meeting scenario, this release adds the following:

    • Audio profile: To improve the audio experience for multi-person meetings, this release adds AUDIO_SCENARIO_MEETING(8) in setAudioProfile.
    • Screen sharing:
      • To allow a user to enable shared slides in presentation mode, this release adds support for enabling the shared window (such as slides, web video, or web document) in full-screen mode during the window sharing.
      • This release adds the LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_CLOSED(12) error code, notifying you that a window shared by the window ID has been closed, or a full-screen window shared by the window ID has exited full-screen mode.
      • This release optimizes smoothness and image quality of screen sharing with the CONTENT_HINT_DETAILS type in a poor network environment.

    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. CDN live streaming with transcoding

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

    4. Interactive streaming delay

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

    API changes

    Added

    Deprecated

    v3.1.2

    v3.1.2 was released on September 15, 2020.

    This release fixed the issue that the trigger timing of the onFirstLocalVideoFrame and onFirstRemoteVideoFrame callbacks is not accurate.

    v3.1.1

    v3.1.1 was released on August 28, 2020.

    This release changes the AREA_CODE 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 initialize, ensure that you use the latest area code when migrating from an earlier SDK version.

    v3.1.0

    v3.1.0 was released on Aug 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. 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 features for screen sharing:

    • Bringing the window to the front: By adding the windowFocus member to the ScreenCaptureParameters struct.
    • Excluding specified windows from screen sharing: By adding the excludeWindowList member to the ScreenCaptureParameters struct.
    • Reporting more specific local video states during a screen share: By adding the state code LOCAL_VIDEO_STREAM_STATE_CAPTURING(1) and the error code LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED(11) to the onLocalVideoStateChanged callback.
    • Using MediaIO mode for customized video source: Adding the IVideoSource class, which defines the custom video source.

    3. CDN live streaming

    To improve the user experience in CDN live streaming, this release adds the onRtmpStreamingEvent callback to report events during CDN live streaming, 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: 16 Kbps
    		•
  • For the interactive streaming profile: 52 Kbps
  • For the communication profile: 16 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. 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.

    Issues fixed

    This release fixed the occasional howling issue on some Huawei laptops.

    API changes

    Added

    Deprecated

    • setEncryptionSecret
    • setEncryptionMode
    • onFirstLocalAudioFrame

    Deleted

    • Warning code: WARN_ADM_IMPROPER_SETTINGS(1053)

    v3.0.1.1

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

    • Crashes when calling the registerVideoRenderFactory (deprecated) method.
    • The image enhancement feature does not work.

    v3.0.1

    v3.0.1 was released on May 27, 2020.

    Compatibility changes

    Frame position for the video observer

    As of this release, to get the video frame from the onPreEncodeVideoFrame callback, you must set POSITION_PRE_ENCODER(1<<2) in getObserverFramePosition 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 the advanced guide Set the Voice Changer and Reverberation Effects for more information.

    3. Fill mode

    To improve the user experience of watching videos, this release adds a video display mode RENDER_MODE_FILL(4). 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

    4. Data post-processing in multiple channels

    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

    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.

    Fixed issues

    • Audio mixing issues and abnormal loopback test results.
    • A black screen issue when a co-host shares the screen.
    • Inaccurate report of the onClientRoleChanged callback, authentication with an App ID and token, and a garbled log directory.

    API changes

    This release adds the following APIs:

    v3.0.0.2

    v3.0.0.2 was released on Apr 22, 2020.

    New features

    Specifying the area of connection

    This release adds areaCode member in the RtcEngineContext struct for specifying the area of connection when creating an IRtcEngine 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 black screen issue when a co-host shares the screen.

    API changes

    Added

    areaCode member in the RtcEngineContext struct

    v3.0.0

    v3.0.0 was released on Mar 5, 2020.

    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.

    New features

    1. Multiple channel management

    To enable a user to join an unlimited number of channels at a time, this release adds the IChannel and IChannelEventHandler classes. By creating multiple IChannel 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.

    • onPreEncodeVideo: 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 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. Image enhancement

    Adds setBeautyEffectOptions for enabling image enhancement in scenarios such as video social networking, an online class, or interactive live streaming. You can call this method to set parameters including contrast, brightness, smoothness, red saturation, and so on. See Image Enhancement 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 profile.

    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 3A sample rate of 32 kHz, music encoding, mono, and a bitrate of up to 64 Kbps.

    2. Mirror mode

    This release enables you to set a mirror effect for the stream to be encoded or for the streams to be rendered.

    • 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:
      • 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.
      • We also add the mirrorMode member to the VideoCanvas struct. You can use setupLocalVideo to set a mirror effect for the local view, or use setupRemoteVideo to set a mirror effect for 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

    4. Screen sharing

    This release enables window sharing of UWP (Universal Windows Platform) applications when you call startScreenCaptureByWindowId.

    5. 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 CDN live streaming.

    API changes

    Added

    Deprecated

    • RtcEngineParameters class
    • enableWebSdkInteroperability
    • setLocalRenderMode¹
    • setRemoteRenderMode¹
    • setLocalVideoMirrorMode
    • onFirstRemoteAudioDecoded, and onFirstRemoteAudioFrame, replaced by onRemoteAudioStateChanged
    • onStreamPublished and onStreamUnpublished, replaced by onRtmpStreamingStateChanged

    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 profile only, also works in the COMMUNICATION profile.
    • In some one-to-one call, the downlink media stream falls back to audio-only under poor network conditions.

    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. Supporting RGBA raw video data

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

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

    Improvements

    1. Improving the watermark function in Live Interactive Streaming

    This release adds a new addVideoWatermark method with the following settings:

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

    Issues fixed

    Miscellaneous

    A typo in the IAgoraRtcEngine.h file.

    API changes

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

    Added

    Deprecated

    • startAudioRecording
    • addVideoWatermark

    v2.9.0

    v2.9.0 is released on Aug 16, 2019.

    Compatibility changes

    1. RTMP streaming

    In this release, we deleted the following methods:

    • configPublisher
    • setVideoCompositingLayout
    • clearVideoCompositingLayout

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

    For how to implement the new methods, see Push Streams to the CDN.

    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.

    The triggering timing of the new callback is different from the old one. The new onRemoteVideoStateChanged callback is triggered only when the remote video state has changed.

    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 an interactive 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_BROADCASTING channels interact with each other.

    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.

    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 interactive 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. Improving the screen sharing quality

    This release improves the sharpness of text during screen sharing in the COMMUNICATION profile, particularly when the network condition is poor. Note that this improvement takes effect only when you set ContentHint as Details(2).

    4. Supporting hot-swappable devices

    To improve the experience in using video devices on Windows, this release adds support for hot-swappable devices with the context member in the RtcEngineContext class. Setting this member also achieves the following functions:

    • Supports plugging or unplugging video devices before or after joining the channel.
    • Supports plugging or unplugging video devices when the app uses the external video renderer.
    • Fixes crashes caused by plugging or unplugging the camera when the device is powered on.
    • Minimizes the time to join a channel.

    5. Other Improvements

    • 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.
    • Invalid call of the muteRemoteAudioStream method.
    • Occasionally no audio.

    Video

    • The onRemoteVideoStateChanged callback behaves unexpectedly.

    Miscellaneous

    • Occasionally mixed streams in RTMP streaming.
    • Occasional crashes occur.
    • Failure to join the channel.

    API changes

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

    Added

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

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

    API changes

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

    Added

    Deprecated

    v2.4.1

    V2.4.1 is released on Jun 12th, 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 RTMP

    To improve the usability of the RTMP 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 RTMP 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.
    		•
    RtcImage 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 interactive live streaming scenarios, the host can send shopping links, digital coupons, and online quizzes to the audience for more diversified interactive live streaming 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. Optimized screen sharing

    To avoid image cropping and distortion in screen sharing, v2.4.1 optimizes the encoding algorithms. In this release Agora applies the following encoding algorithms:

    Suppose the value of dimensions is 1920 x 1080 pixels, that is, 2073600 pixels:

    • If the value of the screen dimensions is lower than that of the encoding dimensions, for example, 1000 x 1000 pixels, the SDK uses 1000 x 1000 pixels for encoding.
    • If the value of the screen dimensions is higher than that of the encoding dimensions, for example, 2000 x 2000 pixels, the SDK uses the maximum value under 1920 x 1080 pixels with the aspect ratio of the screen dimension (1:1) for encoding, that is, 1440 x 1440 pixels.

    Agora uses the dimensions value in theScreenCaptureParameters class to calculate the charges. If you do not set the value of **dimensions, the SDK uses the default value of 1920 x 1080 to calculate the charges.

    You can also choose whether or not to capture the mouse cursor when sharing the screen. v2.4.1 adds the captureMouseCursor parameter in the ScreenCaptureParameters class and captures the mouse by default.

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

    4. State of the RTMP streaming

    v2.4.1 adds the onRtmpStreamingStateChanged callback to indicate the state of the RTMP streaming 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.

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

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

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

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

    9. Miscellaneous

    v2.4.1 supports 64-bit operation systems.

    Improvements

    1. Reporting more statistics

    2. 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 enableAudioQualityIndication method.
    • Improved the stability of video services.
    • Improved the stability of RTMP streaming services.
    • Improved the compatibility of the SDK with video devices.

    Issues fixed

    Audio

    • The app cannot play multiple local audio effect files simultaneously. - windows

    Video

    • The sending client sends the low stream unexpectedly.
    • The user cannot switch between the screen sharing stream and the camera stream.

    Miscellaneous

    • Users still receive the onNetworkQuality callback after leaving the channel.
    • Occasional crashes.

    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

    Deprecated

    • enableAudioQualityIndication
    • onCameraReady. Use LOCAL_VIDEO_STREAM_STATE_CAPTURING(1) in the onLocalVideoStateChanged callback instead.
    • onVideoStopped. Use LOCAL_VIDEO_STREAM_STATE_STOPPED(0) in 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.
    • The ERR_VDM_WIM_DEVICE_IN_USE(1502) error code. Use LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY(3) in the 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. Advanced screen sharing

    v2.4.0 upgrades screen sharing and provides the following advanced functions:

    v2.4.0 deprecates the startScreenCapture method. We recommend using the new methods for screen sharing. With the new methods, developers need to design the code logic to obtain the screenRect and windowId. For more information, see Share the Screen.

    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.

    3. Tracking the sound position of a remote user

    v2.4.0 adds the enableSoundPositionIndication and setRemoteVoicePosition. 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. Audio device loopback test

    v2.4.0 adds the startAudioDeviceLoopbackTest and stopAudioDeviceLoopbackTest methods for testing whether the local audio devices are working properly. The test involves only the local audio devices and does not report the network condition.

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

    v2.4.0 adds the setRemoteUserPriority method for setting the priority of a remote user. 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.

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

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

    9. Setting the background image for LiveTranscoding

    v2.4.0 adds the backgroundImage parameter in the LiveTranscoding Class in Windows to set the background image in the combined video of the interactive live streaming.

    10. Cloud proxy

    Adds 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.
    • 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.
    • Improves the video smoothness and reduces the time delay when sharing a screen under poor network conditions.

    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.
    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
    • Occasional crashes.
    • The stream for screen sharing is cropped when lowering the screen resolution. We highly recommend using the new methods in v2.4.0 for screen sharing. With the new screen sharing parameters, these methods separate the stream for screen sharing from the camera-captured stream. See Share the Screen for more information.
    • A region cannot be shared if one of its coordinates is negative.
    • Occasional echoes.
    • 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
    Deprecated
    • startEchoTest
    • startScreenCapture
    • setVideoQualityParameters

    v2.3.3

    v2.3.3 is released on January 24, 2019.

    Improvements

    v2.3.3 optimizes the screen-sharing algorithm for different scenarios. The video smoothness and quality are enhanced when a user presents slides or browses websites. v2.3.3 also improves the initial image quality in the COMMUNICATION profile.

    Issues fixed

    Occasional inaccurate statistics returned in the onNetworkQuality callback.

    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 call smoothness.
    • Reduces video freezes in the LIVE_BROADCASTING profile.

    Before upgrading your SDK, ensure that your version is:

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

    If you using an Agora SDK version v2.0.8 and wish to migrate the v2.3.2, refer to the Migration Guide for major API changes.

    New features

    1. External video data (Push Mode)

    v2.3.2 adds the following methods, allowing you to use the external video during a call or in interactive live streaming:

    The application can encapsulate the external video frames in the AgoraVideoFrame format and push them to the SDK for encoding and transmitting.

    This feature applies to scenarios where a user captures and renders the external video and then pushes the video frames to the SDK for transmission (the application processes the rendering).

    2. External audio sink (Pull Mode)

    v2.3.2 adds the following methods to improve the user experience in playing the external audio:

    The application pulls the decoded audio frames (mixed from the remote users) from the media engine for external playback.

    The difference between pullAudioFrame and onPlaybackAudioFrame:

    • pullAudioFrame: The application pulls the audio frames and:

      • Specifies the number of audio samples for playback.

      • Adjusts the frame buffer.

      • Allows for a delay in processing the audio frame.

        This method avoids problems caused by jitter in the external audio, such as an unsynchronized audio playback.

    • onPlaybackAudioFrame: The SDK pushes the audio frames to the application once every 10 ms. Any delay in processing the audio frames may result in audio jitter.

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

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

    5. Fallback options for interactive live streaming under unreliable network conditions

    Unreliable network conditions affect the overall quality of the interactive live streaming. v2.3.2 adds the setLocalPublishFallbackOption and setRemoteSubscribeFallbackOption methods to allow the SDK to:

    • Automatically disable the video stream when the network conditions cannot support both audio and video, or
    • 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 switches back to the video.

    6. Upstream and Downstream statistics of each remote user/host

    v2.3.2 adds the onRemoteAudioTransportStats and onRemoteVideoTransportStats callbacks to provide the upstream and downstream statistics of each remote user/host. During a call or interactive live streaming, the SDK triggers these callbacks once every two seconds after the local user receives audio/video packets from a remote user. The callbacks return the user ID, received audio/video bitrate, packet loss rate, and network time delay (ms).

    7. New video encoder configuration

    To support video rotation scenarios and improve the quality of the custom video source, v2.3.2 deprecates the setVideoProfile method and replaces it with the setVideoEncoderConfiguration method to set the video encoder configurations. The VideoEncoderConfiguration class provides a set of configurable video parameters, including the dimension, frame rate, bitrate, and orientation. You can still use the setVideoProfile method, but Agora recommends using the setVideoEncoderConfiguration method to set the video profile.

    8. Virtual sound card

    v2.3.2 adds the deviceName parameter in the enableLoopbackRecording method, allowing you to use a virtual sound card for audio recording:

    • To use the current sound card, set deviceName as NULL.
    • To use a virtual card, set deviceName as the name of the virtual card.

    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.

    Agora plans 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.
    2. New network connection policy

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

    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 Agora does 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 interactive live streaming. Application developers can use this feedback for future product improvement. Agora strongly recommends integrating this method in your application.

    4. Improves the audio device usability

    v2.3.2 optimizes the audio device selection to fix the no audio issue when a user switches the audio device during a call or interactive live streaming.

    5. 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.
    • Optimizes the API calling threads.
    • Checks the headset and Bluetooth device connection.
    • Reduces the audio delay.
    • Optimizes the screen-sharing function.

    Issues fixed

    The following issues are fixed in v2.3.2:

    SDK
    • Flashes when detecting a device.
    Audio
    • A user joins the interactive live streaming with a Bluetooth headset. The audio is not played through the Bluetooth headset when the user leaves the channel and opens another application.
    • Crashes when calling the startAudioMixing method to play music files.
    • A previously disabled microphone becomes enabled when the device connects to a headset.
    • 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 application switches back from the background.
    • Crashes in the audio module.
    Video
    • The users on the Web client cannot see the video sent from the Native client due to codec bugs.
    • Hardware encoder issues when using an external video source on x86 devices.
    • 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.
    • Occasional long intervals between joining a channel and seeing the first remote video frame.
    • The remote user's video is mirrored when sharing part of the desktop and when the application calls the setVideoProfile method to specify the video resolution.
    • Blurry video when sharing a high-resolution screen.
    • The cursor on the remote side is not in the same position as the local side when sharing the desktop.

    API changes

    To improve the user experience, Agora has made the following changes to the APIs:

    Added
    Deprecated

    v2.2.2

    v2.2.2 is released on June 21, 2018.

    Issues fixed

    • Fixed occasional online statistics crashes.
    • Fixed the issue of failing to report the uid and volume of the speaker in a channel.
    • Fixed the issue of occasional video freeze after a view size change.

    v2.2.1

    v2.2.0 is released on May 30, 2018 and improves the internal code implementation.

    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 to enable 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

    Agora provides a proxy package for enterprise users with corporate firewalls to deploy before accessing the services of Agora.

    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 RTMP live streaming as a watermark. Adds the addVideoWatermark and clearVideoWatermarks methods to add and delete watermarks in a local live streaming. Adds the watermark parameter in the LiveTranscoding interface to add watermarks in RTMP 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 need for real-time network quality detection in the channel, the onNetworkQuality callback improves its data accuracy.

    3. Last mile network quality detection before joining a channel

    To test if the network condition can support audio or video calls before joining a channel, the onLastmileQuality callback changes its detection base from a fixed bitrate to the bitrate set in videoProfile to improve data accuracy. When the network condition is unknown, the SDK still triggers this callback once every 2 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_BROADCASTING channel.
    • Occasional audio issues 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 profile. 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 a normal COMMUNICATION or LIVE_BROADCASTING profile.

    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 video quality of the interactive live streaming will be better than the video quality of the call in the same resolutions, resulting in the interactive live streaming using more bandwidth.

    Issues fixed

    • The co-host is not seen by his/her counterpart after leaving and rejoining the channel.
    • The video resolution of the shared screen is worse in the COMMUNICATION profile than in the LIVE_BROADCASTING profile.

    v2.1.1

    v2.1.1 is released on March 16, 2018.

    Agora has identified a critical bug 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 the interactive live streaming scenario, the host can enhance the local audio effects from the built-in microphone with the setLocalVoiceEqualization and setLocalVoiceReverb methods to implement the expected 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. See:

    4. 17-way video

    Adds the support of 17-way video in the interactive live streaming scenario

    5. Injecting an external video stream

    Adds the function of injecting an external video stream to an ongoing interactive streaming. See Inject Online Media Stream.

    6. Screen sharing for Interactive Streaming
    • Before v2.1.0: The Agora SDK only supports the screen sharing function in a video call scenario.
    • From v2.1.0: The Agora SDK adds the screen-sharing function in interactive streaming.
    7. Loopback recording

    Adds the enableLoopbackRecording method to collect all local sounds.

    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, host-in, and stream-pushing).
    Billing Optimization Small video resolutions are charged according to the voice-only mode. For example, 16 × 16.

    Issues fixed

    • Occasional issues of the camera unable to capture the video source.
    • Occasional video freeze issues.
    • Occasional crashes.

    v2.0

    v2.0 is released on November 21, 2017.

    Compatibility changes

    Developers,

    Due to the upgrade of Agora products, Windows SDK 2.0 no longer supports the Agora Recording Server version 1.8.2 and before, or relevant APIs.

    This may affect:

    • Users of both the Windows SDK and Agora Recording Server v1.8.2 or before.
    • The following API methods are no longer supported: startRecordingService, stopRecordingService, and refreshRecordingServiceStatus.

    Two solutions are available:

    1. Migrate from the Agora Recording Server v1.8.2 or before to the Agora Recording SDK v1.12 or later. The Agora Recording SDK does not require recording on the client side and does not affect subsequent upgrades of the Windows SDK (recommended). For how to use the Agora Recording SDK, refer to:
    1. If you want to continue using the Agora Recording Server, you can use your current Windows SDK version (v1.14 and before). Contact Technical Support for any questions.

    New features

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

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

      Name Description
      setExternalAudioSource Sets the external audio source parameters, including the sample rate and channel number.
      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 the function, if required.

    • Supports Windows (x64).

    • Adds API methods such as setting the volume, mute states, and system volume settings.

      Name Description
      setPlaybackDeviceVolume Sets the volume of the playback device.
      getPlaybackDeviceVolume Gets the volume of the playback device.
      setRecordingDeviceVolume Sets the volume of the microphone.
      getRecordingDeviceVolume Gets the volume of the microphone.
      setPlaybackDeviceMute Mutes the playback device.
      getPlaybackDeviceMute Gets the mute status of the playback device.
      setRecordingDeviceMute Mutes the microphone.
      getRecordingDeviceMute Gets the mute status of the microphone.
      onAudioDeviceVolumeChanged Notifies the application when the volume of the playback device, recording device, or application changes.

    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 Interactive Streaming: Adds the setInEarMonitoringVolume method to adjust the volume of the in-ear monitor.

    Improvements

    • Optimizes the audio at high bitrates.
    • Live Interactive Streaming: 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 or disabled the video of a specific user, the network still sent the streams.
      • Starting from v1.14: If you mute the audio or disable the video 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 when the network was in poor conditions.
      • Starting from v1.14: Accurate control over the bitrate prevents huge fluctuations avoiding network congestion and shortening the transmission latency.

    Issues fixed:

    • Unable to hear any audio on certain Windows systems.
    • Camera-related issues on certain Windows systems.

    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 on a user role switch between the host and audience in the interactive live streaming.
    • Supports the push-stream failure callback on the server side.

    Improvements:

    • Screen Sharing: Enhances the video definition and fluency.
    • Screen Sharing: Supports updating the captured region dynamically.
    • The video profile is controllable by the software codec.

    Issues Fixed:

    Occasional crashes.

    v1.12

    v1.12 is released on July 25, 2017.

    New features:

    • Adds the injectStream method to inject an RTMP stream into the current channel in the LIVE_BROADCASTING profile.
    • 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.
    • Adds a set of APIs to manage the audio effect.
    • Adds the ActiveSpeaker method to report on the active speaker in the current channel.
    • Removes the setScreenCaptureWindow method, and updated the startScreenCapture method to share the whole screen and specify the window or region in the COMMUNICATION profile.
    • Adds displaying the mouse function when the screen-sharing function is enabled in the COMMUNICATION profile.
    • Web: Adds and updates a series of APIs to enable interoperability between the web browsers and native clients for the COMMUNICATION and LIVE_BROADCASTING profiles. See Release Notes.

    Recording: Adds APIs for real-time video mixing and web recording. See Release Notes for the Recording SDK.

    Improvements:

    Android/iOS/macOS/Windows: In the COMMUNICATION profile, an improvement for the 320 × 180 resolution profile:

    • Keeps the video smooth under poor network and equipment conditions.
    • Enhances the image quality to be better than 180p under good network and equipment conditions.

    Issues fixed:

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