Release notes

If your target platform is Android 12 or higher, add the android.permission.BLUETOOTH_CONNECT permission to the AndroidManifest.xml file of the Android project to enable the Bluetooth function of the Android system.

Known issues

The list of known issues page is continuously updated as the systems evolve. Agora suggests you regularly upgrade to the latest version of the SDK, which includes new features, bug fixes and improvements.

v4.6.3

Released on February 12, 2026.

Issues fixed

This release fixed the following issues:

• The app occasionally crashed in audio interaction scenarios.

v4.6.2

Released on January 19, 2026.

New features

Included in this release:

• New permission granted callback on Android

  The onPermissionGranted callback helps confirm permission status. You can use this callback to determine whether the user granted the necessary permissions.

Improvements

This release includes the following enhancements:

• Seamless switching for sound effect files

  Adds support for seamless switching of sound effect files. For the same sound effect file, if you call preloadEffect followed by playEffect, the SDK does not close the file after playback completes or when stopEffect is called. When you call playEffect again, the SDK reuses the loaded file to enable loop playback and seamless switching. This feature also works in multi-channel scenarios.

• Improved accuracy of network quality evaluation

  Improves the accuracy of network quality evaluation in the onNetworkQuality callback, making the reported data better reflect the user's perceived experience.

• Support for 24kHz sampling rate for audio playback

  Adds support for audio data with a sample rate of 24000 Hz in onPlaybackAudioFrame. When calling setPlaybackAudioFrameParameters to set the playback audio format, you can set sampleRate to 24000.

• Additional improvements

  • Adds error codes ERR_PCMSEND_FORMAT (200) and ERR_PCMSEND_BUFFEROVERFLOW (201) to report PCM data transmission errors.
  • The Media Recorder module now supports recording audio from Media Player and Audio Mixing.

Compatibility changes

This release introduces the following compatibility changes:

• Audio Spectrum removed from Lite and Voice packages

  To further reduce SDK package size, this version removes the Audio Spectrum feature from the Lite and Voice SDK packages. If you need the Audio Spectrum feature, please integrate the Full package.

• Decoder plugins built into the SDK

  The relevant decoder plugins are now built into the SDK to ensure overall decoding compatibility.

Issues fixed

This release fixed the following issues:

• The bitrate setting in the startLocalTranscoder API did not take effect.
• On some emulators (such as LDPlayer 9), electrical noise was occasionally heard on the receiver side during audio engagements.
• During audio engagements, after calling playEffect locally, if a remote user switched to broadcaster and started speaking, electrical noise was occasionally heard locally.
• When a user joined a channel as a broadcaster with the audio scenario set to AUDIO_SCENARIO_CHATROOM and did not publish local audio, then played a music file using startAudioMixing, and switched the audio scenario to AUDIO_SCENARIO_GAMESTREAMING, noise was occasionally heard.
• The app occasionally became unresponsive (ANR) during audio engagements.
• Occasional crashes occurred during audio engagements.

v4.6.1

Released on November 26, 2025.

Issues fixed

This version fixes the following issues:

• The app occasionally crashed during audio communication when connected to a network via VPN.
• The app occasionally crashed during audio communication.
• In multi-channel scenarios, the app occasionally crashed during audio communication with other devices.

v4.6.0

Released on August 26, 2025.

Compatibility changes

This version includes SDK behavior changes, API deprecations, and deletions. To ensure your app functions correctly, update your code after upgrading to this version.

For details on deprecated and deleted APIs in each version, see the API Sunset Notice.

• Deprecation of direct CDN streaming APIs

  Deprecates the APIs related to direct CDN streaming, which will be removed in a future release. Agora recommends using Media Push instead.

  • setDirectCdnStreamingAudioConfiguration
  • setDirectCdnStreamingVideoConfiguration
  • startDirectCdnStreaming
  • stopDirectCdnStreaming
  • updateDirectCdnStreamingMediaOptions
  • DirectCdnStreamingMediaOptions
  • DirectCdnStreamingStats
  • DirectCdnStreamingState
  • DirectCdnStreamingReason

• Deprecation of virtual metronome APIs

  Deprecates the APIs for the virtual metronome feature, which will be removed in a future release.

  • startRhythmPlayer
  • configRhythmPlayer
  • onRhythmPlayerStateChanged

• Deletion of redundant APIs

  Removed the following redundant APIs and parameters:

  • setLocalPublishFallbackOption
  • onLocalPublishFallbackToAudioOnly
  • onDownlinkNetworkInfoUpdated
  • onWlAccStats
  • WlAccStats
  • onWlAccMessage
  • enableWirelessAccelerate

• Changes to int UID and string UID mapping

  • Before v4.6.0: If you used registerLocalUserAccount to register a string UID (for example, "aa") and obtain an int UID (for example, 123), joining a channel with this int UID automatically mapped it to the original string UID ("aa").
  • From v4.6.0: The SDK no longer automatically maps an int UID to the original string UID. If you need to join the channel with the original string UID, call the join method directly with the string UID. After upgrading, review and update your app logic to ensure users join the channel with the expected identity.

New features

• Multipath network transmission

  Introduced multipath transmission for devices with multiple network interfaces (such as 5G, Wi-Fi, and LAN). This feature improves stability in challenging network environments, including in-vehicle systems, IoT, trains, and highways. Enable it by setting enableMultipath in ChannelMediaOptions to true.

  • Dynamic mode: Dynamically selects the optimal path based on network conditions. Suitable for scenarios sensitive to data consumption but requiring high experience quality, such as meetings and educational settings. You can optionally set preferMultipathType to prioritize a path type; if not set, all paths have the same default weight.
  • Duplicate mode: Sends data simultaneously over all available paths (such as LAN, Wi-Fi, and cellular) to eliminate the impact of poor network conditions. Suitable for scenarios not sensitive to data consumption but with extreme stability requirements, such as outdoor broadcasting and parallel control. This mode incurs additional costs.

  Configure uplink and downlink modes separately with uplinkMultipathMode and downlinkMultipathMode. Monitor performance with the onMultipathStats callback, which reports per-path statistics including data consumption.

• Asynchronous engine destruction

  Added the destroy [2/2] method with an option for asynchronous destruction, triggering the onEngineReleased callback.

• Token renewal result callback

  Added the onRenewTokenResult callback and RENEW_TOKEN_ERROR_CODE for handling the result of renewToken.

• Other new features

  • Added setPlaybackAudioFrameBeforeMixingParameters to configure the format of raw audio frames returned in onPlaybackAudioFrameBeforeMixing, including sample rate, number of channels, and the number of samples per callback.
  • Added preloadEffectEx [1/2] for preloading audio effects in a specific channel. Supports both local and online files, enabling faster playback later and suitable for multi-channel scenarios.
  • Added playEffectEx [1/2] for playing audio effects in a specific channel with advanced controls such as loop count, pitch, spatial position, volume, whether to publish to the channel, and starting playback position.

Improvements

• Added support for G.711 and G.722 audio codecs when interoperating with the Web SDK to improve cross-platform audio compatibility and clarity.
• Optimized the plugin loading mechanism to automatically load the SDK's dynamic library plugins for Android apps developed with C++.

Issues fixed

This version fixes the following issues:

• Online audio effect playback restarted from the beginning when seek was called to change playback position.
• Occasional echoes in media volume mode when a broadcaster published a microphone audio stream while playing an audio effect with playEffect [2/2] and music with startAudioMixing [2/2].
• Missing media metadata observer callback when registerMediaMetadataObserver was called after setExternalVideoSource (Android, iOS).
• Occasional crashes (Android, iOS).
• Incorrect relay state (RELAY_STATE_FAILURE) and error (RELAY_ERROR_SERVER_ERROR_RESPONSE) reported after a specific join/relay sequence using joinChannelEx.
• Occasional audio noise when using Bluetooth or wired headphones after setting AUDIO_SCENARIO_CHATROOM (Android).

v4.5.2

v4.5.2 was released on April 22, 2025.

Issues fixed

This release fixes the following issues:

• While playing a multi-track media file, noise was heard when adjusting the audio pitch using setAudioPitch.
• When the host called createCustomAudioTrack with trackType set to AUDIO_TRACK_DIRECT, pushed custom audio frames using pushExternalAudioFrame, and then called playEffect [2/2] to play audio effects, audience members heard noise.
• Apps using the SDK occasionally experienced UI lag caused by main thread blocking during audio and video interactions.
• When playing an MP4 file with EAC3 audio encoding using startAudioMixing, sometimes no sound was heard.
• Memory leaks occurred after leaving the channel and stopping video rendering.
• After calling setCameraFocusPositionInPreview to manually set the focus position, the focus position was inaccurate when the camera captured a zoomed-in image.
• When calling setExternalMediaProjection to configure an external MediaProjection instance, the transmitted video stream resolution (width/height) did not adjust dynamically when the screen orientation changed between landscape and portrait modes.
• Calling openWithMediaSource and setting isLiveSource to true to play a video stream caused playback failure.
• When attempting to open a non-existent local media file, the onPlayerSourceStateChanged callback did not report PLAYER_STATE_FAILED as expected.
• When the sender transmitted multi-channel encoded audio, the receiver occasionally experienced noise.
• When opening two different media resources consecutively using the media player, the second call unexpectedly triggered the onPlayerInfoUpdated callback with information from the first media resource.
• After enabling user volume indication with enableAudioVolumeIndication, the onAudioVolumeIndication callback returned a local user volume of 0 for both local and remote users.
• The app occasionally froze during audio and video communication.
• Calling setExtensionProperty with the key "makeup_options" to apply makeup effects failed.
• In low-light environments, the preview image appeared darker on certain device models during audio and video communication.
• On 21
  ultra-wide displays, setting a high resolution (such as 3840×2160) during screen sharing caused the shared image to appear cropped in both the local preview and on the receiver’s screen.
• When the app called enableVideoImageSource to enable the video image source feature, streaming succeeded, but occasionally onVideoPublishStateChanged did not return the expected results.
• In multi-channel scenarios, if the app called setupRemoteVideoEx before successfully calling joinChannelEx, the first frame of the remote video occasionally experienced significant delay.
• After a failed attempt to join a channel, trying again without first calling leaveChannel [1/2] occasionally caused a crash.

v4.5.1

v4.5.1 was released on March 6, 2025.

New features

AI conversation scenario

This version introduces the AUDIO_SCENARIO_AI_CLIENT audio scenario option, specifically designed for interacting with conversational AI agents powered by the Conversational AI Engine.

This scenario optimizes audio transmission algorithms based on the characteristics of AI-generated voices, ensuring stable voice data transmission even in weak network conditions with up to 80% packet loss. The optimization enhances conversation continuity and reliability across various network environments.

Issues fixed

This release fixes the following issues:

• Apps integrating the Agora SDK with targetSdkVersion set to 34 crashed when attempting to enable screen sharing for the first time on Android 14.
• After using the pause method to pause playback, calling seek to move to a specific position, and then calling play, the Media Player resumed from the paused position instead of the newly specified position.
• When using the Media Player, the file path returned by getPlaySrc [1/2] did not update after calling switchSrc to switch to a new media resource.
• When using Bluetooth headphones on certain device models for audio and video interactions, adjusting the phone volume occasionally changed the media volume instead of the Bluetooth volume.
• During audio and video interactions, the local user sometimes experienced a black screen when viewing remote video streams.
• On specific device models, calling setCameraExposureFactor to set the camera's exposure coefficient at a particular angle sometimes caused the video screen to darken when the device was moved to another angle.
• When playing a CDN live stream, the video occasionally froze for an extended period after recovering from an interruption.
• In interactive live streaming, after joining a channel as an audience member using a string user ID, the audio and video occasionally became unsynchronized.
• Plugins sometimes malfunctioned when using AI noise suppression and AI echo cancellation plugins simultaneously.

v4.5.0

v4.5.0 was released on November 27, 2024.

Compatibility changes

This version includes optimizations to some features, including changes to SDK behavior and API renaming and deletion. To ensure normal operation of the project, update the code in the app after upgrading to this release.

1. 16 KB memory page size

   Starting from Android 15, the system adds support for 16 KB memory page size, as detailed in Support 16 KB page sizes. To ensure the stability and performance of the app, starting from this version, the SDK supports 16 KB memory page size, ensuring seamless operation on devices with both 4 KB and 16 KB memory page sizes, enhancing compatibility and preventing crashes.

New features

1. Local audio mixing

   This version introduces the local audio mixing feature. You can call the startLocalAudioMixer method to mix the audio streams from the local microphone, media player, sound card, and remote audio streams into a single audio stream, which can then be published to the channel. When you no longer need audio mixing, you can call the stopLocalAudioMixer method to stop local audio mixing. During the mixing process, you can call the updateLocalAudioMixerConfiguration method to update the configuration of the audio streams being mixed.

   Example use cases for this feature include:

   • When using the local video mixing feature, the associated audio streams of the mixed video streams can be simultaneously captured and published.
   • In live streaming use-cases, users can receive audio streams within the channel, mix multiple audio streams locally, and then forward the mixed audio stream to other channels.
   • In educational use-cases, teachers can mix the audio from interactions with students locally and then forward the mixed audio stream to other channels.

2. External MediaProjection

   This version introduces the setExternalMediaProjection method, which allows you to set an external MediaProjection and replace the MediaProjection applied by the SDK.

   If you have the capability to apply for MediaProjection on your own, you can use this feature to achieve more flexible screen capture.

Improvements

1. Custom audio capture improvements

   This version adds the enableAudioProcessingmember parameter to AudioTrackConfig, which is used to control whether to enable 3A audio processing for custom audio capture tracks of the AUDIO_TRACK_DIRECT type. The default value of this parameter is false, meaning that audio processing is not enabled. Users can enable it as needed, enhancing the flexibility of custom audio processing.

2. Other improvements

   • This version optimizes the logic for calling queryDeviceScore to obtain device score levels, improving the accuracy of the score results.
   • When calling setPlaybackSpeed to set the playback speed of an audio file, the minimum supported speed is 0.3x.

Bug fixes

This version fixes the following issues:

• Occasional noise and stuttering when playing music resources from the music content center.
• During audio and video interaction, after being interrupted by a system call, the user volume reported by the onAudioVolumeIndication callback was incorrect.
• Calling startAudioMixing [1/2] and then immediately calling pauseAudioMixing to pause the music file playback does not take effect.
• Occasional crashes during audio and video interaction.

v4.4.1

v4.4.1 was released on August 8, 2024.

Issues fixed

This release fixes the issue where io.agora.rtc:full-rtc-basic:4.4.0 and io.agora.rtc:voice-rtc-basic:4.4.0 were not working properly on Maven Central due to an upload error.

v4.4.0

v4.4.0 was released on August 5, 2024.

Compatibility changes

This version includes optimizations to some features, including changes to the SDK behavior and API renaming and deletion. To ensure normal operation of the project, update the code in the app after upgrading to this release.

1. To distinguish context information in different extension callbacks, this version removes the original extension callbacks and adds new corresponding callbacks that contain context information (see table below). You can identify the extension name, the user ID, and the service provider name through ExtensionContext in each callback.

   Original callback	New callback
   onEvent	onEventWithContext
   onStarted	onStartedWithContext
   onStopped	onStoppedWithContext
   onError	onErrorWithContext

2. This version removes the buffer, uid, and timeStampMs parameters of the onMetadataReceived callback. You can get metadata-related information, including timeStampMs (timestamp of the sent data), uid (user ID), and channelId (channel name) through the newly-added metadata parameter.

New features

1. Voice AI tuner

   This version introduces the voice AI tuner feature, which can enhance the sound quality and tone, similar to a physical sound card. You can enable the voice AI tuner feature by calling the enableVoiceAITuner method and passing in the sound effect types supported in the VOICE_AI_TUNER_TYPE enum to achieve effects like deep voice, cute voice, husky singing voice, and so on.

Improvements

1. Adaptive hardware decoding support

   This release introduces adaptive hardware decoding support, enhancing rendering smoothness on low-end devices and effectively reducing system load.

2. Other improvements

   This version also includes the following improvements:

   • Deprecates the option parameter of type int in setRemoteSubscribeFallbackOption [1/2], and adds an overloaded function setRemoteSubscribeFallbackOption [2/2] with the option parameter of type StreamFallbackOptions.
   • Optimizes the transmission strategy: Calling enableInstantMediaRendering no longer impacts the security of the transmission link.
   • Deprecates redundant enumerations CLIENT_ROLE_CHANGE_FAILED_REQUEST_TIME_OUT and CLIENT_ROLE_CHANGE_FAILED_CONNECTION_FAILED.

Issues fixed

This release fixes the following issue:

• Audio playback failed when pushing external audio data using pushExternalAudioFrame and the sample rate was not set as a recommended value, such as 22050 Hz and 11025 Hz.

v4.3.2

v4.3.2 was released on June 4, 2024.

Improvements

1. This release enhances the usability of the setRemoteSubscribeFallbackOption method by removing the timing requirements for invocation. It can now be called both before and after joining the channel to dynamically switch audio and video stream fallback options in weak network conditions.

2. The Agora media player now fully supports playing music files located in the /assets/ directory or from URI starting with content://.

Issues fixed

This version fixed the following issues:

• Local audio capture failed after joining a channel while answering a system phone call and hanging up, preventing remote users from hearing any sound.
• During the interaction process on certain devices (for example, Redmi Note8), after answering and hanging up a system call, local media files were played without sound and no sound was heard from the remote end (Android).
• The app occasionally crashed when remote users left the channel.

v4.3.1

v4.3.1 was released on April 29, 2024.

Compatibility changes

To ensure parameter naming consistency, this version renames channelName to channelId and optionalUid to uid in joinChannel [1/2]. Update your app's code after upgrading to this version to ensure normal project operations.

New features

1. Data stream encryption

   This version adds datastreamEncryptionEnabled to EncryptionConfig for enabling data stream encryption. You can set this when you activate encryption with enableEncryption. If there are issues causing failures in data stream encryption or decryption, these can be identified by the newly added ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE and ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE enumerations.

2. Other features

   • A new method enableEncryptionEx is added for enabling media stream or data stream encryption in multi-channel use-cases.
   • A new method setAudioMixingPlaybackSpeed is introduced for setting the playback speed of audio files.
   • A new method getCallIdEx is introduced for retrieving call IDs in multi-channel use-cases.

3. Beta features

   • Speech driven avatar is released in beta. See beta documentation for details.

Improvements

1. CPU consumption reduction of in-ear monitoring

   This release adds an enumerator EAR_MONITORING_FILTER_REUSE_POST_PROCESSING_FILTER. For complex audio processing use-cases, you can specify this option to reuse the audio filter after sender-side processing in in-ear monitoring, thereby reducing CPU consumption. Note that this option may increase the latency of in-ear monitoring, which is suitable for latency-tolerant use-cases requiring low CPU consumption.

2. Other improvements

   This version also includes the following improvements:

   • Enhanced performance and stability of the local compositing feature, reducing its CPU usage.
   • New chorus effect ROOM_ACOUSTICS_CHORUS is added to enhance the spatial presence of vocals in chorus use-cases.
   • In RemoteAudioStats, a new e2eDelay field is added to report the delay from when the audio is captured on the sending end to when the audio is played on the receiving end.

Issues fixed

This version fixed the following issues:

• After joining a channel and calling disableAudio, audio playback did not immediately stop.
• Broadcasters using certain models of devices under speaker mode experienced occasional local audio capture failures when switching the app process to the background and then back to the foreground, causing remote users to not hear the broadcaster's audio.

API changes

Added

• registerFaceInfoObserver
• IFaceInfoObserver
• onFaceInfo
• MediaSourceType adds SPEECH_DRIVEN_VIDEO_SOURCE
• EncryptionConfig adds datastreamEncryptionEnabled
• ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE
• ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE
• RemoteAudioStats adds e2eDelay
• ERR_DATASTREAM_DECRYPTION_FAILED
• ROOM_ACOUSTICS_CHORUS is added, enhancing the spatial presence of vocals in chorus use-cases.
• getCallIdEx
• enableEncryptionEx
• setAudioMixingPlaybackSpeed
• EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS

v4.3.0

v4.3.0 was released on February 22, 2024.

Compatibility changes

This release has optimized the implementation of some functions, which involved renaming or deletion of some APIs. To ensure normal operation of the project, update the code in the app after upgrading to this release.

1. Renaming parameters in callbacks

   In order to make the parameters in some callbacks and the naming of enumerations in enumeration classes easier to understand, the following modifications have been made in this release. Modify the parameter settings in the callbacks after upgrading to this release.

   Callback	Original parameter name	Existing parameter name
   onLocalAudioStateChanged	error	reason
   onLocalVideoStateChanged	error	reason
   onDirectCdnStreamingStateChanged	error	reason
   onPlayerStateChanged	error	reason
   onRtmpStreamingStateChanged	errCode	reason

   Original enumeration class	Current enumeration class
   DirectCdnStreamingReason	DirectCdnStreamingReason
   MediaPlayerReason	MediaPlayerReason

   Note: For specific renaming of enumerations, refer to API changes.

2. Channel media relay

   To improve interface usability, this release removes some methods and callbacks for channel media relay. Use the alternative options listed in the table below:

   Deleted methods and callbacks	Alternative methods and callbacks
   startChannelMediaRelay updateChannelMediaRelay	startOrUpdateChannelMediaRelay
   startChannelMediaRelayEx updateChannelMediaRelayEx	startOrUpdateChannelMediaRelayEx
   onChannelMediaRelayEvent	onChannelMediaRelayStateChanged

3. Audio route

   Since this release, RouteBluetooth is renamed to AUDIO_ROUTE_BLUETOOTH_DEVICE_HFP, representing a Bluetooth device using the HFP protocol. The AUDIO_ROUTE_BLUETOOTH_DEVICE_A2DP(10) is added to represent a Bluetooth device using the A2DP protocol.

4. Log encryption behavior changes

   For security and performance reasons, as of this release, the SDK encrypts logs and no longer supports printing plaintext logs via the console.

   Refer to the following solutions for different needs:

   • If you need to know the API call status, please check the API logs and print the SDK callback logs yourself.
   • For any other special requirements, please contact technical support and provide the corresponding encrypted logs.

5. Removing IAgoraEventHandler interface

   This release deletes the IAgoraEventHandler interface class. All callback events that were previously managed under this class are now processed through the IRtcEngineEventHandler interface class.

New features

1. Query device score

   This release adds the queryDeviceScore method to query the device's score level to ensure that the user-set parameters do not exceed the device's capabilities. For example, in HD or UHD video use-cases, you can first call this method to query the device's score. If the returned score is low (for example, below 60), you need to lower the video resolution to avoid affecting the video experience. The minimum device score required for different business use-cases is varied. For specific score recommendations, please contact technical support.

2. Select different audio tracks for local playback and streaming

   This release introduces the selectMultiAudioTrack method that allows you to select different audio tracks for local playback and streaming to remote users. For example, in use-cases like online karaoke, the host can choose to play the original sound locally and publish the accompaniment in the channel. Before using this function, you need to open the media file through the openWithMediaSource method and enable this function by setting the enableMultiAudioTrack parameter in MediaPlayerSource.

3. Audio playback device test

   This release introduces the startPlaybackDeviceTest method to allow you to test whether your local audio device for playback works properly. You can specify the audio file to be played through the testAudioFilePath parameter and see if your audio device works properly. After the test is completed, you need to call the newly added stopPlaybackDeviceTest method to stop the test.

4. Others

   This release has passed the test verification of the following APIs and can be applied to the entire series of RTC 4.x SDK.

   • onRemoteSubscribeFallbackToAudioOnly: Occurs when the subscribed video stream falls back to audio-only stream due to weak network conditions or switches back to the video stream after the network conditions improve.
   • setPlayerOption and setPlayerOptionString: Sets media player options for providing technical previews or special customization features.
   • enableCustomAudioLocalPlayback: Sets whether to enable the local playback of external audio source.

Improvements

1. SDK task processing scheduling optimization

   This release optimizes the scheduling mechanism for internal tasks within the SDK, with improvements in the following aspects:

   • The speed of video rendering and audio playback for both remote and local first frames improves by 10% to 20%.
   • The API call duration and response time are reduced by 5% to 50%.
   • The SDK's parallel processing capability significantly improves, delivering higher video quality (720P, 24 FPS) even on lower-end devices. Additionally, image processing remains more stable in use-cases involving high resolutions and frame rates.
   • The stability of the SDK is further enhanced, leading to a noticeable decrease in the crash rate across various specific use-cases.

2. In-ear monitoring volume boost

   This release provides users with more flexible in-ear monitoring audio adjustment options, supporting the ability to set the in-ear monitoring volume to four times the original volume by calling setInEarMonitoringVolume.

3. Spatial audio effects usability improvement

   • This release optimizes the design of the setZones method, supporting the ability to set the zones parameter to NULL, indicating the clearing of all echo cancellation zones.
   • As of this release, it is no longer necessary to unsubscribe from the audio streams of all remote users within the channel before calling the ILocalSpatialAudioEngine method.

4. Other improvements

   This release also includes the following improvements:

   • Adds allowCaptureCurrentApp member in AudioCaptureParameters, which is used to set whether to capture audio from the current app during screen sharing. The default value of this member is true, which means it collects the audio from the current app by default. In certain use-cases, the shared screen audio captured by the app may cause echo on the remote side due to signal delay and other reasons. Agora suggests setting this member as false to eliminate the remote echo introduced during the screen sharing process.
   • This release optimizes the SDK's domain name resolution strategy, improving the stability of calling setLocalAccessPoint to resolve domain names in complex network environments.
   • This release adds the earMonitorDelay and aecEstimatedDelay members in LocalAudioStats to report ear monitor delay and acoustic echo cancellation (AEC) delay, respectively.
   • The onPlayerCacheStats callback is added to report the statistics of the media file being cached. This callback is triggered once per second after file caching is started.
   • The onPlayerPlaybackStats callback is added to report the statistics of the media file being played. This callback is triggered once per second after the media file starts playing. You can obtain information like the audio and video bitrate of the media file through PlayerPlaybackStats.

Issues fixed

This release fixed the following issue:

• In an online meeting use-case, occasional audio freezes occurred when the local user was listening to remote users.

API changes

Added

• onTranscodedStreamLayoutInfo
• VideoLayout
• The subviewUid and uid members in VideoCanvas
• The codecType member in VideoEncoderConfiguration
• The allowCaptureCurrentApp member in AudioCaptureParameters
• enableCustomAudioLocalPlayback
• selectMultiAudioTrack
• onPlayerCacheStats
• onPlayerPlaybackStats
• PlayerPlaybackStats
• startPlaybackDeviceTest
• stopPlaybackDeviceTest
• The earMonitorDelay and aecEstimatedDelay members in LocalAudioStats
• queryDeviceScore
• The CUSTOM_VIDEO_SOURCE enumeration in MediaSourceType
• setBeautyEffectOptions
• setLowlightEnhanceOptions
• setVideoDenoiserOptions
• setColorEnhanceOptions
• enableVirtualBackground
• The AUDIO_ROUTE_BLUETOOTH_DEVICE_A2DP enumeration

Modified

• ROUTE_BLUETOOTH is renamed as AUDIO_ROUTE_BLUETOOTH_DEVICE_HFP
• All ERROR fields in the following enumerations are changed to REASON:
• LOCAL_AUDIO_STREAM_ERROR_OK
• LOCAL_AUDIO_STREAM_ERROR_FAILURE
• LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION
• LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY
• LOCAL_AUDIO_STREAM_ERROR_CAPTURE_FAILURE
• LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE
• LOCAL_VIDEO_STREAM_ERROR_OK
• LOCAL_VIDEO_STREAM_ERROR_FAILURE
• LOCAL_VIDEO_STREAM_ERROR_DEVICE_NO_PERMISSION
• LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY
• LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE
• LOCAL_VIDEO_STREAM_ERROR_CODEC_NOT_SUPPORT
• LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND
• PLAYER_ERROR_NONE
• PLAYER_ERROR_INVALID_ARGUMENTS
• PLAYER_ERROR_INTERNAL
• PLAYER_ERROR_NO_RESOURCE
• PLAYER_ERROR_INVALID_MEDIA_SOURCE
• PLAYER_ERROR_UNKNOWN_STREAM_TYPE
• PLAYER_ERROR_OBJ_NOT_INITIALIZED
• PLAYER_ERROR_CODEC_NOT_SUPPORTED
• PLAYER_ERROR_VIDEO_RENDER_FAILED
• PLAYER_ERROR_INVALID_STATE
• PLAYER_ERROR_URL_NOT_FOUND
• PLAYER_ERROR_INVALID_CONNECTION_STATE
• PLAYER_ERROR_SRC_BUFFER_UNDERFLOW
• PLAYER_ERROR_INTERRUPTED
• PLAYER_ERROR_NOT_SUPPORTED
• PLAYER_ERROR_TOKEN_EXPIRED
• PLAYER_ERROR_UNKNOWN
• RTMP_STREAM_PUBLISH_ERROR_OK
• RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT
• RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED
• RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT
• RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR
• RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR
• RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN
• RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT
• RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED
• RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND
• RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED
• RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER
• RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM
• RTMP_STREAM_PUBLISH_ERROR_NET_DOWN
• RTMP_STREAM_PUBLISH_ERROR_INVALID_PRIVILEGE
• RTMP_STREAM_UNPUBLISH_ERROR_OK

Deleted

• startChannelMediaRelay
• updateChannelMediaRelay
• startChannelMediaRelayEx
• updateChannelMediaRelayEx
• onChannelMediaRelayEvent

v4.2.6

v4.2.6 was released on November 17, 2023.

Issues fixed

This release fixed the following issues occurring when using Android 14:

• When integrating the SDK, setting the Android targetSdkVersion to 34 could cause screen sharing to be unavailable or even the app to crash.

v4.2.3

v4.2.3 was released on October 11, 2023.

Improvements

Other improvements

This release includes the following additional improvements:

• Optimizes the logic of handling invalid parameters. When you call the setPlaybackSpeed method to set the playback speed of audio files, if you pass an invalid parameter, the SDK returns the error code -2, which means that you need to reset the parameter.
• Optimizes the logic of Token parsing, in order to prevent an app from crash when an invalid token is passed in.

Issues fixed

This release fixed the following issues:

• Occasional failure of joining a channel when the local system time was not set correctly.
• When calling the playEffect [2/2] method to play two audio files using the same soundId, the first audio file was sometimes played repeatedly.
• When the host called the startAudioMixing [2/2] method to play music, sometimes the host couldn't hear the music while the remote users could hear it.
• Occasional crashes occurred on certain Android devices.
• In channels joined by calling joinChannelEx exclusively, calling setEnableSpeakerphone is unable to switch audio route from the speaker to the headphone.

v4.2.2

v4.2.2 was released on july 27, 2023.

New features

1. Wildcard token

   This release introduces wildcard tokens. Agora supports setting the channel name used for generating a token as a wildcard character. The token generated can be used to join any channel if you use the same user id. In use-cases involving multiple channels, such as switching between different channels, using a wildcard token can avoid repeated application of tokens every time users joining a new channel, which reduces the pressure on your token server. See Secure authentication with tokens.

2. Preloading channels

   This release adds preloadChannel[1/2] and preloadChannel[2/2] methods, which allows a user whose role is set as audience to preload channels before joining one. Calling the method can help shortening the time of joining a channel, thus reducing the time it takes for audience members to hear the host.

   When preloading more than one channels, Agora recommends that you use a wildcard token for preloading to avoid repeated application of tokens every time you joining a new channel, thus saving the time for switching between channels. See Secure authentication with tokens.

Improvements

1. Virtual Background Algorithm Upgrade

   This version has upgraded the portrait segmentation algorithm of the virtual background, which comprehensively improves the accuracy of portrait segmentation, the smoothness of the portrait edge with the virtual background, and the fit of the edge when the person moves. In addition, it optimizes the precision of the person's edge in use-cases such as meetings, offices, homes, and under backlight or weak light conditions.

2. Channel media relay

   The number of target channels for media relay has been increased to 6. When calling startOrUpdateChannelMediaRelay and startOrUpdateChannelMediaRelayEx, you can specify up to 6 target channels.

This release includes the following additional improvements:

1. To improve the switching experience between multiple audio routes, this release adds the setRouteInCommunicationMode method. This method can switch the audio route from a Bluetooth headphone to the earpiece, wired headphone or speaker in communication volume mode (MODE_IN_COMMUNICATION).

Issues fixed

This release fixed the following issues:

• Slow channel reconnection after the connection was interrupted due to network reasons.

API changes

Added

• preloadChannel[1/2]
• preloadChannel[2/2]
• updatePreloadChannelToken
• setRouteInCommunicationMode

v4.2.1

This version was released on June 21, 2023.

Improvements

This version improves the network transmission strategy, enhancing the smoothness of audio interactions.

Issues fixed

This version fixed the following issues:

• Inability to join channels caused by SDK's incompatibility with some older versions of AccessToken.
• After the sending end called setAINSMode to activate AI noise reduction, occasional echo was observed by the receiving end.
• Brief noise occurred while playing media files using the media player.

v4.2.0

v4.2.0 was released on May 24, 2023.

Compatibility changes

If you use the features mentioned in this section, ensure that you modify the implementation of the relevant features after upgrading the SDK.

1. Channel media options

• publishCustomAudioTrackEnableAec in ChannelMediaOptions is deleted. Use publishCustomAudioTrack instead.
• publishCustomAudioSourceId in ChannelMediaOptions is renamed to publishCustomAudioTrackId.

2. Miscellaneous

• onApiCallExecuted is deleted. Agora recommends getting the results of the API implementation through relevant channels and media callbacks.
• startChannelMediaRelay, updateChannelMediaRelay, startChannelMediaRelayEx, and updateChannelMediaRelayEx are deprecated. Use startOrUpdateChannelMediaRelay and startOrUpdateChannelMediaRelayEx instead.

New features

1. AI Noise Suppression

This release introduces public APIs for the AI Noise Suppression function. Once enabled, the SDK automatically detects and reduces background noises. Whether in bustling public venues or real-time competitive arenas that demand lightning-fast responsiveness, this function guarantees optimal audio clarity, providing users with an elevated audio experience. You can enable this function through the newly-introduced setAINSMode method and set the noise reduction mode as balance, aggressive, or low latency according to your use-case.

2. Cross-device synchronization

In real-time collaborative singing use-cases, network issues can cause inconsistencies in the downlinks of different client devices. To address this, this release introduces getNtpWallTimeInMs for obtaining the current Network Time Protocol (NTP) time. By using this method to synchronize lyrics and music across multiple client devices, users can achieve synchronized singing and lyrics progression, resulting in a better collaborative experience.

Improvements

1. Improved voice changer

This release introduces the setLocalVoiceFormant method that allows you to adjust the formant ratio to change the timbre of the voice. This method can be used together with the setLocalVoicePitch method to adjust the pitch and timbre of voice at the same time, enabling a wider range of voice transformation effects.

2. Improved compatibility with audio file types

As of v4.2.0, you can use the following methods to open files with a URI starting with content://:

• startAudioMixing [2/2]
• playEffect [3/3]
• open [2/2]
• openWithMediaSource

3. Channel media relay

This release introduces startOrUpdateChannelMediaRelay and startOrUpdateChannelMediaRelayEx, allowing for a simpler and smoother way to start and update media relay across channels. With these methods, developers can easily start the media relay across channels and update the target channels for media relay with a single method. Additionally, the internal interaction frequency has been optimized, effectively reducing latency in function calls.

4. Custom audio tracks

To better meet the needs of custom audio capture use-cases, this release adds createCustomAudioTrack and destroyCustomAudioTrack for creating and destroying custom audio tracks. Two types of audio tracks are also provided for users to choose from, further improving the flexibility of capturing external audio source:

• Mixable audio track: Supports mixing multiple external audio sources and publishing them to the same channel, suitable for multi-channel audio capture use-cases.
• Direct audio track: Only supports publishing one external audio source to a single channel, suitable for low-latency audio capture use-cases.

Issues fixed

This release fixed the following issues:

• Occasional crashes occurred on Android devices when users joined or left a channel.
• When the host frequently switched the user role between broadcaster and audience in a short period of time, the audience members could not hear the audio of the host.
• Occasional failure when enabling in-ear monitoring.
• Occasional echo.
• Abnormal client status caused by an exception in the onRemoteAudioStateChanged callback.

API changes

Added

• startOrUpdateChannelMediaRelay
• startOrUpdateChannelMediaRelayEx
• getNtpWallTimeInMs
• setAINSMode
• createAudioCustomTrack
• destroyAudioCustomTrack
• AudioTrackConfig
• AudioTrackType
• The mDomainLimit and mAutoRegisterAgoraExtensions members in RtcEngineConfig

Deprecated

• startChannelMediaRelay
• startChannelMediaRelayEx
• updateChannelMediaRelay
• updateChannelMediaRelayEx
• onChannelMediaRelayEvent

Deleted

• onApiCallExecuted
• publishCustomAudioTrackEnableAec in ChannelMediaOptions

v4.1.1

v4.1.1 was released on February 8, 2023.

New features

Instant audio frame rendering

This release adds the enableInstantMediaRendering method to enable instant rendering mode for audio and video frames, which can speed up the first video or audio frame rendering after the user joins the channel.

Issues fixed

This release fixed the following issues:

• Playing audio files with a sample rate of 48 kHz failed.
• In real-time chorus use-cases, remote users heard noises and echoes when an OPPO R11 device joined the channel in loudspeaker mode.
• When the playback of the local music finished, the onAudioMixingFinished callback was not properly triggered.
• At the moment when a user left a channel, a request for leaving was not sent to the server and the leaving behavior was incorrectly determined by the server as timed out.

API changes

Added

enableInstantMediaRendering

v4.1.0

v4.1.0 was released on December 15, 2022.

New features

1. Headphone equalization effect

This release adds the setHeadphoneEQParameters method, which is used to adjust the low- and high-frequency parameters of the headphone EQ. This mainly useful in spatial audio use-cases. If you cannot achieve the expected headphone EQ effect after calling setHeadphoneEQPreset, you can call setHeadphoneEQParameters to adjust the EQ.

2. MPUDP (MultiPath UDP) (Beta)

As of this release, the SDK supports MPUDP protocol, which enables you to connect and use multiple paths to maximize the use of channel resources based on the UDP protocol. You can use different physical NICs on both mobile and desktop and aggregate them to effectively combat network jitter and improve transmission quality.

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

3. Multi-channel management

This release adds a series of multi-channel related methods that you can call to manage audio stream in multi-channel use-cases.

• The muteLocalAudioStreamEx method is used to cancel or resume publishing a local audio stream.
• The muteAllRemoteAudioStreamsEx is used to cancel or resume the subscription of all remote users to audio stream.
• The startRtmpStreamWithoutTranscodingEx, startRtmpStreamWithTranscodingEx, updateRtmpTranscodingEx, and stopRtmpStreamEx methods are used to implement Media Push in multi-channel use-cases.
• The startChannelMediaRelayEx, updateChannelMediaRelayEx, pauseAllChannelMediaRelayEx, resumeAllChannelMediaRelayEx, and stopChannelMediaRelayEx methods are used to relay media streams across channels in multi-channel use-cases.
• Adds the leaveChannelEx [2/2] method. Compared with the leaveChannelEx [1/2] method, a new options parameter is added, which is used to choose whether to stop recording with the microphone when leaving a channel in a multi-channel use-case.

4. Client role switching

In order to enable users to know whether the switched user role is low-latency or ultra-low-latency, this release adds the newRoleOptions parameter to the onClientRoleChanged callback. The value of this parameter is as follows:

• AUDIENCE_LATENCY_LEVEL_LOW_LATENCY (1): Low latency.
• AUDIENCE_LATENCY_LEVEL_ULTRA_LOW_LATENCY (2): Ultra-low latency.

Improvements

1. Bluetooth permissions

To simplify integration, as of this release, you can use the SDK to enable Android users to use Bluetooth normally without adding the BLUETOOTH_CONNECT permission.

2. Relaying media streams across channels

This release optimizes the updateChannelMediaRelay method as follows:

• Before v4.1.0: If the target channel update fails due to internal reasons in the server, the SDK returns the error code RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED(8), and you need to call the updateChannelMediaRelay method again.
• v4.1.0 and later: If the target channel update fails due to internal server reasons, the SDK retries the update until the target channel update is successful.

3. Reconstructed AIAEC algorithm

This release reconstructs the AEC algorithm based on the AI method. Compared with the traditional AEC algorithm, the new algorithm can preserve the complete, clear, and smooth near-end vocals under poor echo-to-signal conditions, significantly improving the system's echo cancellation and dual-talk performance. This gives users a more comfortable call and live-broadcast experience. AIAEC is suitable for conference calls, chats, karaoke, and other use-cases.

Other improvements

This release includes the following additional improvements:

• Reduces the latency when pushing external audio sources.
• Improves the performance of echo cancellation when using the AUDIO_SCENARIO_MEETING scenario.
• Enhances the ability to identify different network protocol stacks and improves the SDK's access capabilities in multiple-operator network use-cases.

Issues fixed

This release fixed the following issues:

• Audience members heard buzzing noises when the host switched between speakers and earphones during live streaming.
• The call getExtensionProperty failed and returned an empty string.

API changes

Added

• setHeadphoneEQParameters

• leaveChannelEx [2/2]

• muteLocalAudioStreamEx

• muteAllRemoteAudioStreamsEx

• startRtmpStreamWithoutTranscodingEx

• startRtmpStreamWithTranscodingEx

• updateRtmpTranscodingEx

• stopRtmpStreamEx

• startChannelMediaRelayEx

• updateChannelMediaRelayEx

• pauseAllChannelMediaRelayEx

• resumeAllChannelMediaRelayEx

• stopChannelMediaRelayEx

• followEncodeDimensionRatio in CameraCapturerConfiguration

• newRoleOptions in onClientRoleChanged

• adjustUserPlaybackSignalVolumeEx

Deprecated

• onApiCallExecuted. Use the callbacks triggered by specific methods instead.

Deleted

• Removes RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED(8) in onChannelMediaRelayEvent callback

Known issues

• The package manager download is listed as 4.1.0-1. This the correct download for Voice SDK for Android v4.1.0.

v4.0.1

v4.0.1 was released on September 29, 2022.

New features

1. In-ear monitoring

This release adds getEarMonitoringAudioParams callback to set the audio data format of the in-ear monitoring. You can use your own audio effect processing module to pre-process the audio frame data of the in-ear monitoring to implement custom audio effects. After calling registerAudioFrameObserver to register the audio observer, set the audio data format in the return value of the getEarMonitoringAudioParams callback. The SDK calculates the sampling interval based on the return value of the callback, and triggers the onEarMonitoringAudioFrame callback based on the sampling interval.

2. Audio capture device test

This release adds support for testing local audio capture devices before joining channel. You can call startRecordingDeviceTest to start the audio capture device test. After the test is complete, call the stopPlaybackDeviceTest method to stop the audio capture device test.

3. Local network connection types

To make it easier for users to know the connection type of the local network at any stage, this release adds the getNetworkType method. You can use this method to get the type of network connection in use, including UNKNOWN, DISCONNECTED, LAN, WIFI, 2G, 3G, 4G, 5G. When the local network connection type changes, the SDK triggers the onNetworkTypeChanged callback to report the current network connection type.

4. Audio stream filter

This release introduces filtering audio streams based on volume. Once this function is enabled, the Agora server ranks all audio streams by volume and transports 3 audio streams with the highest volumes to the receivers by default. The number of audio streams to be transported can be adjusted; you can contact support@agora.io to adjust this number according to your use-case.

Meanwhile, Agora supports publishers to choose whether or not the audio streams being published are to be filtered based on volume. Streams that are not filtered will bypass this filter mechanism and transported directly to the receivers. In use-cases where there are a number of publishers, enabling this function helps reducing the bandwidth and device system pressure for the receivers.

To enable this function, contact support@agora.io.

5. Spatial audio effect

This release adds the following features applicable to spatial audio effect use-cases, which can effectively enhance the user's sense of presence experience in virtual interactive use-cases.

• Sound insulation area: You can set a sound insulation area and sound attenuation parameter by calling setZones. When the sound source (which can be a user or the media player) and the listener belong to the inside and outside of the sound insulation area, the listener experiences an attenuation effect similar to that of the sound in the real environment when it encounters a building partition. You can also set the sound attenuation parameter for the media player and the user, respectively, by calling setPlayerAttenuation and setRemoteAudioAttenuation, and specify whether to use that setting to force an override of the sound attenuation parameter in setZones.
• Doppler sound: You can enable Doppler sound by setting the enable_doppler parameter in SpatialAudioParams, and the receiver experiences noticeable tonal changes in the event of a high-speed relative displacement between the source and receiver (such as in a racing game use-case).
• Headphone equalizer: You can use a preset headphone equalization effect by calling the setHeadphoneEQPreset method to improve the hearing of the headphones.

Issues fixed

This release fixed the following issues.

1. In online meeting use-cases, the local user and the remote user might not hear each other after the local user is interrupted by a call.
2. After calling setCloudProxy to set the cloud proxy, calling joinChannelEx to join multiple channels failed.

API changes

Added

• getEarMonitoringAudioParams
• stopRecordingDeviceTest
• stopRecordingDeviceTest
• getNetworkType
• isAudioFilterable in the ChannelMediaOptions
• setZones
• setPlayerAttenuation
• setRemoteAudioAttenuation
• muteRemoteAudioStream
• SpatialAudioParams
• setHeadphoneEQPreset
• HEADPHONE_EQUALIZER_PRESET

Deprecated

• startEchoTest [2/3]

v4.0.0

v4.0.0 was released on September 15, 2022.

Compatibility changes

1. Integration change

This release has optimized the implementation of some features, resulting in incompatibility with v3.7.x. The following are the main features with compatibility changes:

• Multiple channel
• Media stream publishing control
• Warning codes

After upgrading the SDK, you need to update the code in your app according to your business use-cases. For details, see Migrate from v3.7.x to v4.x.

2. Callback exception handling

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

New features

1. Multiple media tracks

This release supports one RtcEngine instance to collect multiple audio sources at the same time and publish them to the remote users by setting RtcEngineEx and ChannelMediaOptions.

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

You can also experience the following features with the multi-channel capability:

• Publish multiple sets of audio streams to the remote users through different user IDs (uid).
• Mix multiple audio streams and publish to the remote users through a user ID (uid).

2. Agora media player

To make it easier for users to integrate the Agora SDK and reduce the SDK's package size, this release introduces the Agora media player. After calling the createMediaPlayer method to create a media player object, you can then call the methods in the IMediaPlayer class to experience a series of functions, such as playing local and online media files, preloading a media file, changing the CDN route for playing according to your network conditions, or sharing the audio streams being played with remote users.

3. Brand-new AI Noise Suppression

The SDK supports a new version of AI noise reduction (in comparison to the basic AI noise reduction in v3.7.x). The new AI noise reduction has better vocal fidelity, cleaner noise suppression, and adds a dereverberation option. To enable this feature, contact support@agora.io.

4. Ultra-high audio quality

To make the audio clearer and restore more details, this release adds the ULTRA_HIGH_QUALITY_VOICE enumeration. In use-cases that mainly feature the human voice, such as chat or singing, you can call setVoiceBeautifierPreset and use this enumeration to experience ultra-high audio quality.

5. Spatial audio

This feature is in experimental status. To enable this feature, contact support@agora.io. Contact technical support if needed.

You can set the spatial audio for the remote user as following:

• Local Cartesian Coordinate System Calculation: This solution uses the ILocalSpatialAudioEngine class to implement spatial audio by calculating the spatial coordinates of the remote user. You need to call updateSelfPosition and updateRemotePosition to update the spatial coordinates of the local and remote users, respectively, so that the local user can hear the spatial audio effect of the remote user.

You can also set the spatial audio for the media player as following:

• Local Cartesian Coordinate System Calculation: This solution uses the ILocalSpatialAudioEngine class to implement spatial audio. You need to call updateSelfPosition and updatePlayerPositionInfo to update the spatial coordinates of the local user and media player, respectively, so that the local user can hear the spatial audio effect of media player.

6. Real-time chorus

This release gives real-time chorus the following abilities:

• Two or more choruses are supported.
• Each singer is independent of each other. If one singer fails or quits the chorus, the other singers can continue to sing.
• Very low latency experience. Each singer can hear each other in real time, and the audience can also hear each singer in real time.

This release adds the AUDIO_SCENARIO_CHORUS enumeration. With this enumeration, users can experience ultra-low latency in real-time chorus when the network conditions are good.

7. Extensions from the Agora extensions marketplace

In order to enhance the real-time audio interactive activities based on the Agora SDK, this release supports the one-stop solution for the extensions from the Agora extensions marketplace:

• Easy to integrate: The integration of modular functions can be achieved simply by calling an API, and the integration efficiency is improved by nearly 95%.
• Extensibility design: The modular and extensible SDK design style endows the Agora SDK with good extensibility, which enables developers to quickly build real-time interactive apps based on the Agora extensions marketplace ecosystem.
• Build an ecosystem: A community of real-time audio and video apps has developed that can accommodate a wide range of developers, offering a variety of extension combinations. After integrating the extensions, developers can build richer real-time interactive functions. For details, see Use an Extension.
• Become a vendor: Vendors can integrate their products with Agora SDK in the form of extensions, display and publish them in the Agora extensions marketplace, and build a real-time interactive ecosystem for developers together with Agora. For details on how to develop and publish extensions, see Become a Vendor.

8. Enhanced channel management

To meet the channel management requirements of various business use-cases, this release adds the following functions to the ChannelMediaOptions structure:

• Sets or switches the publishing of multiple audio sources.
• Sets or switches channel profile and user role.
• Controls audio publishing delay.

Set ChannelMediaOptions when calling joinChannel or joinChannelEx to specify the publishing and subscription behavior of a media stream, for example, whether to subscribe to the audio streams of remote users. After joining the channel, call updateChannelMediaOptions to update the settings in ChannelMediaOptions at any time, for example, to switch the published audio sources.

9. Subscription allowlists and blocklists

This release introduces subscription allowlists and blocklists for remote audio streams. You can add a user ID that you want to subscribe to in your allowlist, or add a user ID for the streams you do not wish to see to your blocklists. You can experience this feature through the following APIs, and in use-cases that involve multiple channels, you can call the following methods in the RtcEngineEx interface:

• setSubscribeAudioBlacklist：Set the audio subscription blocklist.
• setSubscribeAudioWhitelist：Set the audio subscription allowlist.

If a user is added in a blocklist and a allowlist at the same time, only the blocklist takes effect.

10. Set audio scenarios

To make it easier to change audio scenarios, this release adds the setAudioScenario method. For example, if you want to change the audio scenario from AUDIO_SCENARIO_DEFAULT to AUDIO_SCENARIO_GAME_STREAMING when you are in a channel, you can call this method.

Improvements

1. Fast channel switching

This release can achieve the same switching speed as switchChannel in v3.7.x through the leaveChannel and joinChannel methods so that you don't need to take the time to call the switchChannel method.

2. Voice pitch of the local user This release adds voicePitch in AudioVolumeInfo of onAudioVolumeIndication. You can use voicePitch to get the local user's voice pitch and perform business functions such as rating for singing.

3. Device permission management

This release adds the onPermissionError method, which is automatically reported when the audio capture device or camera does not obtain the appropriate permission. You can enable the corresponding device permission according to the prompt of the callback.

Notifications

2022.10

• After you enable Notifications, your server receives the events that you subscribe to in the form of HTTPS requests.
• To improve communication security between the Notifications and your server, Agora SDRTN® uses signatures for identity verification.
• As of this release, you can use Notifications in conjunction with this product.

Known issues

The list of known issues page is continuously updated as the systems evolve. Agora suggests you regularly upgrade to the latest version of the SDK, which includes new features, bug fixes and improvements.

• iOS SDK v4.2.6

  AirPods Pro Bluetooth connection issue

  AirPods Pro does not support A2DP protocol in communication audio mode, which may lead to connection failure in that mode.

v4.6.2

Released on January 19, 2026.

Improvements

This release includes the following enhancements:

• Seamless switching for sound effect files

  Adds support for seamless switching of sound effect files. For the same sound effect file, if you call preloadEffect followed by playEffect, the SDK does not close the file after playback completes or when stopEffect is called. When you call playEffect again, the SDK reuses the loaded file to enable loop playback and seamless switching. This feature also works in multi-channel scenarios.

• Improved accuracy of network quality evaluation

  Improves the accuracy of network quality evaluation in the networkQuality callback, making the reported data better reflect the user's perceived experience.

• Support for 24kHz sampling rate for audio playback

  Adds support for audio data with a sample rate of 24000 Hz in onPlaybackAudioFrame. When calling setPlaybackAudioFrameParameters to set the playback audio format, you can set sampleRate to 24000.

• Additional improvements

  • Adds error codes AgoraErrorCodePcmSendFormat (200) and AgoraErrorCodePcmSendBufferOverflow (201) to report PCM data transmission errors.

Compatibility changes

This release introduces the following compatibility changes:

• Audio Spectrum removed from Lite and Voice packages

  To further reduce SDK package size, this version removes the Audio Spectrum feature from the Lite and Voice SDK packages. If you need the Audio Spectrum feature, please integrate the Full package.

• Decoder plugins built into the SDK

  The relevant decoder plugins are now built into the SDK to ensure overall decoding compatibility.

• armv7 architecture no longer supported by default

  Starting from this version, the SDK no longer supports the armv7 architecture by default. If you need to support it, please contact support.

Issues fixed

This release fixed the following issues:

• Beauty effects did not work in some scenarios.
• When calling leaveChannel and destroy on a sub-thread while the UI orientation changed simultaneously, the app crashed.

v4.6.0

Released on August 26, 2025.

Compatibility changes

This version includes SDK behavior changes, API deprecations, and deletions. To ensure your app functions correctly, update your code after upgrading to this version.

For details on deprecated and deleted APIs in each version, see the API Sunset Notice.

• Deprecation of direct CDN streaming APIs

  Deprecates the APIs related to direct CDN streaming, which will be removed in a future release. Agora recommends using Media Push instead.

  • setDirectCdnStreamingAudioConfiguration:
  • setDirectCdnStreamingVideoConfiguration:
  • startDirectCdnStreaming:publishUrl:mediaOptions:
  • stopDirectCdnStreaming
  • rtcEngine:didDirectCdnStreamingStateChanged:reason:message:
  • AgoraDirectCdnStreamingMediaOptions
  • AgoraDirectCdnStreamingStats
  • AgoraDirectCdnStreamingState
  • AgoraDirectCdnStreamingReason

• Deprecation of virtual metronome APIs

  Deprecates the APIs for the virtual metronome feature, which will be removed in a future release.

  • startRhythmPlayer:sound2:config:
  • configRhythmPlayer:
  • rtcEngine:didRhythmPlayerStateChanged:reason:

• Deletion of redundant APIs

  Removed the following redundant APIs and parameters:

  • setLocalPublishFallbackOption:
  • rtcEngine:didLocalPublishFallbackToAudioOnly:
  • downlinkNetworkInfoUpdate
  • wlAccStats
  • AgoraWlAccReason
  • AgoraWlAccAction
  • rtcEngine:wlAccStats:averageStats:
  • rtcEngine:wlAccMessage:action:wlAccMsg:
  • enableWirelessAccelerate
  • receivedFrameRate (removed from AgoraRtcRemoteVideoStats)

• Changes to int UID and string UID mapping

  • Before v4.6.0: If you used registerLocalUserAccountWithAppID:userAccount: to register a string UID (for example, "aa") and obtain an int UID (for example, 123), joining a channel with this int UID automatically mapped it to the original string UID ("aa").
  • From v4.6.0: The SDK no longer automatically maps an int UID to the original string UID. If you need to join the channel with the original string UID, call joinChannelByUserAccount:token:channelId:joinSuccess: directly with the string UID. After upgrading, review and update your app logic to ensure users join the channel with the expected identity.

• Default log path change

  This release changes the default log path from AppSandbox/Library/documents/agorasdk.log to AppSandbox/Library/caches/agorasdk.log. If you upgrade the SDK from v4.3.1 or later to v4.6.0, ensure that you use the new path to access the log file.

New features

• Multipath network transmission

  Introduced multipath transmission for devices with multiple network interfaces (such as 5G, Wi-Fi, and LAN). This feature improves stability in challenging network environments and is suitable for scenarios such as in-vehicle systems, IoT, trains, and highways. Enable it by setting enableMultipath in AgoraRtcChannelMediaOptions to YES.

  • Dynamic mode: Dynamically selects the optimal path based on network conditions. Suitable for scenarios sensitive to data consumption but requiring high quality, such as meetings and educational settings. Optionally set preferMultipathType to prioritize a path type.
  • Duplicate mode: Sends data simultaneously over all available paths for maximum stability. This mode eliminates the impact of poor network conditions and is suitable for scenarios with extreme quality requirements, such as outdoor broadcasting and parallel control.

  Configure uplink and downlink modes separately with uplinkMultipathMode and downlinkMultipathMode. Monitor performance with the rtcEngine:didMultipathStatsChanged: callback, which reports data usage and other statistics for each path.

• Asynchronous engine destruction

  Added the destroy: method with an option for asynchronous destruction, triggering the engineReleasedBlock callback.

• Token renewal result callback

  Added the rtcEngine:didRenewTokenResult: callback and RENEW_TOKEN_ERROR_CODE for handling the result of renewToken:.

• Other new features

  • Added setPlaybackAudioFrameBeforeMixingParameters: to configure the format of raw audio frames returned in onPlaybackAudioFrameBeforeMixing:channelId:uid:.
  • Added preloadEffectEx:soundId: for preloading audio effects in a specific channel, supporting both local and online files.
  • Added playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:startPos: for playing audio effects in a specific channel with advanced controls.

Improvements

• Added support for G.711 and G.722 audio codecs when inter-operating with the Web SDK for better cross-platform audio compatibility.

Fixed issues

This version fixes the following issues:

• Online audio effect playback restarted from the beginning when seekToPosition: was called.
• Occasional echoes in media volume mode when a broadcaster published a microphone audio stream while playing an audio effect with playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: and music with startAudioMixing:loopback:cycle:startPos:.
• Missing media metadata observer callback when setMediaMetadataDelegate:withType: was called after setExternalVideoSource:useTexture:sourceType: (Android, iOS).
• Occasional crashes (Android, iOS).
• Media relay occasionally reported AgoraChannelMediaRelayStateFailure and AgoraChannelMediaRelayErrorServerErrorResponse after the following sequence: join, relay, unpublish, leave, rejoin, and start relay again.

v4.5.2

v4.5.2 was released on April 22, 2025.

Issues fixed

This release fixes the following issues:

• While playing a multi-track media file, noise was heard when adjusting the audio pitch using setAudioPitch.
• When the host called createCustomAudioTrack:config: to create a custom audio track with trackType set to AUDIO_TRACK_DIRECT, then called pushExternalAudioFrameRawData:samples:sampleRate:channels:trackId:timestamp: to push custom audio frames to a channel, and finally called playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: to play an audio effect, audience members in the channel heard noise.
• Apps using the SDK occasionally experienced UI lag caused by main thread blocking during audio and video interactions.
• Calling openWithMediaSource: and setting isLiveSource to YES in the source parameter to play a video stream caused playback failure.
• When calling enableVirtualBackground to enable the virtual background, the background image appeared enlarged and blurry when the device was rotated.
• When the sender transmitted multi-channel encoded audio, noise was occasionally heard by the receiver.
• When the app integrated a media player and called open twice to load different media resources consecutively, the second call incorrectly triggered the AgoraRtcMediaPlayer:infoUpdated: callback with information from the first media resource.
• After enabling user volume indication with enableAudioVolumeIndication:smooth:reportVad:, the rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: callback reported a local user volume of 0 for both local and remote users.
• The app occasionally froze during audio and video communication.
• When you called enableVideoImageSource:options: to enable the video image source feature, the sending side appeared to stream successfully, but the rtcEngine:didVideoPublishStateChange:sourceType:oldState:newState:elapseSinceLastState: callback reported a publish failure.
• In multi-channel scenarios, if the app called setupRemoteVideoEx:connection: to initialize the remote user's view before successfully calling joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:, the first frame of the remote video occasionally experienced significant delay.

v4.5.1

v4.5.1 was released on March 6, 2025.

New Features

1. AI Conversation Scenario

   This version introduces the AgoraAudioScenarioAiClient audio scenario, specifically designed for interacting with the conversational AI agent created by Conversational AI Engine. This scenario optimizes the audio transmission algorithm based on the characteristics of AI-generated voices, ensuring stable voice data transmission even in weak network conditions with up to 80% packet loss. The optimization enhances conversation continuity and reliability, adapting to various challenging network environments.

Improvements

• Reduced SDK initialization time on specific device models.

Issues Fixed

This release resolves the following issues:

• When using the pause method to pause playback, then calling seekToPosition: to move to a specific position, and finally calling play, the Media Player resumed from the paused position instead of the specified position.
• When using the Media Player, the file path of the media resource returned by getPlaySrc did not update after calling switchSrc:syncPts: to switch to a new media resource.
• Pushing video frames in i420 format to the channel while using CVPixelBuffer to process these frames caused crashes.
• Calling setupLocalVideo: to set up two views and then enabling face detection with enableFaceDetection: prevented face information from being detected in the newly assigned views.
• In screen-sharing scenarios, the receiving user saw a green line on the shared image.
• In interactive live streaming scenarios, after joining a channel as an audience member using a string user ID, audio occasionally became unsynchronized with video.
• AI noise suppression and AI echo cancellation plugins sometimes failed when used together.

v4.5.0

v4.5.0 was released on November 27, 2024.

Compatibility changes

This version includes optimizations to some features, including changes to SDK behavior and API renaming and deletion. To ensure normal operation of the project, update the code in the app after upgrading to this release.

New features

1. Local audio mixing

   This version introduces the local audio mixing feature. You can call the startLocalAudioMixer method to mix the audio streams from the local microphone, media player, sound card, and remote audio streams into a single audio stream, which can then be published to the channel. When you no longer need audio mixing, you can call the stopLocalAudioMixer method to stop local audio mixing. During the mixing process, you can call the updateLocalAudioMixerConfiguration method to update the configuration of the audio streams being mixed.

   Example use cases for this feature include:

   • When using the local video mixing feature, the associated audio streams of the mixed video streams can be simultaneously captured and published.
   • In live streaming use-cases, users can receive audio streams within the channel, mix multiple audio streams locally, and then forward the mixed audio stream to other channels.
   • In educational use-cases, teachers can mix the audio from interactions with students locally and then forward the mixed audio stream to other channels.

Improvements

1. Custom audio capture improvements

   This version adds the enableAudioProcessing member parameter to AgoraAudioTrackConfig, which is used to control whether to enable 3A audio processing for custom audio capture tracks of the AUDIO_TRACK_DIRECT type. The default value of this parameter is NO, meaning that audio processing is not enabled. Users can enable it as needed, enhancing the flexibility of custom audio processing.

2. Other improvements

   • This version optimizes the logic for calling queryDeviceScore to obtain device score levels, improving the accuracy of the score results.
   • After calling enableLocalAudio: to disable local audio capture within the channel, the mute side button on the phone can be used to mute the background sound effects played by the app.
   • When calling setPlaybackSpeed: to set the playback speed of an audio file, the minimum supported speed is 0.3x.

Bug fixes

This version fixes the following issues:

• Occasional instances where the receiving end cannot hear the sender during audio and video interaction.
• During audio and video interaction, if the sender's device system version is iOS 17, the receiving end occasionally cannot hear the sender.
• No sound when playing online media resources using the media player after the app starts.
• Occasional instances of no sound in audio capture after resuming from being interrupted by other system apps.
• Calling startAudioMixing:loopback:cycle: and then immediately calling pauseAudioMixing to pause the music file playback does not take effect.

v4.4.0

v4.4.0 was released on August 5, 2024.

Compatibility changes

This version includes optimizations to some features, including changes to SDK behavior and API renaming and deletion. To ensure normal operation of the project, update the code in the app after upgrading to this release.

1. To distinguish context information in different extension callbacks, this version removes the original extension callbacks and adds new corresponding callbacks that contain context information (see table below). You can identify the extension name, the user ID, and the service provider name through AgoraExtensionContext in each callback.

   Original callback	New callback
   onEvent	onExtensionEventWithContext
   onExtensionStarted	onExtensionStartedWithContext
   onExtensionStopped	onExtensionStoppedWithContext
   onExtensionError	onExtensionErrorWithContext

2. Before v4.4.0, when a user role was set to audience and setAudioScenario was called to set the audio scenario to chatroom (AgoraAudioScenarioChatRoom), the user would see a microphone permission request popup. As of v4.4.0, the SDK uses native iOS APIs to control the microphone, so audience members in a chatroom scenario will no longer receive the microphone permission request popup.

3. This version renames the receiveMetadata callback to didMetadataReceived and removes the data and timeStamp parameters. You can get metadata-related information, including timeStamp (timestamp of the sent data), uid (user ID), and channelId (channel name) through the newly-added metadata parameter.

New features

1. Voice AI tuner

   This version introduces the voice AI tuner feature, which can enhance the sound quality and tone, similar to a physical sound card. You can enable the voice AI tuner feature by calling the enableVoiceAITuner method and passing in the sound effect types supported in the AgoraVoiceAITunerType enum to achieve effects like deep voice, cute voice, husky singing voice, and so on.

Improvements

This version includes the following improvements:

• Optimizes the transmission strategy: Calling enableInstantMediaRendering no longer impacts the security of the transmission link.
• Deprecates redundant enumeration values AgoraClientRoleChangeFailedRequestTimeout and AgoraClientRoleChangeFailedConnectionFailed in AgoraClientRoleChangeFailedReason.

Issues fixed

This release fixes the following issues:

• Occasional app crashes occurred when multiple remote users joined a channel simultaneously during real-time interaction.
• After the sender called startDirectCdnStreaming to start direct CDN streaming, frequent switching or toggling of the network occasionally resulted in a black screen on the receiver's end without a streaming failure callback on the sender's end.
• Audio playback failed when pushing external audio data using pushExternalAudioFrameRawData and the sample rate was not set as a recommended value, such as 22050 Hz and 11025 Hz.

v4.3.2

v4.3.2 was released on June 4, 2024.

Improvements

1. This release enhances the usability of the setRemoteSubscribeFallbackOption method by removing the timing requirements for invocation. It can now be called both before and after joining the channel to dynamically switch audio and video stream fallback options in weak network conditions.

2. The Agora media player supports playing mp4 files with an Alpha channel.

Issues fixed

This version fixed the following issues:

• The app occasionally crashed when remote users left the channel.
• When playing an audio file using [startAudioMixing 1/2] and the playing finished, the SDK sometimes failed to trigger the audioMixingStateChanged (AgoraAudioMixingStateTypeStopped, AgoraAudioMixingReasonAllLoopsCompleted) callback which reports that the playing is completed.
• When calling the [playEffect 3/3] method to play sound effect files shorter than 1 second with loopCount set to 0, there was no sound.

v4.3.1

v4.3.1 was released on April 29, 2024.

New features

1. Privacy manifest file

   To meet Apple's safety compliance requirements for app publication, the SDK now includes a privacy manifest file, PrivacyInfo.xcprivacy, detailing the SDK's API calls that access or use user data, along with a description of the types of data collected.

   If you need to publish an app with SDK versions prior to v4.3.1 to the Apple App Store, manually add the PrivacyInfo.xcprivacy file to your Xcode project. For more details, see How can I add a privacy manifest to my iOS app?.

2. Data stream encryption

   This version adds datastreamEncryptionEnabled to AgoraEncryptionConfig for enabling data stream encryption. You can set this when you activate encryption with enableEncryption. If there are issues causing failures in data stream encryption or decryption, these can be identified by the newly added ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE and ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE enumerations.

3. Other features

   • A new method enableEncryptionEx is added for enabling media stream or data stream encryption in multi-channel use-cases.
   • A new method setAudioMixingPlaybackSpeed is introduced for setting the playback speed of audio files.
   • A new method getCallIdEx is introduced for retrieving call IDs in multi-channel use-cases.

4. Beta features

   • Speech driven avatar is released in beta. See beta documentation for details.

Improvements

1. Custom audio capture optimization

   To enhance the flexibility of custom audio capture, this release deprecates pushExternalAudioFrameSampleBuffer [1/2] and introduces pushExternalAudioFrameSampleBuffer [2/2]. Compared to the deprecated method, the new method adds parameters such as sampleRate, channels, and trackId. These support pushing external CMSampleBuffer audio data to the channel via custom audio tracks, and allow for the setting of sample rates and channel counts for external audio sources.

2. CPU consumption reduction of in-ear monitoring

   This release adds an enumerator AgoraEarMonitoringFilterReusePostProcessingFilter in AgoraEarMonitoringFilterType. For complex audio processing use-cases, you can specify this option to reuse the audio filter after sender-side processing in in-ear monitoring, thereby reducing CPU consumption. Note that this option may increase the latency of in-ear monitoring, which is suitable for latency-tolerant use-cases requiring low CPU consumption.

3. Other improvements

   This version also includes the following improvements:

   • Enhanced media player capabilities to handle WebM format videos, including support for rendering alpha channels.
   • In AgoraAudioEffectPreset, a new enumeration AgoraAudioEffectPresetRoomAcousticsChorus (chorus effect) is added, enhancing the spatial presence of vocals in chorus use-cases.
   • In AgoraRtcRemoteAudioStats, a new e2eDelay field is added to report the delay from when the audio is captured on the sending end to when the audio is played on the receiving end.

API changes

Added

• setFaceInfoDelegate
• AgoraFaceInfoDelegate
• onFaceInfo
• AgoraMediaSourceType adds AgoraMediaSourceTypeSpeechDriven
• AgoraEncryptionConfig adds datastreamEncryptionEnabled
• AgoraEncryptionErrorType adds the following enumerations:
• ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE
• ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE
• AgoraRtcRemoteAudioStats adds e2eDelay
• AgoraErrorCode adds AgoraErrorCodeDatastreamDecryptionFailed
• AgoraAudioEffectPreset adds AgoraAudioEffectPresetRoomAcousticsChorus, enhancing the spatial presence of vocals in chorus use-cases
• getCallIdEx
• enableEncryptionEx
• setAudioMixingPlaybackSpeed
• AgoraEarMonitoringFilterType adds a new enumeration AgoraEarMonitoringFilterBuiltInAudioFilters
• pushExternalAudioFrameSampleBuffer [2/2]

Deprecated

• pushExternalAudioFrameSampleBuffer [1/2]

v4.3.0

v4.3.0 was released on February 22, 2024.

Compatibility changes

This release has optimized the implementation of some functions, involving renaming or deletion of some APIs. To ensure the normal operation of the project, you need to update the code in the app after upgrading to this release.

1. Renaming parameters in callbacks

   In order to make the parameters in some callbacks and the naming of enumerations in enumeration classes easier to understand, the following modifications have been made in this release. Please modify the parameter settings in the callbacks after upgrading to this release.

   Callback	Original parameter name	New parameter name
   localAudioStateChanged	error	reason
   localVideoStateChanged	error	reason
   onDirectCdnStreamingStateChanged	error	reason
   didChangedToState	error	reason
   rtmpStreamingChangedToState	errCode	reason

   Original enumeration class	New enumeration class
   AgoraAudioLocalError	AgoraAudioLocalReason
   AgoraLocalVideoStreamError	AgoraLocalVideoStreamReason
   AgoraDirectCdnStreamingError	AgoraDirectCdnStreamingReason
   AgoraMediaPlayerError	AgoraMediaPlayerReason
   AgoraRtmpStreamingError	AgoraRtmpStreamingReason

   Note: For specific renaming of enumerations, please refer to API changes.

2. Channel media relay

   To improve interface usability, this release removes some methods and callbacks for channel media relay. Use the alternative options listed in the table below:

   Deleted methods and callbacks	Alternative methods and callbacks
   startChannelMediaRelay updateChannelMediaRelay	startOrUpdateChannelMediaRelay
   startChannelMediaRelayEx updateChannelMediaRelayEx	startOrUpdateChannelMediaRelayEx
   didReceiveChannelMediaRelayEvent	channelMediaRelayStateDidChange

3. Audio route

   Starting with this release, AgoraAudioOutputRoutingBluetooth in AgoraAudioOutputRouting is renamed to AgoraAudioOutputRoutingBluetoothDeviceHfp, representing a Bluetooth device using the HFP protocol. AgoraAudioOutputRoutingBluetoothDeviceA2dp(10) is added to represent the audio route to a Bluetooth device using the A2DP protocol.

4. Log encryption behavior changes

   For security and performance reasons, as of this release, the SDK encrypts logs and no longer supports printing plaintext logs via the console.

   Refer to the following solutions for different needs:

   • If you need to know the API call status, please check the API logs and print the SDK callback logs yourself.
   • For any other special requirements, please contact technical support and provide the corresponding encrypted logs.

New features

1. Query Device Score

   This release adds the queryDeviceScore method to query the device's score level to ensure that the user-set parameters do not exceed the device's capabilities. For example, in HD or UHD video use-cases, you can first call this method to query the device's score. If the returned score is low (for example, below 60), you need to lower the video resolution to avoid affecting the video experience. The minimum device score required for different business use-cases is varied. For specific score recommendations, please contact technical support.

2. Select different audio tracks for local playback and streaming

   This release introduces the selectMultiAudioTrack method that allows you to select different audio tracks for local playback and streaming to remote users. For example, in use-cases like online karaoke, the host can choose to play the original sound locally and publish the accompaniment in the channel. Before using this function, you need to open the media file through the openWithMediaSource method and enable this function by setting the enableMultiAudioTrack parameter in AgoraMediaSource.

3. Device test for audio capturing and playback

   This release introduces the following methods to test whether the audio capturing or playback devices work properly before joining a channel:

   • startRecordingDeviceTest: Tests whether the local audio capturing device, such as the speaker, is working properly. After calling this method, the SDK triggers a callback at the time interval set in this method, which reports uid = 0 and the volume information of the capturing device. After the test is completed, you need to call the newly added stopRecordingDeviceTest method to stop the test.
   • startPlaybackDeviceTest: Tests whether the local audio playback device is working properly. You can specify the audio file to be played through the testAudioFilePath parameter and see if your audio device works properly. After the test is completed, you need to call the newly added stopPlaybackDeviceTest method to stop the test.

4. Others

   This release has passed the test verification of the following APIs and can be applied to the entire series of the SDK v4.x.

   • setRemoteSubscribeFallbackOption: Sets fallback option for the subscribed video stream in weak network conditions.
   • didRemoteSubscribeFallbackToAudioOnly: Occurs when the subscribed video stream falls back to audio-only stream due to weak network conditions or switches back to the video stream after the network conditions improve.
   • [setPlayerOption 1/2] and [setPlayerOption 2/2]: Sets media player options for providing technical previews or special customization features.
   • enableCustomAudioLocalPlayback: Sets whether to enable the local playback of external audio source.

Improvements

1. SDK task processing scheduling optimization

   This release optimizes the scheduling mechanism for internal tasks within the SDK, with improvements in the following aspects:

   • The speed of video rendering and audio playback for both remote and local first frames improves by 10% to 20%.
   • The API call duration and response time are reduced by 5% to 50%.
   • The SDK's parallel processing capability significantly improves, delivering higher video quality (720P, 24 fps) even on lower-end devices. Additionally, image processing remains more stable in use-cases involving high resolutions and frame rates.
   • The stability of the SDK is further enhanced, leading to a noticeable decrease in the crash rate across various specific use-cases.

2. In-ear monitoring volume boost

   This release provides users with more flexible in-ear monitoring audio adjustment options, supporting the ability to set the in-ear monitoring volume to four times the original volume by calling setInEarMonitoringVolume.

3. Spatial audio effects usability improvement

   • This release optimizes the design of the setZones method, supporting the ability to set the zones parameter to NULL, indicating the clearing of all echo cancellation zones.
   • As of this release, it is no longer necessary to unsubscribe from the audio streams of all remote users within the channel before calling methods in AgoraLocalSpatialAudioKit.
   • This release introduces the updateSelfTransform method, designed to pass position vectors for direct rendering in iOS native frameworks such as SceneKit or RealityKit.

4. Local audio state changed callback optimization

   This release introduces the following enumeration in AgoraAudioLocalReason, enabling users to obtain more details about local audio errors through the localAudioStateChanged callback:

   • AgoraAudioLocalReasonInterrupted: The local audio capture is interrupted by system calls, Siri, or alarm clocks. Remind your users to end the phone call, Siri, or alarm clock if the local audio capture is required.

5. Other Improvements

   This release also includes the following improvements:

   • This release optimizes the SDK's domain name resolution strategy, improving the stability of calling to resolve domain names in complex network environments.
   • When passing in an image with transparent background as the virtual background image, the transparent background can be filled with customized color.
   • This release adds the earMonitorDelay and aecEstimatedDelay members in AgoraRtcLocalAudioStats to report ear monitor delay and acoustic echo cancellation (AEC) delay, respectively.
   • The cacheStats callback is added to report the statistics of the media file being cached. This callback is triggered once per second after file caching is started.
   • The playbackStats callback is added to report the statistics of the media file being played. This callback is triggered once per second after the media file starts playing. You can obtain information like the audio and video bitrate of the media file through AgoraMediaPlayerPlaybackStats.

API changes

Added

• didTranscodedStreamLayoutInfoUpdatedWithUserId
• AgoraVideoLayoutInfo
• The subviewUid member in AgoraRtcVideoCanvas
• updateSelfTransform
• The AgoraAudioLocalReasonInterrupted enumeration in AgoraAudioLocalReason
• enableCustomAudioLocalPlayback
• queryDeviceScore
• The AgoraMediaSourceTypeCustomVideo enumeration in AgoraMediaSourceType
• [setBeautyEffectOptions 2/2]
• [setLowlightEnhanceOptions 2/2]
• [setVideoDenoiserOptions 2/2]
• [setColorEnhanceOptions 2/2]
• [enableVirtualBackground 2/2]
• The AgoraAudioOutputRoutingBluetoothDeviceA2dp enumeration in AgoraAudioOutputRouting
• Adds the earMonitorDelay and aecEstimatedDelay in AgoraRtcLocalAudioStats
• selectMultiAudioTrack
• cacheStats
• playbackStats
• AgoraMediaPlayerPlaybackStats
• startPlaybackDeviceTest
• stopPlaybackDeviceTest

Modified

• pushExternalVideoFrame[1/2] is migrated from AgoraRtcEngineKit(Ex) to AgoraRtcEngineKit
• AgoraAudioOutputRoutingBluetooth is renamed as AgoraAudioOutputRoutingBluetoothDeviceHfp
• All Error fields in the following enumerations are changed to Reason:
• AgoraAudioLocalErrorOK
• AgoraAudioLocalErrorFailure
• AgoraAudioLocalErrorDeviceNoPermission
• AgoraAudioLocalErrorDeviceBusy
• AgoraAudioLocalErrorRecordFailure
• AgoraAudioLocalErrorEncodeFailure
• AgoraLocalVideoStreamErrorOK
• AgoraLocalVideoStreamErrorFailure
• AgoraLocalVideoStreamErrorDeviceNoPermission
• AgoraLocalVideoStreamErrorDeviceBusy
• AgoraLocalVideoStreamErrorCaptureFailure
• AgoraLocalVideoStreamErrorCodecNotSupport
• AgoraLocalVideoStreamErrorCaptureInBackGround
• AgoraLocalVideoStreamErrorCaptureMultipleForegroundApps
• AgoraLocalVideoStreamErrorCaptureNoDeviceFound
• AgoraLocalVideoStreamErrorCaptureDeviceDisconnected
• AgoraLocalVideoStreamErrorCaptureDeviceInvalidId
• AgoraDirectCdnStreamingErrorOK
• AgoraDirectCdnStreamingErrorFailed
• AgoraDirectCdnStreamingErrorAudioPublication
• AgoraDirectCdnStreamingErrorVideoPublication
• AgoraDirectCdnStreamingErrorNetConnect
• AgoraDirectCdnStreamingErrorBadName
• AgoraMediaPlayerErrorNone
• AgoraMediaPlayerErrorInvalidArguments
• AgoraMediaPlayerErrorInternal
• AgoraMediaPlayerErrorNoSource
• AgoraMediaPlayerErrorInvalidMediaSource
• AgoraMediaPlayerErrorUnknowStreamType
• AgoraMediaPlayerErrorObjNotInitialized
• AgoraMediaPlayerErrorCodecNotSupported
• AgoraMediaPlayerErrorVideoRenderFailed
• AgoraMediaPlayerErrorInvalidState
• AgoraMediaPlayerErrorUrlNotFound
• AgoraMediaPlayerErrorInvalidConnectState
• AgoraMediaPlayerErrorSrcBufferUnderflow
• AgoraMediaPlayerErrorInterrupted
• AgoraMediaPlayerErrorNotSupported
• AgoraMediaPlayerErrorTokenExpired
• AgoraMediaPlayerErrorUnknown
• AgoraRtmpStreamingErrorOK
• AgoraRtmpStreamingErrorInvalidParameters
• AgoraRtmpStreamingErrorEncryptedStreamNotAllowed
• AgoraRtmpStreamingErrorConnectionTimeout
• AgoraRtmpStreamingErrorInternalServerError
• AgoraRtmpStreamingErrorRtmpServerError
• AgoraRtmpStreamingErrorTooOften
• AgoraRtmpStreamingErrorReachLimit
• AgoraRtmpStreamingErrorNotAuthorized
• AgoraRtmpStreamingErrorStreamNotFound
• AgoraRtmpStreamingErrorFormatNotSupported
• AgoraRtmpStreamingErrorNotBroadcaster
• AgoraRtmpStreamingErrorTranscodingNoMixStream
• AgoraRtmpStreamingErrorNetDown
• AgoraRtmpStreamingErrorInvalidPrivilege
• AgoraRtmpStreamingErrorUnpublishOK

Deleted

• startChannelMediaRelay
• updateChannelMediaRelay
• startChannelMediaRelayEx
• updateChannelMediaRelayEx
• didReceiveChannelMediaRelayEvent
• AgoraChannelMediaRelayEvent

v4.2.6

v4.2.6 was released on November 17, 2023.

Issues fixed

This release fixed the following issue:

• When using an iOS 16 or later device with Bluetooth headphones connected before joining the channel, the audio routing after joining the channel was not as expected: Audio was played from the speaker, not the Bluetooth headphones.

v4.2.3

v4.2.3 was released on October 11, 2023.

Improvements

Other improvements

This release includes the following additional improvements:

• Optimizes the logic of handling invalid parameters. When you call the setPlaybackSpeed method to set the playback speed of audio files, if you pass an invalid parameter, the SDK returns the error code -2, which means that you need to reset the parameter.
• Optimizes the logic of Token parsing, in order to prevent an app from crash when an invalid token is passed in.

Issues fixed

This release fixed the following issues:

• Occasional failure of joining a channel when the local system time was not set correctly.
• When calling the playEffect [3/3] method to play two audio files using the same soundId, the first audio file was sometimes played repeatedly.

v4.2.2

v4.2.2 was released on july 27, 2023.

New features

1. Wildcard token

   This release introduces wildcard tokens. Agora supports setting the channel name used for generating a token as a wildcard character. The token generated can be used to join any channel if you use the same user id. In use-cases involving multiple channels, such as switching between different channels, using a wildcard token can avoid repeated application of tokens every time users joining a new channel, which reduces the pressure on your token server. See Deploy a token server.

   All 4.x SDKs support using wildcard tokens.

2. Preloading channels

   This release adds preloadChannelByToken[1/2] and preloadChannelByToken[2/2] methods, which allows a user whose role is set as audience to preload channels before joining one. Calling the method can help shortening the time of joining a channel, thus reducing the time it takes for audience members to hear the host.

   When preloading more than one channels, Agora recommends that you use a wildcard token for preloading to avoid repeated application of tokens every time you joining a new channel, thus saving the time for switching between channels. See Deploy a token server.

Improvements

Channel media relay

The number of target channels for media relay has been increased to 6. When calling startOrUpdateChannelMediaRelay and startOrUpdateChannelMediaRelayEx, you can specify up to 6 target channels.

Issues fixed

This release fixed slow channel reconnection after the connection was interrupted due to network reasons.

API changes

Added

• startPreview [2/2]
• stopPreview [2/2]
• setCameraExposureFactor
• isCameraExposureSupported
• preloadChannelByToken [1/2]
• preloadChannelByToken [2/2]
• updatePreloadChannelToken
• The following members in AgoraRtcChannelMediaOptions:
• publishThirdCameraTrack
• publishFourthCameraTrack
• publishThirdScreenTrack
• publishFourthScreenTrack
• AgoraVideoCodecCapLevels
• AgoraVideoCodecCapabilityLevel
• backgroundColor in AgoraRtcVideoCanvas
• codecLevels in CodecCapAgoraVideoCodecCapInfoInfo
• AgoraVideoRemoteReasonCodecNotSupport in AgoraVideoRemoteReason

v4.2.1

This version was released on June 21, 2023.

Improvements

This version improves the network transmission strategy, enhancing the smoothness of audio interactions.

Fixed Issues

This version fixed the following issues:

• Inability to join channels caused by SDK's incompatibility with some older versions of AccessToken.
• After the sending end called setAINSMode to activate AI noise reduction, occasional echo was observed by the receiving end.
• Brief noise occurred while playing media files using the media player.
• Occasional crash after calling the destroyMediaPlayer method.

v4.2.0

v4.2.0 was released on May 24, 2023.

Compatibility changes

If you use the features mentioned in this section, ensure that you modify the implementation of the relevant features after upgrading the SDK.

1. Channel media options

• publishCustomAudioTrackEnableAec in AgoraRtcChannelMediaOptions is deleted. Use publishCustomAudioTrack instead.
• publishCustomAudioSourceId in AgoraRtcChannelMediaOptions is renamed to publishCustomAudioTrackId.

2. Miscellaneous

• didApiCallExecute is deleted. Agora recommends getting the results of the API implementation through relevant channels and media callbacks.
• startChannelMediaRelay, updateChannelMediaRelay, startChannelMediaRelayEx, and updateChannelMediaRelayEx are deprecated. Use startOrUpdateChannelMediaRelay and startOrUpdateChannelMediaRelayEx instead.

New features

1. AI Noise Suppression

This release introduces public APIs for the AI Noise Suppression function. Once enabled, the SDK automatically detects and reduces background noises. Whether in bustling public venues or real-time competitive arenas that demand lightning-fast responsiveness, this function guarantees optimal audio clarity, providing users with an elevated audio experience. You can enable this function through the newly-introduced setAINSMode method and set the noise suppression mode as balance, aggressive, or low latency according to your use-case.

2. Cross-device synchronization

In real-time collaborative singing use-cases, network issues can cause inconsistencies in the downlinks of different client devices. To address this, this release introduces getNtpWallTimeInMs for obtaining the current Network Time Protocol (NTP) time. By using this method to synchronize lyrics and music across multiple client devices, users can achieve synchronized singing and lyrics progression, resulting in a better collaborative experience.

Improvements

1. Voice changer

This release introduces the setLocalVoiceFormant method that allows you to adjust the formant ratio to change the timbre of the voice. This method can be used together with the setLocalVoicePitch method to adjust the pitch and timbre of voice at the same time, enabling a wider range of voice transformation effects.

2. Channel media relay

This release introduces startOrUpdateChannelMediaRelay and startOrUpdateChannelMediaRelayEx, allowing for a simpler and smoother way to start and update media relay across channels. With these methods, developers can easily start the media relay across channels and update the target channels for media relay with a single method. Additionally, the internal interaction frequency has been optimized, effectively reducing latency in function calls.

3. Custom audio tracks

To better meet the needs of custom audio capture use-cases, this release adds createCustomAudioTrack and destroyCustomAudioTrack for creating and destroying custom audio tracks. Two types of audio tracks are also provided for users to choose from, further improving the flexibility of capturing external audio source:

• Mixable audio track: Supports mixing multiple external audio sources and publishing them to the same channel, suitable for multi-channel audio capture use-cases.
• Direct audio track: Only supports publishing one external audio source to a single channel, suitable for low-latency audio capture use-cases.

Issues fixed

This release fixed the following issues:

• When the host frequently switched the user role between broadcaster and audience in a short period of time, the audience members could not hear the audio of the host.
• Abnormal client status caused by an exception in the onRemoteAudioStateChanged callback.

API changes

Added

• startOrUpdateChannelMediaRelay
• startOrUpdateChannelMediaRelayEx
• getNtpWallTimeInMs
• setAINSMode
• createAudioCustomTrack
• destroyAudioCustomTrack
• AudioTrackConfig
• AgoraAudioTrackType
• AgoraApplicationScenarioType
• The domainLimit and autoRegisterAgoraExtensions members in AgoraRtcEngineConfig
• The channelId and uid parameters in stateDidChanged and informationDidUpdated callbacks

Deprecated

• startChannelMediaRelay
• startChannelMediaRelayEx
• updateChannelMediaRelay
• updateChannelMediaRelayEx
• didReceiveChannelMediaRelayEvent
• AgoraChannelMediaRelayEvent

Deleted

• didApiCallExecute
• publishCustomAudioTrackEnableAec in AgoraRtcChannelMediaOptions

v4.1.1

v4.1.1 was released on February 8, 2023.

New features

Instant frame rendering

This release adds the enableInstantMediaRendering method to enable instant rendering mode for audio frames, which can speed up the first audio frame rendering after the user joins the channel.

Issues fixed

This release fixed the issue that playing audio files with a sample rate of 48 kHz failed.

API changes

Added

enableInstantMediaRendering

v4.1.0

v4.1.0 was released on December 15, 2022.

New features

1. Headphone equalization effect

This release adds the setHeadphoneEQParameters method, which is used to adjust the low- and high-frequency parameters of the headphone EQ. This mainly useful in spatial audio use-cases. If you cannot achieve the expected headphone EQ effect after calling setHeadphoneEQPreset, you can call setHeadphoneEQParameters to adjust the EQ.

2. MPUDP (MultiPath UDP) (Beta)

As of this release, the SDK supports MPUDP protocol, which enables you to connect and use multiple paths to maximize the use of channel resources based on the UDP protocol. You can use different physical NICs on both mobile and desktop and aggregate them to effectively combat network jitter and improve transmission quality.

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

3. Multi-channel management

This release adds a series of multi-channel related methods that you can call to manage audio streams in multi-channel use-cases.

• The muteLocalAudioStreamEx method is used to cancel or resume publishing a local audio stream, respectively.
• The muteAllRemoteAudioStreamsEx is used to cancel or resume the subscription of all remote users to audio streams, respectively.
• The startRtmpStreamWithoutTranscodingEx, startRtmpStreamWithTranscodingEx, updateRtmpTranscodingEx, and stopRtmpStreamEx methods are used to implement Media Push in multi-channel use-cases.
• The startChannelMediaRelayEx, updateChannelMediaRelayEx, pauseAllChannelMediaRelayEx, resumeAllChannelMediaRelayEx, and stopChannelMediaRelayEx methods are used to relay media streams across channels in multi-channel use-cases.
• Adds the leaveChannelEx [2/2] method. Compared with the leaveChannelEx [1/2] method, a new options parameter is added, which is used to choose whether to stop recording with the microphone when leaving a channel in a multi-channel use-case.

4. Client role switching

In order to enable users to know whether the switched user role is low-latency or ultra-low-latency, this release adds the newRoleOptions parameter to the didClientRoleChanged callback. The value of this parameter is as follows:

• AgoraAudienceLatencyLevelLowLatency (1): Low latency.
• AgoraAudienceLatencyLevelUltraLowLatency (2): Ultra-low latency.

Improvements

1. Relaying media streams across channels

This release optimizes the updateChannelMediaRelay method as follows:

• Before v4.1.0: If the target channel update fails due to internal reasons in the server, the SDK returns the error code AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8), and you need to call the updateChannelMediaRelay method again.
• v4.1.0 and later: If the target channel update fails due to internal server reasons, the SDK retries the update until the target channel update is successful.

2. Reconstructed AIAEC algorithm

This release reconstructs the AEC algorithm based on the AI method. Compared with the traditional AEC algorithm, the new algorithm can preserve the complete, clear, and smooth near-end vocals under poor echo-to-signal conditions, significantly improving the system's echo cancellation and dual-talk performance. This gives users a more comfortable call and live-broadcast experience. AIAEC is suitable for conference calls, chats, karaoke, and other use-cases.

Other improvements

This release includes the following additional improvements:

• Reduces the latency when pushing external audio sources.
• Improves the performance of echo cancellation when using AgoraAudioScenarioMeeting.
• Enhances the ability to identify different network protocol stacks and improves the SDK's access capabilities in multiple-operator network scenarios.

Issues fixed

This release fixed the following issues:

• Calling startAudioMixing to play music files in the ipod-library://item path failed.
• Audience members heard buzzing noises when the host switched between speakers and earphones during live streaming.
• Different timestamps for audio data were obtained simultaneously and separately via onRecordAudioFrame callbacks.
• The call getExtensionProperty failed and returned an empty string.

API changes

Added

• enableMultiCamera
• startSecondaryCameraCapture
• stopSecondaryCameraCapture
• setHeadphoneEQParameters
• muteLocalAudioStreamEx
• muteAllRemoteAudioStreamsEx
• startRtmpStreamWithoutTranscodingEx
• startRtmpStreamWithTranscodingEx
• updateRtmpTranscodingEx
• stopRtmpStreamEx
• startChannelMediaRelayEx
• updateChannelMediaRelayEx
• pauseAllChannelMediaRelayEx
• resumeAllChannelMediaRelayEx
• stopChannelMediaRelayEx
• followEncodeDimensionRatio in AgoraCameraCapturerConfiguration
• leaveChannelEx [2/2]
• newRoleOptions in didClientRoleChanged
• adjustUserPlaybackSignalVolumeEx
• enableAudioVolumeIndicationEx

Deprecated

• didApiCallExecute. Use the callbacks triggered by specific methods instead.

Deleted

• Removes deprecated member parameters backgroundImage and watermark in AgoraLiveTranscoding class.
• Removes AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8) in didReceiveChannelMediaRelayEvent.

v4.0.1

v4.0.1 was released on September 29, 2022.

Compatibility changes

1. To improve code usability, this release changes the parameters in optional type in the following classes to basic data types such as bool and int:

• isAgoraSource and isLiveSource in AgoraMediaSource is changed from optional to bool.
• All parameter types in AgoraRtcChannelMediaOptions are changed from optional to bool or int.

New features

1. In-ear monitoring

This release adds getEarMonitoringAudioParams callback to set the audio data format of the in-ear monitoring. You can use your own audio effect processing module to pre-process the audio frame data of the in-ear monitoring to implement custom audio effects. After calling setAudioFrameDelegate to register the audio observer, set the audio data format in the return value of the getEarMonitoringAudioParams callback. The SDK calculates the sampling interval based on the return value of the callback, and triggers the onEarMonitoringAudioFrame callback based on the sampling interval.

2. Local network connection types

To make it easier for users to know the connection type of the local network at any stage, this release adds the getNetworkType method. You can use this method to get the type of network connection in use, including UNKNOWN, DISCONNECTED, LAN, WIFI, 2G, 3G, 4G, 5G. When the local network connection type changes, the SDK triggers the networkTypeChangedToType callback to report the current network connection type.

3. Audio stream filter

This release introduces filtering audio streams based on volume. Once this function is enabled, the Agora server ranks all audio streams by volume and transports 3 audio streams with the highest volumes to the receivers by default. The number of audio streams to be transported can be adjusted; you can contact support@agora.io to adjust this number according to your use-case.

Meanwhile, Agora supports publishers to choose whether or not the audio streams being published are to be filtered based on volume. Streams that are not filtered will bypass this filter mechanism and transported directly to the receivers. In use-cases where there are a number of publishers, enabling this function helps reducing the bandwidth and device system pressure for the receivers.

To enable this function, contact support@agora.io.

4. Spatial audio effect

This release adds the following features applicable to spatial audio effect use-cases, which can effectively enhance the user's sense of presence experience in virtual interactive use-cases.

• Sound insulation area: You can set a sound insulation area and sound attenuation parameter by calling setZones. When the sound source (which can be a user or the media player) and the listener belong to the inside and outside of the sound insulation area, the listener experiences an attenuation effect similar to that of the sound in the real environment when it encounters a building partition. You can also set the sound attenuation parameter for the media player and the user, respectively, by calling setPlayerAttenuation and setRemoteAudioAttenuation, and specify whether to use that setting to force an override of the sound attenuation parameter in setZones.
• Doppler sound: You can enable Doppler sound by setting the enable_doppler parameter in SpatialAudioParams, and the receiver experiences noticeable tonal changes in the event of a high-speed relative displacement between the source and receiver (such as in a racing game use-case).
• Headphone equalizer: You can use a preset headphone equalization effect by calling the setHeadphoneEQPreset method to improve the hearing of the headphones.

API changes

Added

• getEarMonitoringAudioParams

• getNetworkType

• isAudioFilterable in the ChannelMediaOptions

• setZones

• setPlayerAttenuation

• setRemoteAudioAttenuation

• muteRemoteAudioStream

• SpatialAudioParams

• setHeadphoneEQPreset

• AgoraHeadphoneEQPreset

Deprecated

• startEchoTest [2/3]

v4.0.0

v4.0.0 was released on September 15, 2022.

Compatibility changes

1. Integration change

This release has optimized the implementation of some features, resulting in incompatibility with v3.7.x. The following are the main features with compatibility changes:

• Multiple channel
• Media stream publishing control
• Custom video capture and rendering (Media IO)
• Warning codes

After upgrading the SDK, you need to update the code in your app according to your business use-cases. For details, see Migrate from v3.7.x to v4.0.0.

New features

1. Multiple media tracks

This release supports one AgoraRtcEngineKit instance to collect multiple audio and video sources at the same time and publish them to the remote users by setting AgoraRtcEngineKit(Ex) and AgoraRtcChannelMediaOptions.

• After calling joinChannelByToken to join the first channel, call joinChannelExByToken multiple times to join multiple channels, and publish the specified stream to different channels through different user ID (localUid) and AgoraRtcChannelMediaOptions settings.

You can also experience the following features with the multi-channel capability:

• Publish multiple sets of audio streams to the remote users through different user IDs (uid).
• Mix multiple audio streams and publish to the remote users through a user ID (uid).

3. Agora media player

To make it easier for users to integrate the Agora SDK and reduce the SDK's package size, this release introduces the Agora media player. After calling the createMediaPlayerWithDelegate method to create a media player object, you can then call the methods in the AgoraRtcMediaPlayerProtocol class to experience a series of functions, such as playing local and online media files, preloading a media file, changing the CDN route for playing according to your network conditions, or sharing the audio and video streams being played with remote users.

4. Brand-new AI Noise Suppression

The SDK supports a new version of AI noise reduction (in comparison to the basic AI noise reduction in v3.7.x). The new AI noise reduction has better vocal fidelity, cleaner noise suppression, and adds a dereverberation option. To experience this feature, contact support@agora.io. The SDK supports a new version of Noise Suppression (in comparison to the basic Noise Suppression in v3.7.0). The new AI Noise Suppression has better vocal fidelity, cleaner noise suppression, and adds a dereverberation option. To experience this feature, contact support@agora.io.

5. Ultra-high audio quality

To make the audio clearer and restore more details, this release adds the AgoraVoiceBeautifierUltraHighQuality enumeration. In use-cases that mainly feature the human voice, such as chat or singing, you can call setVoiceBeautifierPreset and use this enumeration to experience ultra-high audio quality.

6. Spatial audio

This feature is in experimental status. To enable this feature, contact support@agora.io. Contact Technical Support if needed.

You can set the spatial audio for the remote user as following:

• Local Cartesian Coordinate System Calculation: This solution uses the AgoraLocalSpatialAudioKit class to implement spatial audio by calculating the spatial coordinates of the remote user. You need to call updateSelfPosition and updateRemotePosition to update the spatial coordinates of the local and remote users, respectively, so that the local user can hear the spatial audio effect of the remote user.

You can also set the spatial audio for the media player as following:

• Local Cartesian Coordinate System Calculation: This solution uses the AgoraLocalSpatialAudioKit class to implement spatial audio. You need to call updateSelfPosition and updatePlayerPositionInfo to update the spatial coordinates of the local user and media player, respectively, so that the local user can hear the spatial audio effect of media player.

7. Real-time chorus

This release gives real-time chorus the following abilities:

• Two or more choruses are supported.
• Each singer is independent of each other. If one singer fails or quits the chorus, the other singers can continue to sing.
• Very low latency experience. Each singer can hear each other in real time, and the audience can also hear each singer in real time.

This release adds the AgoraAudioScenarioChorus enumeration in AgoraAudioScenario. With this enumeration, users can experience ultra-low latency in real-time chorus when the network conditions are good.

8. Extensions from the Agora extensions marketplace

In order to enhance the real-time audio and video interactive activities based on the Agora SDK, this release supports the one-stop solution for the extensions from the Agora extensions marketplace:

• Easy to integrate: The integration of modular functions can be achieved simply by calling an API, and the integration efficiency is improved by nearly 95%.
• Extensibility design: The modular and extensible SDK design style endows the Agora SDK with good extensibility, which enables developers to quickly build real-time interactive apps based on the Agora extensions marketplace ecosystem.
• Build an ecosystem: A community of real-time audio and video apps has developed that can accommodate a wide range of developers, offering a variety of extension combinations. After integrating the extensions, developers can build richer real-time interactive functions. For details, see Use an Extension.
• Become a vendor: Vendors can integrate their products with Agora SDK in the form of extensions, display and publish them in the Agora extensions marketplace, and build a real-time interactive ecosystem for developers together with Agora. For details on how to develop and publish extensions, see Become a Vendor.

9. Enhanced channel management

To meet the channel management requirements of various business use-cases, this release adds the following functions to the AgoraRtcChannelMediaOptions structure:

• Sets or switches the publishing of multiple audio sources.
• Sets or switches channel profile and user role.
• Controls audio publishing delay.

Set AgoraRtcChannelMediaOptions when calling joinChannelByToken or joinChannelExByToken to specify the publishing and subscription behavior of a media stream, for example, whether to subscribe to the audio and video streams of remote users. After joining the channel, call updateChannelWithMediaOptions to update the settings in AgoraRtcChannelMediaOptions at any time, for example, to switch the published audio sources.

11. Subscription allowlists and blocklists

This release introduces subscription allowlists and blocklists for remote audio streams. You can add a user ID that you want to subscribe to in your allowlist, or add a user ID for the streams you do not wish to see to your blocklists. You can experience this feature through the following APIs, and in use-cases that involve multiple channels, you can call the following methods in the AgoraRtcEngineKit(Ex) interface:

• setSubscribeAudioBlacklist：Set the audio subscription blocklist.
• setSubscribeAudioWhitelist：Set the audio subscription allowlist.

If a user is added in a blocklist and a allowlist at the same time, only the blocklist takes effect.

12. Set audio scenarios

To make it easier to change audio scenarios, this release adds the setAudioScenario method. For example, if you want to change the audio scenario from AgoraAudioScenarioDefault to AgoraAudioScenarioGameStreaming when you are in a channel, you can call this method.

Improvements

1. Fast channel switching

This release can achieve the same switching speed as switchChannelByToken in v3.7.x through the leaveChannel and joinChannelByToken methods so that you don't need to take the time to call the switchChannelByToken method.

2. Voice pitch of the local user This release adds voicePitch in AgoraRtcAudioVolumeInfo of reportAudioVolumeIndicationOfSpeakers. You can use voicePitch to get the local user's voice pitch and perform business functions such as rating for singing.

Notifications

2022.10

• After you enable Notifications, your server receives the events that you subscribe to in the form of HTTPS requests.
• To improve communication security between the Notifications and your server, Agora SDRTN® uses signatures for identity verification.
• As of this release, you can use Notifications in conjunction with this product.

Known issues

The list of known issues page is continuously updated as the systems evolve. Agora suggests you regularly upgrade to the latest version of the SDK, which includes new features, bug fixes and improvements.

• MacOS SDK v4.4.0

  MacOS 15 Sequoia beta system issue

  When the app path (including the App name) contains non-English characters (such as Chinese characters), the compiled Metal shader library may not contain any methods, causing the app to crash. See this article for the workaround.

v4.6.2

Released on January 19, 2026.

Improvements

This release includes the following enhancements:

• Seamless switching for sound effect files

  Adds support for seamless switching of sound effect files. For the same sound effect file, if you call preloadEffect followed by playEffect, the SDK does not close the file after playback completes or when stopEffect is called. When you call playEffect again, the SDK reuses the loaded file to enable loop playback and seamless switching. This feature also works in multi-channel scenarios.

• Improved accuracy of network quality evaluation

  Improves the accuracy of network quality evaluation in the networkQuality callback, making the reported data better reflect the user's perceived experience.

• Support for 24kHz sampling rate for audio playback

  Adds support for audio data with a sample rate of 24000 Hz in onPlaybackAudioFrame. When calling setPlaybackAudioFrameParameters to set the playback audio format, you can set sampleRate to 24000.

• Additional improvements

  • Adds error codes AgoraErrorCodePcmSendFormat (200) and AgoraErrorCodePcmSendBufferOverflow (201) to report PCM data transmission errors.

Compatibility changes

This release introduces the following compatibility changes:

• Decoder plugins built into the SDK

  The relevant decoder plugins are now built into the SDK to ensure overall decoding compatibility.

v4.6.0

Released on August 26, 2025.

Compatibility changes

This version includes SDK behavior changes, API deprecations, and deletions. To ensure your app functions correctly, update your code after upgrading to this version.

For details on deprecated and deleted APIs in each version, see the API Sunset Notice.

• Deprecation of direct CDN streaming APIs

  Deprecates the APIs related to direct CDN streaming, which will be removed in a future release. Agora recommends using Media Push instead.

  • setDirectCdnStreamingAudioConfiguration:
  • setDirectCdnStreamingVideoConfiguration:
  • startDirectCdnStreaming:publishUrl:mediaOptions:
  • stopDirectCdnStreaming
  • rtcEngine:didDirectCdnStreamingStateChanged:reason:message:
  • AgoraDirectCdnStreamingMediaOptions
  • AgoraDirectCdnStreamingStats
  • AgoraDirectCdnStreamingState
  • AgoraDirectCdnStreamingReason

• Deprecation of virtual metronome APIs

  Deprecates the APIs for the virtual metronome feature, which will be removed in a future release.

  • startRhythmPlayer:sound2:config:
  • configRhythmPlayer:
  • rtcEngine:didRhythmPlayerStateChanged:reason:

• Deletion of redundant APIs

  Removed the following redundant APIs and parameters:

  • setLocalPublishFallbackOption:
  • rtcEngine:didLocalPublishFallbackToAudioOnly:
  • downlinkNetworkInfoUpdate
  • wlAccStats
  • AgoraWlAccReason
  • AgoraWlAccAction
  • rtcEngine:wlAccStats:averageStats:
  • rtcEngine:wlAccMessage:action:wlAccMsg:
  • enableWirelessAccelerate
  • receivedFrameRate (removed from AgoraRtcRemoteVideoStats)

• Changes to int UID and string UID mapping

  • Before v4.6.0: If registerLocalUserAccountWithAppID:userAccount: was used to register a string UID (for example, "aa") and obtain an int UID (for example, 123), joining a channel later with the int UID automatically mapped it to the original string UID ("aa").
  • From v4.6.0: The SDK no longer automatically maps an int UID to the original string UID. If registerLocalUserAccountWithAppID:userAccount: was called to get an int UID but the channel needs to be joined with the original string UID, call joinChannelByUserAccount:token:channelId:joinSuccess: directly with the string UID. After upgrading, review and update app logic to ensure users join the channel with the expected identity.

New features

• Multipath network transmission

  Introduced multipath transmission for devices with multiple network interfaces (for example, 5G, Wi-Fi, and LAN). This feature effectively reduces or eliminates experience degradation caused by poor network conditions, making it suitable for real-time audio and video communication scenarios that demand high transmission stability, such as in-vehicle systems, IoT, trains, and highways. Enable it by setting enableMultipath in AgoraRtcChannelMediaOptions to YES.

  • Dynamic mode: Dynamically selects the optimal path based on network conditions. Optionally set preferMultipathType to prioritize a path type. If not set, all path types have the same default weight.
  • Duplicate mode: Sends data simultaneously over all available paths for maximum stability. This mode incurs additional costs and eliminates the impact of poor network conditions.

  Configure uplink and downlink modes separately with uplinkMultipathMode and downlinkMultipathMode. Monitor performance with the rtcEngine:didMultipathStatsChanged: callback, which reports real-time transmission statistics for each path, including data consumption. Contact support@agora.io to enable duplicate mode.

• Asynchronous engine destruction

  Added the destroy: method, supporting synchronous or asynchronous engine destruction. In asynchronous mode, the SDK triggers the engineReleasedBlock callback.

• Token renewal result callback

  Added the rtcEngine:didRenewTokenResult: callback and RENEW_TOKEN_ERROR_CODE to report the result of renewToken:. This allows developers to handle Token renewal failures promptly within the callback.

• Other new features

  • Added setPlaybackAudioFrameBeforeMixingParameters: to configure the format of raw audio frames returned in onPlaybackAudioFrameBeforeMixing:channelId:uid:, including sample rate, number of channels, and the number of samples per callback.
  • Added preloadEffectEx:soundId: to preload audio effects into a specific channel. Supports both local and online audio files, enabling faster playback later and is suitable for multi-channel scenarios.
  • Added playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:startPos: for advanced audio effect playback in a specific channel with parameters such as loop count, pitch, spatial position, volume, whether to publish to the channel, and the starting playback position.

Improvements

• Added support for G.711 and G.722 audio codecs when interoperating with the Web SDK for improved cross-platform audio compatibility and clarity.

Fixed issues

This version fixes the following issues:

• Online audio effect playback restarted from the beginning when seekToPosition: was called.
• Occasional echoes in media volume mode when publishing a microphone stream while simultaneously playing effects with playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: and music with startAudioMixing:loopback:cycle:startPos:.
• Missing media metadata observer callback in cases where setMediaMetadataDelegate:withType: was called after setExternalVideoSource:useTexture:sourceType:.
• Occasional crashes.
• Media relay occasionally reported AgoraChannelMediaRelayStateFailure and AgoraChannelMediaRelayErrorServerErrorResponse after the following sequence: join, relay, unpublish, leave, rejoin, and start relay again.

v4.5.2

v4.5.2 was released on April 22, 2025.

Issues fixed

This release fixes the following issues:

• While playing a multi-track media file, noise was heard when adjusting the audio pitch using setAudioPitch.
• When the host called createCustomAudioTrack:config: to create a custom audio track with trackType set to AUDIO_TRACK_DIRECT, then called pushExternalAudioFrameRawData:samples:sampleRate:channels:trackId:timestamp: to push custom audio frames to a channel, and finally called playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos: to play an audio effect, audience members in the channel heard noise.
• Apps using the SDK occasionally experienced UI lag caused by main thread blocking during audio and video interactions.
• Calling openWithMediaSource: and setting isLiveSource to YES in the source parameter to play a video stream caused playback failure.
• When the sender transmitted multi-channel encoded audio, noise was occasionally heard by the receiver.
• When the app integrated a media player and called open twice to load different media resources consecutively, the second call incorrectly triggered the AgoraRtcMediaPlayer:infoUpdated: callback with information from the first media resource.
• After enabling user volume indication with enableAudioVolumeIndication:smooth:reportVad:, the rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume: callback reported a local user volume of 0 for both local and remote users.
• When you called enableVideoImageSource:options: to enable the video image source feature, the sender streamed successfully but the rtcEngine:didVideoPublishStateChange:sourceType:oldState:newState:elapseSinceLastState: callback occasionally did not return the expected result.
• In multi-channel scenarios, if the app called setupRemoteVideoEx:connection: to initialize the remote user's view before successfully calling joinChannelExByToken:connection:delegate:mediaOptions:, the view failed to display correctly.

v4.5.1

v4.5.1 was released on March 6, 2025.

New Features

1. AI Conversation Scenario

   This version introduces the AgoraAudioScenarioAiClient audio scenario, specifically designed for interacting with the conversational AI agent created by Conversational AI Engine. This scenario optimizes the audio transmission algorithm based on the characteristics of AI-generated voices, ensuring stable voice data transmission even in weak network conditions with up to 80% packet loss. The optimization enhances conversation continuity and reliability, adapting to various challenging network environments.

Issues Fixed

This release resolves the following issues:

• When using the pause method to pause playback, then calling seekToPosition: to move to a specific position, and finally calling play, the Media Player resumed from the paused position instead of the specified position.
• When using the Media Player, the file path of the media resource returned by getPlaySrc did not update after calling switchSrc:syncPts: to switch to a new media resource.
• In interactive live streaming scenarios, after joining a channel as an audience member using a string user ID, audio occasionally became unsynchronized with video.
• AI noise suppression and AI echo cancellation plugins sometimes failed when used together.

v4.5.0

v4.5.0 was released on November 27, 2024.

Compatibility changes

This version includes optimizations to some features, including changes to SDK behavior and API renaming and deletion. To ensure normal operation of the project, update the code in the app after upgrading to this release.

1. Automatic installation of virtual sound card

   Starting from this version, the SDK supports the automatic installation of a virtual sound card. When you call enableLoopbackRecording:deviceName: for the first time, the SDK will automatically install the AgoraALD, a virtual sound card developed by Agora. Once the installation is successful, the audio routing will automatically switch to the virtual sound card, and the virtual sound card will be used for audio capture.

New features

1. Local audio mixing

   This version introduces the local audio mixing feature. You can call the startLocalAudioMixer method to mix the audio streams from the local microphone, media player, sound card, and remote audio streams into a single audio stream, which can then be published to the channel. When you no longer need audio mixing, you can call the stopLocalAudioMixer method to stop local audio mixing. During the mixing process, you can call the updateLocalAudioMixerConfiguration method to update the configuration of the audio streams being mixed.

   Example use cases for this feature include:

   • When using the local video mixing feature, the associated audio streams of the mixed video streams can be simultaneously captured and published.
   • In live streaming use-cases, users can receive audio streams within the channel, mix multiple audio streams locally, and then forward the mixed audio stream to other channels.
   • In educational use-cases, teachers can mix the audio from interactions with students locally and then forward the mixed audio stream to other channels.

2. Others

   • The rtcEngine:device:type:stateChanged: callback supports reporting that the device has been plugged in.

Improvements

1. Custom audio capture improvements

   This version adds the enableAudioProcessing member parameter to AgoraAudioTrackConfig, which is used to control whether to enable 3A audio processing for custom audio capture tracks of the AUDIO_TRACK_DIRECT type. The default value of this parameter is NO, meaning that audio processing is not enabled. Users can enable it as needed, enhancing the flexibility of custom audio processing.

2. Other improvements

   • This version optimizes the logic for calling queryDeviceScore to obtain device score levels, improving the accuracy of the score results.
   • When calling switchSrc:syncPts: to switch between live streams or on-demand streams of different resolutions, smooth and seamless switching can be achieved. An automatic retry mechanism has been added in case of switching failures. The SDK will automatically retry 3 times after a failure. If it still fails, the AgoraRtcMediaPlayer:didOccurEvent:elapsedTime:message: callback will report the AgoraMediaPlayerEventSwitchError event, indicating that an error occurred during media resource switching.
   • When calling setPlaybackSpeed: to set the playback speed of an audio file, the minimum supported speed is 0.3x.

Bug fixes

This version fixes the following issue:

• Calling startAudioMixing:loopback:cycle: and then immediately calling pauseAudioMixing to pause the music file playback does not take effect.

v4.4.0

v4.4.0 was released on August 5, 2024.

Compatibility changes

This version includes optimizations to some features, including changes to SDK behavior and API renaming and deletion. To ensure normal operation of the project, update the code in the app after upgrading to this release.

1. To distinguish context information in different extension callbacks, this version removes the original extension callbacks and adds corresponding callbacks that contain context information (see table below). You can identify the extension name, the user ID, and the service provider name through AgoraExtensionContext in each callback.

   Original callback	New callback
   onEvent	onExtensionEventWithContext
   onExtensionStarted	onExtensionStartedWithContext
   onExtensionStopped	onExtensionStoppedWithContext
   onExtensionError	onExtensionErrorWithContext

2. This version renames the receiveMetadata callback to didMetadataReceived and removes the data and timeStamp parameters. You can get metadata-related information, including timeStamp (timestamp of the sent data), uid (user ID), and channelId (channel name) through the newly-added metadata parameter.

New features

1. Voice AI tuner

   This version introduces the voice AI tuner feature, which can enhance the sound quality and tone, similar to a physical sound card. You can enable the voice AI tuner feature by calling the enableVoiceAITuner method and passing in the sound effect types supported in the AgoraVoiceAITunerType enum to achieve effects like deep voice, cute voice, husky singing voice, and so on.

Improvements

This version includes the following improvements:

• Optimizes transmission strategy: Calling enableInstantMediaRendering no longer impacts the security of the transmission link.
• Deprecates redundant enumeration values AgoraClientRoleChangeFailedRequestTimeout and AgoraClientRoleChangeFailedConnectionFailed in AgoraClientRoleChangeFailedReason.

v4.3.2

v4.3.2 was released on June 4, 2024.

Improvements

This release enhances the usability of the setRemoteSubscribeFallbackOption method by removing the timing requirements for invocation. It can now be called both before and after joining the channel to dynamically switch audio and video stream fallback options in weak network conditions.

Issues fixed

This version fixed the following issues:

• Occasional video smoothness issues during audio and video interactions.
• The app occasionally crashed when remote users left the channel.

v4.3.1

v4.3.1 was released on April 29, 2024.

New Features

1. Data stream encryption

   This version adds datastreamEncryptionEnabled to AgoraEncryptionConfig for enabling data stream encryption. You can set this when you activate encryption with enableEncryption. If there are issues causing failures in data stream encryption or decryption, these can be identified by the newly added ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE and ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE enumerations.

2. Other features

   • A new method enableEncryptionEx is added for enabling media stream or data stream encryption in multi-channel use-cases.
   • A new method setAudioMixingPlaybackSpeed is introduced for setting the playback speed of audio files.
   • A new method getCallIdEx is introduced for retrieving call IDs in multi-channel use-cases.

3. Beta features

   • Speech driven avatar is released in beta. See beta documentation for details.

Improvements

1. Audio device type detection

   This version adds the deviceTypeName member to AgoraRtcDeviceInfo, used to identify the type of audio devices, such as built-in, USB, HDMI, etc.

2. Custom audio capture optimization

   To enhance the flexibility of custom audio capture, this release deprecates pushExternalAudioFrameSampleBuffer [1/2] and introduces pushExternalAudioFrameSampleBuffer [2/2]. Compared to the deprecated method, the new method adds parameters such as sampleRate, channels, and trackId. These support pushing external CMSampleBuffer audio data to the channel via custom audio tracks, and allow for the setting of sample rates and channel counts for external audio sources.

3. CPU consumption reduction of in-ear monitoring

   This release adds an enumerator AgoraEarMonitoringFilterReusePostProcessingFilter in AgoraEarMonitoringFilterType. For complex audio processing use-cases, you can specify this option to reuse the audio filter after sender-side processing in in-ear monitoring, thereby reducing CPU consumption. Note that this option may increase the latency of in-ear monitoring, which is suitable for latency-tolerant use-cases requiring low CPU consumption.

4. Other improvements

   This version also includes the following improvements:

   • In AgoraAudioEffectPreset, a new enumeration AgoraAudioEffectPresetRoomAcousticsChorus (chorus effect) is added, enhancing the spatial presence of vocals in chorus use-cases.
   • In AgoraRtcRemoteAudioStats, a new e2eDelay field is added to report the delay from when the audio is captured on the sending end to when the audio is played on the receiving end.

Issues fixed

This version fixed the following issues:

• When a user plugged and unplugged a Bluetooth or wired headset once, the audio state change callback stateChanged was triggered multiple times.

API changes

Added

• setFaceInfoDelegate
• AgoraFaceInfoDelegate
• onFaceInfo
• AgoraMediaSourceType adds AgoraMediaSourceTypeSpeechDriven
• AgoraEncryptionConfig adds datastreamEncryptionEnabled
• AgoraEncryptionErrorType adds the following enumerations:
  • ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE
  • ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE
• AgoraRtcDeviceInfo adds deviceTypeName
• AgoraRtcRemoteAudioStats adds e2eDelay
• AgoraErrorCode adds AgoraErrorCodeDatastreamDecryptionFailed
• AgoraAudioEffectPreset adds AgoraAudioEffectPresetRoomAcousticsChorus, enhancing the spatial presence of vocals in chorus use-cases.
• getCallIdEx
• enableEncryptionEx
• setAudioMixingPlaybackSpeed
• AgoraEarMonitoringFilterType adds a new enumeration AgoraEarMonitoringFilterBuiltInAudioFilters
• pushExternalAudioFrameSampleBuffer [2/2]

Deprecated

• pushExternalAudioFrameSampleBuffer

v4.3.0

v4.3.0 was released on February 22, 2024.

Compatibility changes

This release has optimized the implementation of some functions, involving renaming or deletion of some APIs. To ensure the normal operation of the project, you need to update the code in the app after upgrading to this release.

1. Renaming parameters in callbacks

   In order to make the parameters in some callbacks and the naming of enumerations in enumeration classes easier to understand, the following modifications have been made in this release. Please modify the parameter settings in the callbacks after upgrading to this release.

   Callback	Original parameter name	New parameter name
   localAudioStateChanged	error	reason
   localVideoStateChanged	error	reason
   onDirectCdnStreamingStateChanged	error	reason
   didChangedToState	error	reason
   rtmpStreamingChangedToState	errCode	reason

   Original enumeration class	New enumeration class
   AgoraAudioLocalError	AgoraAudioLocalReason
   AgoraLocalVideoStreamError	AgoraLocalVideoStreamReason
   AgoraDirectCdnStreamingError	AgoraDirectCdnStreamingReason
   AgoraMediaPlayerError	AgoraMediaPlayerReason
   AgoraRtmpStreamingError	AgoraRtmpStreamingReason

   Note: For specific renaming of enumerations, please refer to API changes.

2. Channel media relay

   To improve interface usability, this release removes some methods and callbacks for channel media relay. Use the alternative options listed in the table below:

   Deleted methods and callbacks	Alternative methods and callbacks
   startChannelMediaRelay updateChannelMediaRelay	startOrUpdateChannelMediaRelay
   startChannelMediaRelayEx updateChannelMediaRelayEx	startOrUpdateChannelMediaRelayEx
   didReceiveChannelMediaRelayEvent	channelMediaRelayStateDidChange

3. Audio loopback capturing

   • Before v4.3.0, if you call the disableAudio method to disable the audio module, audio loopback capturing will not be disabled.
   • As of v4.3.0, if you call the disableAudio method to disable the audio module, audio loopback capturing will be disabled as well. If you need to enable audio loopback capturing, you need to enable the audio module by calling the enableAudio method and then call enableLoopbackRecording.

4. Log encryption behavior changes

   For security and performance reasons, as of this release, the SDK encrypts logs and no longer supports printing plaintext logs via the console.

   Refer to the following solutions for different needs:

   • If you need to know the API call status, please check the API logs and print the SDK callback logs yourself.
   • For any other special requirements, please contact technical support and provide the corresponding encrypted logs.

New features

1. Query device score

   This release adds the queryDeviceScore method to query the device's score level to ensure that the user-set parameters do not exceed the device's capabilities. For example, in HD or UHD video use-cases, you can first call this method to query the device's score. If the returned score is low (for example, below 60), you need to lower the video resolution to avoid affecting the video experience. The minimum device score required for different business use-cases is varied. For specific score recommendations, please contact technical support.

2. Select different audio tracks for local playback and streaming

   This release introduces the selectMultiAudioTrack method that allows you to select different audio tracks for local playback and streaming to remote users. For example, in use-cases like online karaoke, the host can choose to play the original sound locally and publish the accompaniment in the channel. Before using this function, you need to open the media file through the openWithMediaSource method and enable this function by setting the enableMultiAudioTrack parameter in AgoraMediaSource.

3. Others

   This release has passed the test verification of the following APIs and can be applied to the entire series of RTC 4.x SDK.

   • setRemoteSubscribeFallbackOption: Sets fallback option for the subscribed video stream in weak network conditions.
   • didRemoteSubscribeFallbackToAudioOnly: Occurs when the subscribed video stream falls back to audio-only stream due to weak network conditions or switches back to the video stream after the network conditions improve.
   • [setPlayerOption 1/2] and [setPlayerOption 2/2]: Sets media player options for providing technical previews or special customization features.
   • enableCustomAudioLocalPlayback: Sets whether to enable the local playback of external audio source.

Improvements

1. SDK task processing scheduling optimization

   This release optimizes the scheduling mechanism for internal tasks within the SDK, with improvements in the following aspects:

   • The speed of video rendering and audio playback for both remote and local first frames improves by 10% to 20%.
   • The API call duration and response time are reduced by 5% to 50%.
   • The SDK's parallel processing capability significantly improves, delivering higher video quality (720P, 24 fps) even on lower-end devices. Additionally, image processing remains more stable in use-cases involving high resolutions and frame rates.
   • The stability of the SDK is further enhanced, leading to a noticeable decrease in the crash rate across various specific use-cases.

2. In-ear monitoring volume boost

   This release provides users with more flexible in-ear monitoring audio adjustment options, supporting the ability to set the in-ear monitoring volume to four times the original volume by calling setInEarMonitoringVolume.

3. Spatial audio effects usability improvement

   • This release optimizes the design of the setZones method, supporting the ability to set the zones parameter to NULL, indicating the clearing of all echo cancellation zones.
   • As of this release, it is no longer necessary to unsubscribe from the audio streams of all remote users within the channel before calling methods in AgoraLocalSpatialAudioKit.

4. Local audio state changed callback optimization

   This release introduces the following enumerations in AgoraAudioLocalReason, enabling users to obtain more details about local audio errors through the localAudioStateChanged callback:

   • AgoraAudioLocalReasonNoRecordingDevice: No recording device is available. Remind your users to check whether the microphone is connected to the device properly in the control plane of the device or if the microphone is working properly.
   • AgoraAudioLocalReasonNoPlayoutDevice: No playback device is available. Remind your users to check whether the speaker is connected to the device properly in the control plane of the device or if the speaker is working properly.

5. Other Improvements

   This release also includes the following improvements:

   • This release optimizes the SDK's domain name resolution strategy, improving the stability of calling to resolve domain names in complex network environments.
   • When passing in an image with transparent background as the virtual background image, the transparent background can be filled with customized color.
   • This release adds the earMonitorDelay and aecEstimatedDelay members in AgoraRtcLocalAudioStats to report ear monitor delay and acoustic echo cancellation (AEC) delay, respectively.
   • When using the sound card for recording, it supports capturing audio data in stereo.
   • The cacheStats callback is added to report the statistics of the media file being cached. This callback is triggered once per second after file caching is started.
   • The playbackStats callback is added to report the statistics of the media file being played. This callback is triggered once per second after the media file starts playing. You can obtain information like the audio and video bitrate of the media file.

API changes

Added

• The subviewUid member in AgoraRtcVideoCanvas
• The following enumerations in AgoraAudioLocalReason:
  • AgoraAudioLocalReasonNoRecordingDevice
  • AgoraAudioLocalReasonNoPlayoutDevice
• enableCustomAudioLocalPlayback
• queryDeviceScore
• The AgoraMediaSourceTypeCustomVideo enumeration in AgoraMediaSourceType
• The AgoraAudioOutputRoutingBluetoothDeviceA2dp enumeration in AgoraAudioOutputRouting
• Adds the earMonitorDelay and aecEstimatedDelay in AgoraRtcLocalAudioStats
• selectMultiAudioTrack
• cacheStats
• playbackStats

Modified

• All Error fields in the following enumerations are changed to Reason:
  • AgoraAudioLocalErrorOK
  • AgoraAudioLocalErrorFailure
  • AgoraAudioLocalErrorDeviceNoPermission
  • AgoraAudioLocalErrorDeviceBusy
  • AgoraAudioLocalErrorRecordFailure
  • AgoraAudioLocalErrorEncodeFailure
  • AgoraLocalVideoStreamErrorOK
  • AgoraLocalVideoStreamErrorFailure
  • AgoraLocalVideoStreamErrorDeviceNoPermission
  • AgoraLocalVideoStreamErrorDeviceBusy
  • AgoraLocalVideoStreamErrorCaptureFailure
  • AgoraLocalVideoStreamErrorCodecNotSupport
  • AgoraLocalVideoStreamErrorCaptureInBackGround
  • AgoraLocalVideoStreamErrorCaptureMultipleForegroundApps
  • AgoraLocalVideoStreamErrorCaptureNoDeviceFound
  • AgoraLocalVideoStreamErrorCaptureDeviceDisconnected
  • AgoraLocalVideoStreamErrorCaptureDeviceInvalidId
  • AgoraDirectCdnStreamingErrorOK
  • AgoraDirectCdnStreamingErrorFailed
  • AgoraDirectCdnStreamingErrorAudioPublication
  • AgoraDirectCdnStreamingErrorVideoPublication
  • AgoraDirectCdnStreamingErrorNetConnect
  • AgoraDirectCdnStreamingErrorBadName
  • AgoraMediaPlayerErrorNone
  • AgoraMediaPlayerErrorInvalidArguments
  • AgoraMediaPlayerErrorInternal
  • AgoraMediaPlayerErrorNoSource
  • AgoraMediaPlayerErrorInvalidMediaSource
  • AgoraMediaPlayerErrorUnknowStreamType
  • AgoraMediaPlayerErrorObjNotInitialized
  • AgoraMediaPlayerErrorCodecNotSupported
  • AgoraMediaPlayerErrorVideoRenderFailed
  • AgoraMediaPlayerErrorInvalidState
  • AgoraMediaPlayerErrorUrlNotFound
  • AgoraMediaPlayerErrorInvalidConnectState
  • AgoraMediaPlayerErrorSrcBufferUnderflow
  • AgoraMediaPlayerErrorInterrupted
  • AgoraMediaPlayerErrorNotSupported
  • AgoraMediaPlayerErrorTokenExpired
  • AgoraMediaPlayerErrorUnknown
  • AgoraRtmpStreamingErrorOK
  • AgoraRtmpStreamingErrorInvalidParameters
  • AgoraRtmpStreamingErrorEncryptedStreamNotAllowed
  • AgoraRtmpStreamingErrorConnectionTimeout
  • AgoraRtmpStreamingErrorInternalServerError
  • AgoraRtmpStreamingErrorRtmpServerError
  • AgoraRtmpStreamingErrorTooOften
  • AgoraRtmpStreamingErrorReachLimit
  • AgoraRtmpStreamingErrorNotAuthorized
  • AgoraRtmpStreamingErrorStreamNotFound
  • AgoraRtmpStreamingErrorFormatNotSupported
  • AgoraRtmpStreamingErrorNotBroadcaster
  • AgoraRtmpStreamingErrorTranscodingNoMixStream
  • AgoraRtmpStreamingErrorNetDown
  • AgoraRtmpStreamingErrorInvalidPrivilege
  • AgoraRtmpStreamingErrorUnpublishOK

Deleted

• startChannelMediaRelay
• updateChannelMediaRelay
• startChannelMediaRelayEx
• updateChannelMediaRelayEx
• didReceiveChannelMediaRelayEvent
• AgoraChannelMediaRelayEvent

v4.2.6

v4.2.6 was released on November 17, 2023.

Issues fixed

This release fixed the following issue:

• When using an iOS 16 or later device with Bluetooth headphones connected before joining the channel, the audio routing after joining the channel was not as expected: Audio was played from the speaker, not the Bluetooth headphones.

v4.2.3

v4.2.3 was released on October 11, 2023.

Improvements

Other Improvements

This release includes the following additional improvements:

• Optimizes the logic of handling invalid parameters. When you call the setPlaybackSpeed method to set the playback speed of audio files, if you pass an invalid parameter, the SDK returns the error code -2, which means that you need to reset the parameter.
• Optimizes the logic of Token parsing, in order to prevent an app from crash when an invalid token is passed in.

Issues fixed

This release fixed the following issues:

• Occasional crashes when joining a channel.
• Occasional failure of joining a channel when the local system time was not set correctly.
• When calling the playEffect [3/3] method to play two audio files using the same soundId, the first audio file was sometimes played repeatedly.

v4.2.2

v4.2.2 was released on july 27, 2023.

New features

1. Wildcard token

   This release introduces wildcard tokens. Agora supports setting the channel name used for generating a token as a wildcard character. The token generated can be used to join any channel if you use the same user id. In use-cases involving multiple channels, such as switching between different channels, using a wildcard token can avoid repeated application of tokens every time users joining a new channel, which reduces the pressure on your token server. See Deploy a token server.

   All 4.x SDKs support using wildcard tokens.

2. Preloading channels

   This release adds preloadChannelByToken[1/2] and preloadChannelByToken[2/2] methods, which allows a user whose role is set as audience to preload channels before joining one. Calling the method can help shortening the time of joining a channel, thus reducing the time it takes for audience members to hear the host.

   When preloading more than one channels, Agora recommends that you use a wildcard token for preloading to avoid repeated application of tokens every time you joining a new channel, thus saving the time for switching between channels. See Deploy a token server.

Improvements

1. Virtual Background Algorithm Upgrade

   This version has upgraded the portrait segmentation algorithm of the virtual background, which comprehensively improves the accuracy of portrait segmentation, the smoothness of the portrait edge with the virtual background, and the fit of the edge when the person moves. In addition, it optimizes the precision of the person's edge in use-cases such as meetings, offices, homes, and under backlight or weak light conditions.

2. Channel media relay

   The number of target channels for media relay has been increased to 6. When calling startOrUpdateChannelMediaRelay and startOrUpdateChannelMediaRelayEx, you can specify up to 6 target channels.

Issues fixed

This release fixed the following issues:

• Occasionally, noise occurred when the local user listened to their own and remote audio after joining the channel.
• Slow channel reconnection after the connection was interrupted due to network reasons.

API changes

Added

• preloadChannelByToken [1/2]
• preloadChannelByToken [2/2]
• updatePreloadChannelToken

v4.2.1

This version was released on June 21, 2023.

Improvements

This version improves the network transmission strategy, enhancing the smoothness of audio interactions.

Fixed Issues

This version fixed the following issues:

• Inability to join channels caused by SDK's incompatibility with some older versions of AccessToken.
• After the sending end called setAINSMode to activate AI noise reduction, occasional echo was observed by the receiving end.
• Brief noise occurred while playing media files using the media player.

v4.2.0

v4.2.0 was released on May 24, 2023.

Compatibility changes

If you use the features mentioned in this section, ensure that you modify the implementation of the relevant features after upgrading the SDK.

1. Channel media options

• publishCustomAudioTrackEnableAec in AgoraRtcChannelMediaOptions is deleted. Use publishCustomAudioTrack instead.
• publishCustomAudioSourceId in AgoraRtcChannelMediaOptions is renamed to publishCustomAudioTrackId.

2. Virtual sound card

As of v4.2.0, Agora supports third-party virtual sound cards. You can use a third-party virtual sound card as the audio input or output device for the SDK. You can use the stateChanged callback to see whether the current input or output device selected by the SDK is a virtual sound card.

3. Miscellaneous

• didApiCallExecute is deleted. Agora recommends getting the results of the API implementation through relevant channels and media callbacks.
• startChannelMediaRelay, updateChannelMediaRelay, startChannelMediaRelayEx, and updateChannelMediaRelayEx are deprecated. Use startOrUpdateChannelMediaRelay and startOrUpdateChannelMediaRelayEx instead.

New features

1. AI Noise Suppression

This release introduces public APIs for the AI Noise Suppression function. Once enabled, the SDK automatically detects and reduces background noises. Whether in bustling public venues or real-time competitive arenas that demand lightning-fast responsiveness, this function guarantees optimal audio clarity, providing users with an elevated audio experience. You can enable this function through the newly-introduced setAINSMode method and set the noise suppression mode as balance, aggressive, or low latency according to your use-case.

2. Cross-device synchronization

In real-time collaborative singing use-cases, network issues can cause inconsistencies in the downlinks of different client devices. To address this, this release introduces getNtpWallTimeInMs for obtaining the current Network Time Protocol (NTP) time. By using this method to synchronize lyrics and music across multiple client devices, users can achieve synchronized singing and lyrics progression, resulting in a better collaborative experience.

Improvements

1. Voice changer

This release introduces the setLocalVoiceFormant method that allows you to adjust the formant ratio to change the timbre of the voice. This method can be used together with the setLocalVoicePitch method to adjust the pitch and timbre of voice at the same time, enabling a wider range of voice transformation effects.

2. Channel media relay

This release introduces startOrUpdateChannelMediaRelay and startOrUpdateChannelMediaRelayEx, allowing for a simpler and smoother way to start and update media relay across channels. With these methods, developers can easily start the media relay across channels and update the target channels for media relay with a single method. Additionally, the internal interaction frequency has been optimized, effectively reducing latency in function calls.

3. Custom audio tracks

To better meet the needs of custom audio capture use-cases, this release adds createCustomAudioTrack and destroyCustomAudioTrack for creating and destroying custom audio tracks. Two types of audio tracks are also provided for users to choose from, further improving the flexibility of capturing external audio source:

• Mixable audio track: Supports mixing multiple external audio sources and publishing them to the same channel, suitable for multi-channel audio capture use-cases.
• Direct audio track: Only supports publishing one external audio source to a single channel, suitable for low-latency audio capture use-cases.

Issues fixed

This release fixed the following issues:

• When the host frequently switched the user role between broadcaster and audience in a short period of time, the audience members could not hear the audio of the host.
• Incorrect information in the type field of the return value after calling getDefaultAudioDevice.

API changes

Added

• startOrUpdateChannelMediaRelay
• startOrUpdateChannelMediaRelayEx
• getNtpWallTimeInMs
• setAINSMode
• createAudioCustomTrack
• destroyAudioCustomTrack
• AudioTrackConfig
• AgoraAudioTrackType
• The domainLimit and autoRegisterAgoraExtensions members in AgoraRtcEngineConfig
• The channelId and uid parameters in stateDidChanged and informationDidUpdated callbacks

Deprecated

• startChannelMediaRelay
• startChannelMediaRelayEx
• updateChannelMediaRelay
• updateChannelMediaRelayEx
• didReceiveChannelMediaRelayEvent
• AgoraChannelMediaRelayEvent

Deleted

• didApiCallExecute
• publishCustomAudioTrackEnableAec in AgoraRtcChannelMediaOptions

v4.1.1

v4.1.1 was released on February 8, 2023.

New features

Instant frame rendering

This release adds the enableInstantMediaRendering method to enable instant rendering mode for audio frames, which can speed up the first audio frame rendering after the user joins the channel.

Issues fixed

This release fixed the issue that playing audio files with a sample rate of 48 kHz failed.

API changes

Added

enableInstantMediaRendering

v4.1.0

v4.1.0 was released on December 15, 2022.

New features

1. Headphone equalization effect

This release adds the setHeadphoneEQParameters method, which is used to adjust the low- and high-frequency parameters of the headphone EQ. This mainly useful in spatial audio use-cases. If you cannot achieve the expected headphone EQ effect after calling setHeadphoneEQPreset, you can call setHeadphoneEQParameters to adjust the EQ.

2. MPUDP (MultiPath UDP) (Beta)

As of this release, the SDK supports MPUDP protocol, which enables you to connect and use multiple paths to maximize the use of channel resources based on the UDP protocol. You can use different physical NICs on both mobile and desktop and aggregate them to effectively combat network jitter and improve transmission quality.

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

3. Multi-channel management

This release adds a series of multi-channel related methods that you can call to manage audio streams in multi-channel use-cases.

• The muteLocalAudioStreamEx method is used to cancel or resume publishing a local audio stream, respectively.
• The muteAllRemoteAudioStreamsEx is used to cancel or resume the subscription of all remote users to audio streams, respectively.
• The startRtmpStreamWithoutTranscodingEx, startRtmpStreamWithTranscodingEx, updateRtmpTranscodingEx, and stopRtmpStreamEx methods are used to implement Media Push in multi-channel use-cases.
• The startChannelMediaRelayEx, updateChannelMediaRelayEx, pauseAllChannelMediaRelayEx, resumeAllChannelMediaRelayEx, and stopChannelMediaRelayEx methods are used to relay media streams across channels in multi-channel use-cases.
• Adds the leaveChannelEx [2/2] method. Compared with the leaveChannelEx [1/2] method, a new options parameter is added, which is used to choose whether to stop recording with the microphone when leaving a channel in a multi-channel use-case.

4. Client role switching

In order to enable users to know whether the switched user role is low-latency or ultra-low-latency, this release adds the newRoleOptions parameter to the didClientRoleChanged callback. The value of this parameter is as follows:

• AgoraAudienceLatencyLevelLowLatency (1): Low latency.
• AgoraAudienceLatencyLevelUltraLowLatency (2): Ultra-low latency.

Improvements

1. Relaying media streams across channels

This release optimizes the updateChannelMediaRelay method as follows:

• Before v4.1.0: If the target channel update fails due to internal reasons in the server, the SDK returns the error code AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8), and you need to call the updateChannelMediaRelay method again.
• v4.1.0 and later: If the target channel update fails due to internal server reasons, the SDK retries the update until the target channel update is successful.

2. Reconstructed AIAEC algorithm

This release reconstructs the AEC algorithm based on the AI method. Compared with the traditional AEC algorithm, the new algorithm can preserve the complete, clear, and smooth near-end vocals under poor echo-to-signal conditions, significantly improving the system's echo cancellation and dual-talk performance. This gives users a more comfortable call and live-broadcast experience. AIAEC is suitable for conference calls, chats, karaoke, and other use-cases.

Other improvements

This release includes the following additional improvements:

• Reduces the latency when pushing external audio sources.
• Improves the performance of echo cancellation when using the AgoraAudioScenarioMeeting scenario.
• Enhances the ability to identify different network protocol stacks and improves the SDK's access capabilities in multiple-operator network use-cases.

Issues fixed

This release fixed the following issues:

• After starting and stopping the audio capture device test, there was no sound when the audio playback device was subsequently started.
• Audience members heard buzzing noises when the host switched between speakers and earphones during live streaming.
• The call getExtensionProperty failed and returned an empty string.

API changes

Added

• setHeadphoneEQParameters
• muteLocalAudioStreamEx
• muteAllRemoteAudioStreamsEx
• startRtmpStreamWithoutTranscodingEx
• startRtmpStreamWithTranscodingEx
• updateRtmpTranscodingEx
• stopRtmpStreamEx
• startChannelMediaRelayEx
• updateChannelMediaRelayEx
• pauseAllChannelMediaRelayEx
• resumeAllChannelMediaRelayEx
• stopChannelMediaRelayEx
• followEncodeDimensionRatio in AgoraCameraCapturerConfiguration
• leaveChannelEx [2/2]
• newRoleOptions in didClientRoleChanged
• adjustUserPlaybackSignalVolumeEx
• enableAudioVolumeIndicationEx

Deprecated

• didApiCallExecute. Use the callbacks triggered by specific methods instead.

Deleted

• Removes deprecated member parameters backgroundImage and watermark in AgoraLiveTranscoding class.
• Removes AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8) in didReceiveChannelMediaRelayEvent callback.

v4.0.1

v4.0.1 was released on September 29, 2022.

Compatibility changes

To improve code usability, this release changes the parameters in optional type in the following classes to basic data types such as bool and int:

• isAgoraSource and isLiveSource in AgoraMediaSource is changed from optional to bool.
• All parameter types in AgoraRtcChannelMediaOptions are changed from optional to bool or int.

New features

1. In-ear monitoring

This release adds support for in-ear monitoring. You can call enableInEarMonitoring to enable the in-ear monitoring function.

After successfully enabling the in-ear monitoring function, you can call setAudioFrameDelegate to register the audio observer, and the SDK triggers the onEarMonitoringAudioFrame callback to report the audio frame data. You can use your own audio effect processing module to pre-process the audio frame data of the in-ear monitoring to implement custom audio effects. Agora recommends that you choose one of the following two methods to set the audio data format of the in-ear monitoring:

• Call the setEarMonitoringAudioFrameParametersWithSampleRate method to set the audio data format of in-ear monitoring. The SDK calculates the sampling interval based on the parameters in this method, and triggers the onEarMonitoringAudioFrame callback based on the sampling interval.
• Set the audio data format in the return value of the getEarMonitoringAudioParams callback. The SDK calculates the sampling interval based on the return value of the callback, and triggers the onEarMonitoringAudioFrame callback based on the sampling interval.

To adjust the in-ear monitoring volume, you can call setInEarMonitoringVolume.

2. Local network connection types

To make it easier for users to know the connection type of the local network at any stage, this release adds the getNetworkType method. You can use this method to get the type of network connection in use, including UNKNOWN, DISCONNECTED, LAN, WIFI, 2G, 3G, 4G, 5G. When the local network connection type changes, the SDK triggers the networkTypeChangedToType callback to report the current network connection type.

3. Audio stream filter

This release introduces filtering audio streams based on volume. Once this function is enabled, the Agora server ranks all audio streams by volume and transports 3 audio streams with the highest volumes to the receivers by default. The number of audio streams to be transported can be adjusted; you can contact support@agora.io to adjust this number according to your use-case.

Meanwhile, Agora supports publishers to choose whether or not the audio streams being published are to be filtered based on volume. Streams that are not filtered will bypass this filter mechanism and transported directly to the receivers. In use-cases where there are a number of publishers, enabling this function helps reducing the bandwidth and device system pressure for the receivers.

To enable this function, contact support@agora.io.

4. Spatial audio effect

This release adds the following features applicable to spatial audio effect use-cases, which can effectively enhance the user's sense of presence experience in virtual interactive use-cases.

• Sound insulation area: You can set a sound insulation area and sound attenuation parameter by calling setZones. When the sound source (which can be a user or the media player) and the listener belong to the inside and outside of the sound insulation area, the listener experiences an attenuation effect similar to that of the sound in the real environment when it encounters a building partition. You can also set the sound attenuation parameter for the media player and the user, respectively, by calling setPlayerAttenuation and setRemoteAudioAttenuation, and specify whether to use that setting to force an override of the sound attenuation parameter in setZones.
• Doppler sound: You can enable Doppler sound by setting the enable_doppler parameter in SpatialAudioParams, and the receiver experiences noticeable tonal changes in the event of a high-speed relative displacement between the source and receiver (such as in a racing game use-case).
• Headphone equalizer: You can use a preset headphone equalization effect by calling the setHeadphoneEQPreset method to improve the hearing of the headphones.

API changes

Added

• getEarMonitoringAudioParams

• getNetworkType

• isAudioFilterable in the ChannelMediaOptions

• setZones

• setPlayerAttenuation

• setRemoteAudioAttenuation

• muteRemoteAudioStream

• SpatialAudioParams

• setHeadphoneEQPreset

• AgoraHeadphoneEQPreset

Deprecated

• startEchoTest [2/3]

v4.0.0

v4.0.0 was released on September 15, 2022.

Compatibility changes

1. Integration change

This release has optimized the implementation of some features, resulting in incompatibility with v3.7.x. The following are the main features with compatibility changes:

• Multiple channel
• Media stream publishing control
• Custom video capture and rendering (Media IO)
• Warning codes

After upgrading the SDK, you need to update the code in your app according to your business use-cases. For details, see Migrate from v3.7.x to v4.0.0.

New features

1. Multiple media tracks

This release supports one AgoraRtcEngineKit instance to collect multiple audio and video sources at the same time and publish them to the remote users by setting AgoraRtcEngineKit(Ex) and AgoraRtcChannelMediaOptions.

• After calling joinChannelByToken to join the first channel, call joinChannelExByToken multiple times to join multiple channels, and publish the specified stream to different channels through different user ID (localUid) and AgoraRtcChannelMediaOptions settings.

You can also experience the following features with the multi-channel capability:

• Publish multiple sets of audio streams to the remote users through different user IDs (uid).
• Mix multiple audio streams and publish to the remote users through a user ID (uid).

3. Agora media player

To make it easier for users to integrate the Agora SDK and reduce the SDK's package size, this release introduces the Agora media player. After calling the createMediaPlayerWithDelegate method to create a media player object, you can then call the methods in the AgoraRtcMediaPlayerProtocol class to experience a series of functions, such as playing local and online media files, preloading a media file, changing the CDN route for playing according to your network conditions, or sharing the audio and video streams being played with remote users.

4. Brand-new AI Noise Suppression

The SDK supports a new version of AI noise reduction (in comparison to the basic AI noise reduction in v3.7.x). The new AI noise reduction has better vocal fidelity, cleaner noise suppression, and adds a dereverberation option. To experience this feature, contact support@agora.io.

5. Ultra-high audio quality

To make the audio clearer and restore more details, this release adds the AgoraVoiceBeautifierUltraHighQuality enumeration. In use-cases that mainly feature the human voice, such as chat or singing, you can call setVoiceBeautifierPreset and use this enumeration to experience ultra-high audio quality.

6. Spatial audio

This feature is in experimental status. To enable this feature, contact support@agora.io. Contact Technical Support if needed.

You can set the spatial audio for the remote user as following:

• Local Cartesian Coordinate System Calculation: This solution uses the AgoraLocalSpatialAudioKit class to implement spatial audio by calculating the spatial coordinates of the remote user. You need to call updateSelfPosition and updateRemotePosition to update the spatial coordinates of the local and remote users, respectively, so that the local user can hear the spatial audio effect of the remote user.

You can also set the spatial audio for the media player as following:

• Local Cartesian Coordinate System Calculation: This solution uses the AgoraLocalSpatialAudioKit class to implement spatial audio. You need to call updateSelfPosition and updatePlayerPositionInfo to update the spatial coordinates of the local user and media player, respectively, so that the local user can hear the spatial audio effect of media player.

7. Real-time chorus

This release gives real-time chorus the following abilities:

• Two or more choruses are supported.
• Each singer is independent of each other. If one singer fails or quits the chorus, the other singers can continue to sing.
• Very low latency experience. Each singer can hear each other in real time, and the audience can also hear each singer in real time.

This release adds the AgoraAudioScenarioChorus enumeration in AgoraAudioScenario. With this enumeration, users can experience ultra-low latency in real-time chorus when the network conditions are good.

8. Extensions from the Agora extensions marketplace

In order to enhance the real-time audio and video interactive activities based on the Agora SDK, this release supports the one-stop solution for the extensions from the Agora extensions marketplace:

• Easy to integrate: The integration of modular functions can be achieved simply by calling an API, and the integration efficiency is improved by nearly 95%.
• Extensibility design: The modular and extensible SDK design style endows the Agora SDK with good extensibility, which enables developers to quickly build real-time interactive apps based on the Agora extensions marketplace ecosystem.
• Build an ecosystem: A community of real-time audio and video apps has developed that can accommodate a wide range of developers, offering a variety of extension combinations. After integrating the extensions, developers can build richer real-time interactive functions. For details, see Use an Extension.
• Become a vendor: Vendors can integrate their products with Agora SDK in the form of extensions, display and publish them in the Agora extensions marketplace, and build a real-time interactive ecosystem for developers together with Agora. For details on how to develop and publish extensions, see Become a Vendor.

9. Enhanced channel management

To meet the channel management requirements of various business use-cases, this release adds the following functions to the AgoraRtcChannelMediaOptions structure:

• Sets or switches the publishing of multiple audio sources.
• Sets or switches channel profile and user role.
• Controls audio publishing delay.

Set AgoraRtcChannelMediaOptions when calling joinChannelByToken or joinChannelExByToken to specify the publishing and subscription behavior of a media stream, for example, whether to subscribe to the audio and video streams of remote users. After joining the channel, call updateChannelWithMediaOptions to update the settings in AgoraRtcChannelMediaOptions at any time, for example, to switch the published audio sources.

11. Subscription allowlists and blocklists

This release introduces subscription allowlists and blocklists for remote audio streams. You can add a user ID that you want to subscribe to in your allowlist, or add a user ID for the streams you do not wish to see to your blocklists. You can experience this feature through the following APIs, and in use-cases that involve multiple channels, you can call the following methods in the AgoraRtcEngineKit(Ex) interface:

• setSubscribeAudioBlacklist：Set the audio subscription blocklist.
• setSubscribeAudioWhitelist：Set the audio subscription allowlist.

If a user is added in a blocklist and a allowlist at the same time, only the blocklist takes effect.

12. Set audio scenarios

To make it easier to change audio scenarios, this release adds the setAudioScenario method. For example, if you want to change the audio scenario from AgoraAudioScenarioDefault to AgoraAudioScenarioGameStreaming when you are in a channel, you can call this method.

Improvements

1. Fast channel switching

This release can achieve the same switching speed as switchChannelByToken in v3.7.x through the leaveChannel and joinChannelByToken methods so that you don't need to take the time to call the switchChannelByToken method.

2. Voice pitch of the local user This release adds voicePitch in AgoraRtcAudioVolumeInfo of reportAudioVolumeIndicationOfSpeakers. You can use voicePitch to get the local user's voice pitch and perform business functions such as rating for singing.

Voice Calling 4.x is a JavaScript and TypeScript library loaded by an HTML web page. The SDK library uses APIs in the web browser to establish connections and control the communication, Broadcast Streaming and Interactive Live Streaming services.

Compatibility

See Supported platforms.

Known issues

The list of known issues page is continuously updated as the systems evolve. Agora suggests you regularly upgrade to the latest version of the SDK, which includes new features, bug fixes and improvements.

• Desktop

  Chrome

  • Starting from Chrome 117, the getStats() method is no longer supported in the SDK v4.9.3 and earlier versions. Calling this method will return all values as 0. This caused by the fact that the old version of the getStats() WebRTC API will be removed from Chrome 117, as stated in the Chrome official documentation. Solution: Upgrade to a higher version of the SDK.

  • On all AMD-based and some Intel-based devices with the Windows operating system, if Chrome uses the H.264 codec, the video transmission bitrate may be lower than the set value. Solution: To resolve this issue, you can set the browser to use the VP9 codec or try to disable hardware acceleration.

  • Chrome 84 on macOS has a known issue: When using the H.264 codec, WebRTC can experience a sudden drop in the frame rate. For details, see the official Google bug reports: Issue 1088650 and Issue 12704. Solution: Agora recommends using VP9 instead of H.264 for Chrome 84 and later versions on macOS.

  • Acoustic Echo Cancellation(AEC) fails to work on Chrome in certain use-cases. Cause: If you apply extra processing (for example, spatial audio) to the received remote audio stream, AEC fails to get the AEC Reference signal. For details, see the Chrome Issue 687574. Solution: Agora recommends that all users wear headphones instead of using speakers. To use speakers in this use-case, contact support@agora.io.

  • Chrome plans to deprecate and remove the Plan B dialect in WebRTC. For details, see the Chrome feature description. If you use any of the following versions of Voice Calling, best practice is to upgrade to the latest version:

    Version	Impact
    v4.0.0-4.0.1	The publish and subscribe methods do not have any effect.

  Safari

  • On Safari 17.2, the SDK cannot switch to the small stream properly.

  • On Safari browsers of some Mac devices with Intel chips, calling enableDualStream to enable H.264-encoded dual-stream mode may result in system lag when the ratio of the small stream to the large stream resolution is below 1/4.

  • On Safari 15.4, if you set the sample rate of the local audio track as 32,000 Hz, the local audio track ends (triggering the AgoraRTCClient.on('track-ended' event).

  • If you use H.264 on Safari 15.1, setting MediaStreamTrack.enabled as false crashes the web tab.

  • On Safari 14.0.1, the audio can experience stuttering.

  • Safari 13 users may not be able to hear other users.

  • Safari 12.1 or earlier only supports the H.264 codec.

  • Safari 11 only supports video resolutions of 480P and higher.

  • Safari does not support getting the output device information, so it does not support the getPlayoutDevices and setAudioOutput methods.

  • On Safari, when calling APIs to get quality statistics, the values of some properties are 0. For example, when calling getLocalAudioStats to get the quality statistics of the local audio track, the value of sendPacketsLost is 0.

  • If Auto-Play is not enabled on Safari (as the following figure shows), the stream playback has no audio. You have to call the navigator.mediaDevices.getUserMedia method to get the device permissions before playing a stream.

  Firefox

  Firefox

  • Black screen issue on the receiver's side with Firefox version 138

    Issue description: When users interact using real-time audio and video on Firefox version 138, the receiver may see a black screen instead of video.

    Root cause: This issue is caused by a rollback in the Firefox browser. Version 138 introduced a temporary change that causes video stream decoding to fail. This is a compatibility issue introduced by the browser vendor. For details, see Bugzilla 1965831.

    Workaround: Agora has implemented a temporary fix through configuration delivery. In incognito or private browsing mode, this configuration may not take effect, and integration changes may be required. Contact technical support for assistance.

  • The default setting for the minimum video bitrate in Web SDK does not take effect on Firefox.

  • Sending SEI data in H.264 video streams is not supported on Firefox.

  • On Firefox 98, when sending H.264 video from Windows devices, the keyframes cannot be received immediately after the video is subscribed, thus slowing down the rendering of the first video frame.

  • When the Web SDK on Firefox communicates with the SDK on some devices, the video on Firefox is rotated.

  • Firefox does not support changing the frame rate (30 fps by default).

  • Firefox does not support setting the audio encoding rate.

  • Setting the video profile on Firefox does not take effect on the following devices:

    • MacBook Pro (13-inch, 2016, Two Thunderbolt 3 ports)
    • Windows 10 (MI)

  • On Macs with the Apple M1 chip, Firefox does not support H.264. For details, see the Firefox documentation.

  • Firefox does not support getting CodecType, sendFrameRate and captureFrameRate.

  Other restrictions on desktop

  • On Chrome 81 or later, Safari, and Firefox, device IDs are only available after the user has granted permission to use the media device. This restriction affects the getMicrophones, getCameras, and getPlaybackDevices methods.
  • The setPlaybackDevice method is only supported on Chrome. Calling this method on other browsers throws the NOT_SUPPORTED error.
  • The setOptimizationMode method and the optimizationMode parameter in CameraVideoTrackInitConfig, ScreenVideoTrackInitConfig, and CustomVideoTrackInitConfig are only supported on Chrome.

• Mobile

  iOS

iOS known issues

iOS 16.0: The video is stretched after the screen changes to a certain orientation

Impact: All browsers and apps that use WKWebView on iOS 16.0, such as Safari and Chrome.

Reason: Due to the regression of the WebRTC module of WebKit on iOS 16.0, RTP streaming with coordination of video orientation (CVO) does not work properly, which causes the video to be stretched after rotation.

Workaround: Agora recommends that you add a prompt to remind users of this issue.

iOS 15.1.x: The browser crashes when sending the H.264 video stream

Impact: All browsers and apps that use WKWebView on iOS 15.1.x, such as Safari and Chrome.

Details: If you set codec as 'h264' when calling createClient, the browsers on iOS 15.1.x crash after you send the video stream.

Reason: This issue happens due to the regression of the WebKit video encoder on iOS 15.1.x. For details, see WebKit Bug 231505.

Workaround: Use the VP9 codec for video encoding.

createClient({codec:'vp9', mode})

iOS 15.x: The actual bitrate of sending the H.264 video stream is lower than expected

Impact: Safari on iOS 15.x

Reason: The issue occurs because WebRTC H264 LowLatency encoder is enabled by default for Safari on iOS 15.x. For details, see Webkit bug 238366.

Workaround: The following workarounds are available:

• Use the VP9 codec for video encoding. The sample code is as follows:

  createClient({codec:'vp9', mode})

• On the iOS device, go to Settings > Safari > Advanced > Experimental Features, and disable WebRTC H264 LowLatency encoder.

iOS 15.0 to 15.3: Low audio volume

Impact: All browsers and apps that use WKWebView on iOS 15.0 to 15.3, such as Safari and Chrome.

Details: On iOS 15.0 to 15.3, after the local user subscribes to the RemoteAudioTrack and plays it, sometimes the audio is routed to the earpiece instead of the speaker, and the volume that the local user hear may be very low.

Reason: This issue happens due to the regression of the WebKit audio module on iOS 15.0 to 15.3. For details, see WebKit Bug 230902.

Workaround: On iOS 15.0 to 15.3, use WebAudio to play the audio, and use GainNode to increase the audio volume level. Use the following workaround:

1. Upgrade to the Web SDK 4.9.0 or later versions.
2. Set the SDK private parameter REMOTE_AUDIO_TRACK_USES_WEB_AUDIO as true. The SDK uses WebAudio to play the remote audio stream. Sample code:

   function isIOS15(ua){
     // Use UA to judge whether the iOS version is 15
   }
   
   if(isIOS15(navigator.userAgent)){
     // If you are using Typescript, add the "@ts-ignore" tag before calling setParameter
     // @ts-ignore
     AgoraRTC.setParameter("REMOTE_AUDIO_TRACK_USES_WEB_AUDIO", true);
   }

iOS 15.x: The video playback goes black

Impact: All browsers and apps that use WKWebView on iOS 15.x, such as Safari and Chrome.

Details: On iOS 15.x, if you play the video in DOM node and add some CSS properties (such as transform and animation) to the video element or its parent element, or if you change the CSS properties to redraw the video rendering area, sometimes the video goes black.

Reason: This issue happens due to the regression of the WebKit video renderer on iOS 15.x. For details, see WebKit Bug 230902.

Workaround: Upgrade to the Web SDK v4.7.3 or later and minimize changes to the CSS properties of the video element and its parent elements.

iOS 15.x: If a user wears a Bluetooth headset, the audio may be significantly distorted

Impact: All browsers and apps that use WKWebView on iOS 15.x, such as Safari and Chrome.

Reason: This issue happens due to the regression of the WebKit audio playback module on iOS 15.x. For details, see WebKit Bug 231422.

Workaround: Agora recommends that you add a prompt to remind users of possible audio distortion issues when they use a Bluetooth headset.

Backgrounding the browser or app causes the audio streaming to be cut off.

Impact:

• Safari on iOS 15.x.
• Browsers and apps that use WKWebView (such as Chrome) on iOS 14.4 to iOS 15.x.

Reason:

• For Safari: This happens primarily due to this WebKit bug. After the browser switches to the background, the AudioContext of WebAudio stops processing audio.
• For browsers and apps using WKWebView: This happens because iOS WKWebView prohibits microphone usage while in the background. For details, see Microphone gets muted in background.

Workaround: Currently there is no workaround for browsers and apps using WKWebView. For Safari on iOS 15.x, you can follow these steps to avoid this issue:

1. Upgrade to the Web SDK v4.7.3 or later versions.

2. When calling createMicrophoneAudioTrack, set bypassWebAudio as true. The Web SDK directly publishes the local audio stream without processing it through WebAudio.

   const localAudioTrack = await AgoraRTC.createMicrophoneAudioTrack({bypassWebAudio: true});

Note that this workaround has a side effect. After applying this workaround, the audio mixing function (MixingAudioTrack) in the SDK fails.

iOS 15.x: Audio and video playback might not resume automatically after being interrupted by a system phone call, another real-time interaction app, Siri, or an alarm.

Impact: All browsers and apps that use WKWebView on iOS 15.x, such as Safari and Chrome.

Reason: Such interruptions can cause the state of the video and audio elements to be paused. After the interruption finishes, the state cannot be automatically switched back to playing, and even calling HTMLMediaElement.play cannot resume the media playback. See the WebKit bug 232599 and 226698 for more details. Workaround: Upgrade to the Web SDK v4.7.3 or later versions. The SDK attempts to resume media playback after the interruption. Agora recommends that you add a prompt that instructs users to refresh the page.

iOS 15.x and 16.x: Certain iPad and iPhone models may experience noise issues after entering a channel.

Impact: Chrome and Safari browsers on specific iPad and iPhone models with iOS 15.x and 16.x. Specific models include:

• iPad (5th Gen)
• iPad (6th Gen)
• iPad (7th Gen)
• iPad Pro (1st Gen)
• iPhone SE (1st Gen)

Workaround: Update to the latest iOS version.

Other known issues

• The volume of a remote user can change randomly on iOS 13 and 14.

  • Switching between the front and rear cameras can momentarily rotate the video.
  • The audio routing can change randomly. Sometimes, the audio is routed to the speakerphone when a headset is connected or to the earpiece when no headset is connected.
  • If you call getUserMedia twice to get two tracks of the same media type, the first track goes muted or black.
  • After a user switches to another app that uses the microphone or camera (such as Siri or Skype) and then switches back, the audio sampling or video capture fails.

  iOS known limitations

  The createScreenVideoTrack method is not supported

Reason: iOS Safari and WKWebView do not support the mediaDevices.getDisplayMedia method.

The setBeautyEffect method is not supported

Reason: WebGL is not well supported on iOS Safari and WKWebView, and the image enhancement algorithm can reduce the system performance below acceptable levels.

The IBufferSourceAudioTrack.seekAudioBuffer method is not supported

Reason: WebAudio on iOS does not support this method.

Cannot send H.264 video streams with a resolution of 1080p or higher

Reason: The Web SDK uses the H.264 Baseline Profile for negotiation, so encoding and sending a video stream with a resolution of 1080p or higher is not supported on iOS.

When sending a low-quality stream on iOS Safari, you cannot set LowStreamParameter.bitrate, and the resolution of the low-quality stream must be proportional to the resolution of the high-quality stream.

Reason: iOS Safari and WkWebView do not support setting the frame rate with the RTCRTPSender.setParameters method. After compressing the resolution with the scaleResolutionDownBy property, the resolution of the low-quality stream stays proportional to the resolution of the high-quality stream.

The encodeDelay property is not supported

Reason: The encodeDelay property cannot be calculated through the getStats method of WebRTC on iOS.

Backgrounding the browser or app causes the user's video to display as a black screen

Reason: iOS AVCaptureSession prohibits camera usage while in the background. For details, see AVCaptureSessionInterruptionReason or Chromium issue 4294.

Calling RemoteAudioTrack.setVolume has no effect on the playback volume of the remote audio

Reason: iOS and iOS WebView do not support setting the volume of a media object through the HTMLMediaElement.volume property.

Android

Android known issues

Android 12: Video distortion on Chrome when hardware acceleration is enabled

Impact: The Chrome browser or Chromium kernel browser 97 or earlier on certain devices with Android 12, such as Pixel 3 and Pixel 4.

Details: If the Chrome browser on Android 12 enables the WebRTC H264 or VP9 hardware acceleration by default, video distortion can occur.

Reason: This issue happens due to the regression of the Chromium WebRTC video encoder. For details, see Chromium issue 1237677.

Workaround: Chrome 97 fixed this issue. You can instruct users to upgrade to Chrome 97 or later versions.

The bitrate when sending video on Android Chrome fails to reach the preset value.

Scope: Certain Android devices, such as Xiaomi and OnePlus.

Reason: This is a hardware encoder issue. The bitrate fails to reach the preset value at a specific video encoding frame rate.

Workaround: In most cases, the bitrate is relatively lower when the frame rate is set as 15 fps. If you set the frame rate as 30 fps, the bitrate increases. So Agora recommends trying to set the frame rate as 30 fps when encountering a bitrate issue. However, setting the frame rate as fps may cause performance issues.

The autoplay of inaudible media is blocked on WeChat

Impact: The WeChat browser using Chromium 89 kernel

Details: The autoplay of inaudible media is blocked. Even after the user interacts with the webpage to resume the video playback, the autoplay block is still not removed.

Reason: This issue happens because the WeChat browser implements a custom autoplay policy.

Workaround: Follow these steps to avoid this issue:

1. Upgrade to the Web SDK v4.6.0 or later versions.

2. Listen to the AgoraRTC.onAutoplayFailed event. Instruct the user to click on the page to resume playback:

   AgoraRTC.onAutoplayFailed = ()=>{
     document.alert('Please click the page to resume playback');
   }

If a local user wears a Bluetooth headset, after they start to send the audio, the remote audio is lost

Scope: Certain Xiaomi and OnePlus devices

Details: If a local user wears a Bluetooth headset, when the Bluetooth headset starts capturing the audio, there is a possibility that the remote audio is lost.

Reason: It may be due to the audio issue on Chromium regarding the profile switch of the Bluetooth.

Workaround: Agora recommends that you add a prompt to remind users of possible audio-loss issues when they use a Bluetooth headset.

When a local user is sending audio, switching the audio output device does not take effect

Scope: Chromium-based browsers on Android devices

Details: When a local users is sending audio, if the user switches from using the speaker to using a Bluetooth headset, the remote audio still comes from the speaker.

Reason: The audio routing on Android devices is controlled by the Android operating system and cannot be fixed at Chromium's level. For details, see Chromium issue 1317548.

Issues specific to certain Android devices

• On devices equipped with MediaTek chips, the Web SDK cannot encode and send video streams in H.264.

  • On devices equipped with Huawei HiSilicon Kirin chips, if you use Chrome versions earlier than 88, the Web SDK cannot encode and send video streams in H.264.
  • When receiving video streams on Chrome on OnePlus 6, if the screen turns off, the video can freeze.
  • Harmony OS does not support sending the video stream of 180p.

  Other known issues

• On some Android devices, the device labels might not be available.

  • On some Android devices, tracks can end if the audio and video streams are interrupted by system phone calls or other audio or video calling apps. To resume the call, the Web SDK needs to re-capture the audio and video.
  • On Android Chrome, the Web SDK cannot send high-quality and low-quality streams in H.264.
  • On Android Chrome earlier than 90, the volume obtained by getVolumeLevel is 0, but the user can hear the audio.
  • On Android system Webview versions from 55 to 75, the decodeFrameRate property stays 0.
  • When running Android 11 on certain OPPO models, such as Reno4 and A11, users will experience black screens and no sound due to the lack of WebRTC support.

  Android known limitations

  The createScreenVideoTrack method is not supported

Reason: The mediaDevices.getDisplayMedia method is not implemented on mobile browsers and WkWebView.

The setBeautyEffect method is not supported

Reason: The image enhancement algorithm can reduce the system performance of mobile devices below acceptable levels.

v4.24.5

Released on June 24, 2026.

Upgrade considerations

• Domain allowlist change

  Starting with v4.24.5, the SDK domain allowlist is updated to:

  .agora.io
  .edge.agora.io
  .sd-rtn.com
  .edge.sd-rtn.com
  .rtnsvc.com
  .edge.rtnsvc.com
  .rtesvc.com
  .edge.rtesvc.com

  If you upgrade to v4.24.5, update your firewall allowlist so the SDK continues to work in restricted-network environments. See Firewall requirements.

New features

• Background voice removal in AI Noise Suppression

  The AI Noise Suppression extension is enhanced to remove background human voices. In noisy environments or scenarios with multiple speakers, this capability further isolates the target speaker and improves audio capture. See Extension release notes.

Improvements

This release includes the following improvements:

• Optimized the signaling flow to improve session-setup efficiency and connection success rates in complex network environments.
• Optimized media-tracing links and jitter-buffer handling to reduce first-frame time and audio and video stuttering in certain scenarios.
• The audio subscription flow now uses a presubscribe model by default, improving subscription efficiency and playback stability. When full-link feedback and frame-rate-priority mode are enabled, you can now set a lower bound for resolution downgrade.

Fixed issues

This release fixed the following issues:

• Connection setup could time out in some scenarios.
• The remote user received duplicate user-joined callbacks when a user with a string UID rejoined a channel immediately after leaving.
• Messages could not be received in some scenarios.
• On Safari 16.6, the local view could turn black or exit unexpectedly in some scenarios.
• Remote video could freeze briefly after the first client.publish(video) call.
• TypeScript type definition files were missing and some exported symbols were incorrect in the npm package.

v4.24.4

Released on May 27, 2026.

Improvements

This release includes internal optimizations for weak-network scenarios, improving the login success rate.

v4.24.3

Released on April 1, 2026.

New features

• AI Noise Suppression extension upgrade

The AI Noise Suppression extension (agora-extension-ai-denoiser) is upgraded to v2.0.1. This version adds a low-latency mode and the ability to configure the log level of the WASM module. For details, see Extension release notes.

Improvements

This release includes the following improvements:

• Optimizes the interactive video experience in H.264 encoding scenarios.
• The Super Clarity extension is upgraded to v2.0.1, with sharpening algorithm improvements that provide better video experience in some scenarios.

v4.24.2

Released on December 12, 2025.

This release addresses a compatibility issue introduced in Chrome 143.

Issue description

During a communication session between users A and B, if user A unsubscribes and stops publishing an audio stream and then tries to publish audio again, the SDK triggers the following error:

Session error code: ERROR_CONTENT

A breaking change in Chrome causes this issue and affects all versions of the RTC Web SDK. See the Chromium bug report for details.

Solution

This version implements a compatibility fix that prevents the issue from interrupting republishing and subscription workflows. The fix remains in place until Chrome provides an official update.

The Agora R&D team has reported the issue to the Chrome team and continues to monitor its progress.

v4.24.1

Released on November 26, 2025.

New Features

• Pre-call network test

Conducting a pre-call network test helps local users assess and predict the quality of their uplink network before starting a call. This version adds the startLastmileProbeTest API, which returns information about packet loss, jitter, and round-trip time for both uplink and downlink before the call begins.

• Dual-stream mode

This version introduces the setDualStreamMode method, which improves how you subscribe to dual video streams. By setting the mode parameter to AUTO_SIMULCAST_MODE, you enable adaptive low-stream mode on the sender side (low-stream is not sent by default). To send low streams, follow these steps:

• The host on the receiving side calls setRemoteVideoStreamType to initiate a low-stream request.
• The sender automatically switches to low-stream mode upon receiving the request.

Additionally, you can set the mode parameter to DISABLE_SIMULCAST_STREAM (never send low stream) or ENABLE_SIMULCAST_STREAM (always send low stream).

For the relationship between this method and the existing enableDualStream and disableDualStream, see the API Reference. To ensure clear integration logic, Agora recommends that you choose one set of APIs for integration. Agora plans to deprecate enableDualStream and disableDualStream in future versions.

• Watermark extension (BETA) This version adds the Watermark extension agora-extension-video-watermark v1.0.0, which enables you to add image watermarks to real-time interactive video streams through an extension.

The Watermark extension supports customizing the watermark's position, size, opacity, and other properties. It can be applied to both local and remote video tracks. For integration and usage steps, refer to Using the Watermark extension guide.

• Other New Features

Adds support for H.265 decoding. Refer to the API Reference for supported browser versions and usage restrictions.

Improvements

• Expanded screen sharing capabilities This version further expands screen sharing capabilities. In the createScreenVideoTrack API, the following parameters are added to support audio sharing during screen sharing:

• windowAudio and monitorTypeSurfaces are added to ScreenVideoTrackInitConfig to control whether to allow sharing window audio and sharing the entire screen, respectively.

• suppressLocalAudioPlayback and restrictOwnAudio are added to ScreenAudioTrackInitConfig to control whether local audio playback and capture are allowed.

In screen sharing scenarios with co-hosting, Agora does not recommend sharing system or window audio, as it may cause echo. You can disable audio sharing by setting both windowAudio and systemAudio in ScreenVideoTrackInitConfig to "exclude".

• New release of the Super Clarity extension

This version upgrades the algorithm of agora-extension-super-clarity, with improvements in reducing plugin size, enhancing video experience, and expanding browser compatibility. The new version of the plugin requires a browser that supports SIMD to run properly. For detailed changes and improvements, refer to the Extension release notes.

Bug Fixes

Fixes an issue on iOS where the system volume could not be set to 0 after destroying an audio stream.

v4.24.0

Released on August 6, 2025

New features

• Fast first-frame rendering

Adds a new options parameter to the join method to configure channel media options. When you set autoSubscribe to true in IJoinOptions, the user automatically subscribes to the host’s media stream when joining the channel.

In real-time interactive scenarios such as one-on-one or one-to-many calls, this feature reduces the time to render the first frame and improves the overall interactive experience.

Improvements

• Transmission optimization in poor network conditions

Optimizes the bandwidth estimation algorithm and implements audio-priority transmission. This reduces the risk of video stuttering under extremely poor network conditions and improves the smoothness of resolution switching, making transitions more seamless. The SDK also responds faster after network recovery.

• New media connection strategy

Introduces a new media connection strategy that improves the SDK’s reconnection and media login success rates under enterprise and restricted network environments.

• Improved accuracy for network quality evaluation

Enhances the algorithm for evaluating NetworkQuality by incorporating available bandwidth as a reference. This enables the SDK to more accurately reflect the impact of bandwidth-limited network conditions.

This improvement requires enabling a private parameter. Contact support@agora.io for details.

Other improvements

• Optimizes the default video bitrate under different encoding standards to allocate uplink bandwidth more efficiently and reduce stuttering in poor network conditions.
• Improves the fallback mechanism for devices that do not support AV1 decoding.
• Enhances the user experience in one-on-one calls in rtc mode when communicating between Web clients or between Web and Native clients.

Issues fixed

This version fixes the following issues:

• Black screen on Firefox 138+ caused by a browser version rollback.
• Video stuttering caused by Safari 18.4 and 18.5.
• Encoding failure when the resolution was too low.
• Occasional black screen in scenarios using Plan-B.

v4.23.4

Released on June 5, 2025.

This release includes internal improvements. It fixes an issue where calling setMute or setEnable under certain conditions could result in no sound. If you are using SDK version 4.23.0 or later, upgrade to this release for a better user experience.

v4.23.3

Released on April 29, 2025.

This release updates the virtual background extension to v2.1.0, with the following changes:

• Optimizes memory and CPU usage.
• Fixes black screen issues at specific resolutions.

v4.23.2

Released on March 4, 2025.

This release includes the following improvements:

• Internal optimizations to support Agora Conversational AI Engine.

  • Enable audio metadata transmission
  • Get presentation timestamp from the audio stream

  For details on using these features, submit a technical support ticket.

• Further reduced package size.

v4.23.1

Released on January 17, 2025.

This release includes several internal improvements.

v4.23.0

Released on December 19, 2024.

Compatibility changes

This release modified the calculation of freezeRate in RemoteVideoTrackStats. The calculation is changed from the cumulative average freeze rate to the freeze rate in the last second. You can use this parameter to determine whether the video is experiencing a momentary freeze. To calculate the cumulative average freeze rate for the current session, use totalFreezeTime or totalDuration.

New features

1. PeerConnection state callback for the local media

   To obtain the media connection state under poor network conditions, this release adds the peerconnection-state-change event, which is used to obtain the connection state of WebRTC RTCPeerConnection.

2. Sharing the current tab by default

   To improve the ease of use of screen sharing, this release adds the preferCurrentTab parameter in ScreenVideoTrackInitConfig, which supports setting sharing the current tab as default when creating a screen sharing track.

Improvements

1. Improved media reconnection strategy

   This release improves the media reconnection strategy, which in turn increases the reconnection and media login success rate under poor network conditions. For enterprise networks with firewalls, the improvement is particularly noticeable. Contact support@agora.io to try this new strategy.

2. Improved virtual background algorithm

   This release upgrades the Virtual Background extension to version 2.0.0. The updated algorithm provides a more distinct face edge and clearer and more stable video images.

3. Reduced package size

   To further reduce the package size, this release separates the Plan-B feature, which is compatible with WebRTC, from the ESM-bundle package into an independent service module. Users can integrate them manually based on actual needs. For details, see Use tree shaking.

4. Other improvements

   • Optimized login duration under complex network conditions.
   • Optimized layer switching algorithm of VP9, which can reduce latency and improve video smoothness.

Bug fixes

This release fixes the following issues:

• Black screen might occur when calling setMute and setEnable under certain conditions.
• Occasional audio and video stream sending failures after network disconnection and reconnection.
• Users with the role of audience can send streams in a 128-person scene.

API changes

Added

• AgoraRTC.on("peer-connection-state-change")
• preferCurrentTab in ScreenVideoTrackInitConfig

v4.22.2

v4.22.2 was released on 29 October 2024.

New features

Screen sharing audio 3A processing

Starting from v4.22.2, when calling the createScreenVideoTrack method to create a screen sharing video track, the withAudio parameter supports passing ScreenAudioTrackInitConfig to customize the initialization config of audio sharing. Depending on your use case, you can enable 3A processing (AGC, AEC, and ANS) as needed to optimize the quality of shared audio.

For details, see the API documentation.

API changes

This version introduces the following new APIs:

• The withAudio parameter in the createScreenVideoTrack method supports passing ScreenAudioTrackInitConfig.

v4.22.1

v4.22.1 was released on 23 September, 2024.

Improvements

This release includes several internal improvements.

v4.22.0

v4.22.0 was released on 16 August, 2024.

Compatibility changes

To further reduce the package size, this version splits the Channel Media Relay Service and the Live Streaming Service from the ESM-bundle format package into independent service modules. You can manually import these modules for integration based on your actual needs. See Use tree shaking for details on how to integrate.

New features

Optimize channel preload

When using the channel preload feature, Agora recommends sending the host's media stream immediately when calling the method to join the channel. This reduces the first frame rendering time. For details, see Preload channels. With this setting, users will start pulling streams as soon as they join the channel, which will generate charges. For details on how Agora charges for the services, see Pricing.

Support for AV1 encoding (Beta)

The SDK supports the AV1 video encoding format. You can enable this encoding format by setting ClientConfig.codec to av1. Compared to H.264 at the same bitrate, AV1 offers over a 30% improvement in encoding efficiency and provides better video quality.

Improvements

This version includes the following improvements:

• Optimizes the SVC (Scalable Video Coding) capability for VP9 encoding and decoding, which further enhances the video quality and transmission efficiency.
• Improves VAD (Voice Activity Detection) with a new music detection feature, increasing the accuracy of voice detection.

Issues fixed

This version fixes the following issues:

• The issue where Safari failed to retrieve stats in certain use-cases.
• The issue with inaccurate bitrate settings under poor network conditions in certain use-cases.

API changes

This version introduces the following new APIs:

• AgoraRTCClient.getRemoteAudioStats adds the receivePacketsDiscarded return field.
• ClientConfig.codec adds the av1 enumeration.
• The AgoraRTC module in the ESM-bundle adds the use method.

v4.21.0

v4.21.0 was released on June 3, 2024.

Compatibility changes

This release introduces the Video Quality Control (VQC) module. ICameraVideoTrack enables the “motion” mode by default to ensure the smoothness of the video under low bandwidth and high CPU usage to further improve the user experience. You can call the setOptimizationMode method to dynamically adjust the transmission mode of the video according to your needs.

New features

Preload channels

This release adds the AgoraRTC.preload method, which allows the user whose role is set to audience to preload channels before joining one. Calling the method can help shorten the time of joining a channel, thus reducing the time it takes for audience members to hear the host.

Improvements

This release includes the following improvements:

• Enhances the bandwidth estimation and congestion control algorithms for the sender in weak network conditions, effectively reducing the buffering rate of the sender under such conditions.
• Optimizes the SDK's browser compatibility detection scope to address the issue of inaccurate browser compatibility detection on certain devices.
• To enhance the user experience of browsers under Safari 17.4, the video quality adaptive algorithm has been added to improve the adaptability of video quality in the case of limited network bandwidth, to further ensure the smoothness of video streaming.

Issues fixed

This release fixes the following issues:

• On some Android devices, the video playback status returned by isPlaying was inaccurate.
• On Safari mobile browsers, the resolution information of the local video track returned by the getLocalVideoStats method was inaccurate; the resolution set by setLowStreamParameter for the low stream resolution did not take effect.

API changes

Added

• AgoraRTC.preload

v4.20.2

v4.20.2 was released on March 21, 2024.

Issues fixed

This release fixes the issue where the browser would modify the captured video resolution when calling createCustomVideoTrack in certain use-cases.

v4.20.1

v4.20.1 was released on February 28, 2024.

New features

This release adds the following new features:

Send the SEI in the H.264 video streams

This release introduces the LocalVideoTrack.sendSeiData method and the RemoteVideoTrack.on("sei-received") event to add and send the Supplemental Enhancement Information (SEI) within the H.264 video streams. The SEI data package has a maximum size of 1KB and encompasses dynamic facial capture data, virtual video information, and digital watermarking. To enable this feature, please contact technical support.

Note:

• This functionality is only supported on Chrome 87 or later, as well as Safari 15.4 or later.
• Due to the conflicts in certain browser core components, this feature is not available when end-to-end media encryption (Beta) is enabled.

Monitor the video states of receivers

v4.20.1 introduces the "video-state-changed" event, which enables real-time monitoring of the video states of receivers, such as freezing and recovery, thereby facilitating prompt responses. For more information, see API documentation.

Data Stream Encryption

To enhance the security of data stream transmission, this version introduces a new encryptDataStream parameter in the setEncryptionConfig method for enabling data stream encryption. For more details, see API documentation.

Improvements

This release adds the following improvements:

• Optimizes the audio reception experience on mobile devices, reducing issues such as electric noise or silence caused by browser defects in single audio stream use-cases.
• Enhances video bitrate settings by adding a default setting for the minimum video bitrate. If you don't specify a value for bitrateMin when calling setEncoderConfiguration, the SDK will automatically set an appropriate bitrate based on the resolution and frame rate settings. This default setting only applies to Chrome and Edge browsers.

Issues fixed

This release fixes the following issue:

• In a single channel with 128 concurrent online hosts, if a user left the channel during network reconnection, it could result in the failure to subscribe to other users' audio streams for the local user.

API changes

Added

• LocalVideoTrack.sendSeiData
• RemoteVideoTrack.on("sei-received")
• RemoteVideoTrack.on("video-state-changed")
• encryptDataStream parameter to AgoraRTCClient.setEncryptionConfig

v4.20.0

v4.20.0 was released on December 8, 2023.

Compatibility changes

Prior to v4.20.0, the IRemoteAudioTrack.setPlaybackDevice method could be invoked on Firefox, but an echo issue would occur due to a Firefox bug. To improve the user experience, starting from v4.20.0, the SDK throws a NOT_SUPPORTED error when this method is called.

If you are using the IRemoteAudioTrack.setPlaybackDevice method, you need to make code modifications after upgrading to v4.20.0.

New features

On certain versions of iOS devices, the app call might not automatically resume after being interrupted by a WeChat call or system phone call. To address this issue, this release introduces the "audio-context-state-changed" event to monitor whether the app call has been interrupted, and the resumeAudioContext method to restore the app call.

For usage details, refer to the API documentation.

Improvements

This release includes the following improvements:

• Reduces the time it takes to join a channel when the user ID is a string.
• Supports audio sharing on the ChromeOS platform when sharing the entire screen or a Chrome tab.

API changes

Added

• resumeAudioContext
• AgoraRTC.on("audio-context-state-changed")

v4.19.3

v4.19.3 was released on November 2, 2023.

Issues fixed

This release fixes a black screen issue when receiving H.264 encoded video streams on Safari prior to 16. Specifically, when a client using v4.19.2 SDK for Web made a video call on Safari prior to 16 to a client using the SDK for Android, iOS, Windows, or macOS, the web client displayed a black screen if the native client sent H.264 encoded video streams.

If you have integrated v4.19.2 of the SDK, Agora recommends upgrading to v4.19.3 as soon as possible.

v4.19.2

v4.19.2 was released on October 20, 2023.

Improvements

VP9 codec (GA)

This release advances VP9 from Beta to General Availability (GA) and introduces the following enhancements:

• Updated browser compatibility: VP9 now supports Safari 16.0 and later versions on both desktop and mobile platforms.
• Automatic fallback to VP8 for older browsers: If any user in a channel uses a browser version below the specified compatibility threshold, all VP9-encoded video streams in that channel will automatically transition to VP8.

Test results show that VP9 provides twice the quality of VP8 at equivalent bitrates.

Dynamic resolution adjustment on Safari

Safari has a known issue where it does not automatically reduce video encoding resolution under poor network conditions or reduced video frame rates, potentially leading to blurry video. To ensure user experience, this release adds the "720p_auto" preset to the video encoder configurations. This preset guarantees automatic adjustment of the video encoding resolution on Safari.

After upgrading to this version, if you are using a 720p video profile, Agora recommends switching to the "720p_auto" preset and setting the encoding format to "vp9" for optimal results.

API changes

Added

• "720p_auto" to VideoEncoderConfigurationPreset

v4.19.1

v4.19.1 was released on October 11, 2023.

Issues fixed

This release fixes the issue that an error occurred when using Webpack 4.x to bundle your app after integrating the SDK.

v4.19.0

v4.19.0 was released on September 25, 2023.

Compatibility changes

Dynamic low-quality video profile adjustment

Before 4.19.0, you had to call setLowStreamParameter before publish to set the video profile for the low-quality video stream. This meant that changing the profile after publishing required republishing, impacting the viewing experience.

As of this release, you can call setLowStreamParameter after publish to dynamically adjust the resolution, bitrate, and frame rate of the low-quality video stream. Agora recommends modifying your setLowStreamParameter calls as needed after upgrading to this release. For example, in use-cases such as live streaming and video conferences, as the number of hosts in the channel increases, you can dynamically adjust the video profile of the low-quality video stream to relieve bandwidth pressure.

New features

Tree shaking support

As of this release, the SDK supports tree shaking, which removes unused code during the build process, reducing your app's size after integrating the SDK. To use this feature, see App size optimization.

Dual display of video stream

This release adds the clone method, allowing you to duplicate the current camera or screen sharing video track and customize display parameters. This can be useful in use-cases such as video conferencing and online education, where you want to display the same video stream with two sets of display parameters, including resolution, frame rate, and bitrate. For example, you can have one display set to high definition and the other to low definition.

Switch between front and rear cameras

To improve camera switching on mobile devices, this release adds the facingMode parameter to the ICameraVideoTrack.setDevice method. You can specify whether to use the front or rear camera on the mobile device.

See setDevice for details.

Third-party video moderation

As of this release, the SDK supports integration with third-party video moderation services.

See setImageModeration in the API Reference for details.

Beta features

End-to-end media encryption and Super Clarity extension are released in beta. See beta documentation for details.

Improvements

Optimized automatic mode

In the automatic mode, the SDK initially attempts a direct connection to Agora SDRTN®. If the attempt fails, the SDK automatically switches to TCP/TLS 443. To enhance the connection experience in restricted networks, this release optimizes the SDK's automatic mode, improving connection speed and stability. The optimized automatic mode no longer uses proxies, resulting in the deprecation of the AgoraRTCClient.on("join-fallback-to-proxy") callback.

Other improvements

This release also includes the following improvements:

• Reduces the time to first frame rendering. To enable this improvement, please contact technical support.
• Adds token expiration as a reason for a user leaving a channel in the AgoraRTCClient.on("connection-state-change") callback for easier troubleshooting.
• Adds sendJitterMs and sendRttMs to local audio track information, reporting jitter (ms) and round-trip time (ms) for sent audio packets.

Issues fixed

This release fixes the following issues:

• Under normal network conditions, the SDK occasionally misreported uplink network quality as 5 in the first few seconds after joining a channel.
• The local and remote audio and video packet loss rates reported by the SDK under the currentPacketLossRate attribute were inaccurate.
• On Windows devices using Chrome 115 browser, if the local user's screen sharing remained static without mouse movement, screen sharing stopped.
• During the procedure of subscribing to remote media streams, instances arose where the absence of audio was sporadically encountered by the local user when the remote user republished the audio stream. Likewise, when the remote user republished the video stream, occasional occurrences of a black screen were observed by the local user.
• Memory was not promptly released after calling IBufferSourceAudioTrack.close.

API changes

Added

• ICameraVideoTrack.clone and ILocalVideoTrack.clone

• facingMode to the setDevice method

• TOKEN_EXPIRE to the ConnectionDisconnectedReason enum

• setImageModeration

• AgoraRTCClient.on("image-moderation-connection-state-change")

• ImageModerationConfiguration

• ImageModerationConnectionState

• sendJitterMs and sendRttMs to the LocalAudioTrackStats interface

• sendJitterMs and sendRttMs to the LocalVideoTrackStats interface

• getRTCRtpTransceiver

• AgoraRTCClient.on("transceiver-updated")

Deprecated

• AgoraRTCClient.on("join-fallback-to-proxy")

v4.18.3

v4.18.3 was released on September 20, 2023.

Issues fixed

v4.18.3 fixes the following issue:

• The SDK failed to obtain audio and video statistics on Safari 17.

v4.18.2

v4.18.2 was released on July 11, 2023.

Issues fixed

v4.18.2 fixes the following issues:

• In certain circumstances, Video SDK for Web triggered microphone and camera device permission prompts after it finished loading.

v4.18.1

v4.18.1 was released on July 03, 2023.

Improvements

Error handling support for event listeners

As of this release, when an error occurs during the execution of the callback function assigned to the event listener (listener), the SDK does not interrupt normal operation. Instead, the SDK captures the exception and provide error information in the logs.

Enhanced concurrency control for asynchronous methods

This release optimizes concurrency control for asynchronous methods. When the following asynchronous methods are invoked concurrently, the SDK executes them in the order they were called, ensuring consistency:

• join and leave
• publish and unpublish
• subscribe and unsubscribe

Taking publish and unpublish as an example, if you call unpublish immediately after calling publish:

• In versions earlier than 4.18.1, unpublish might not take effect, which means the media track could remain published.
• As of version 4.18.1, the actual result is consistent with the order of these method calls, which means the media track is correctly unpublished.

Issues fixed

This release fixed the issue that the following callbacks were not triggered when an external camera or microphone was initially connected to a device without any available cameras or microphones:

• onCameraChanged or AgoraRTC.on("camera-changed")
• onMicrophoneChanged or AgoraRTC.on("microphone-changed")

v4.18.0

v4.18.0 was released on June 12, 2023.

New features

Variable playback speed for audio files

To facilitate changing the playback speed of audio effect or music files, v4.18.0 modifies the IBufferSourceAudioTrack class as follows:

• Adds the setAudioBufferPlaybackSpeed method, which can be called before or after a user joins a channel.
• Adds the playbackSpeed property to retrieve the current playback speed.

Custom signaling proxy

v4.18.0 adds the setProxyServer method to allow customization of the signaling proxy server used by the SDK.

Flexible event listening for AgoraRTC objects

As of v4.18.0, the IAgoraRTC class inherits all methods from the EventEmitter class, providing a flexible way of listening to all events emitted by the AgoraRTC object.

Using onCameraChanged as an example:

// Previous event listening (earlier than v4.18.0)
AgoraRTC.onCameraChanged = (info) => {
 console.log("camera changed!", info.state, info.device);
};
// New event listening (v4.18.0 and later)
AgoraRTC.on("camera-changed", (info) => {
 console.log("Camera changed!", info.state, info.device);
});

You can continue using the previous approach. However, for higher flexibility and extensibility, Agora recommends modifying the listening approach for the following events after upgrading the SDK:

• onAutoplayFailed
• onCameraChanged
• onMicrophoneChanged
• onPlaybackDeviceChanged
• onSecurityPolicyViolation
• onAudioAutoplayFailed: Deprecated, see onAutoplayFailed instead

Scalable Video Coding, access to encoded data, and enhanced connection experience in restricted networks are released in beta. See beta documentation for details.

Improvements

Shorter time to join channel

As of v4.18.0, the SDK enables WebSocket message compression by default, reducing the time to join a channel in poor network conditions.

Other improvements

v4.18.0 also includes the following improvements:

• Improves the retry mechanism by adding a 3s retry rule to switch a downgraded video resolution to a higher one. This prevents the video resolution from remaining low when the network conditions improve, resulting in a better user experience.
• Upgrades the Cloud Proxy service to enhance its stability in different network environments.

API changes

Added

• setProxyServer
• setAudioBufferPlaybackSpeed method and playbackSpeed property to IBufferSourceAudioTrack
• The following methods inherited from the EventEmitter class to the IAgoraRTC class:
• on
• off
• once
• getListeners
• removeAllListeners

Issues fixed

v4.18.0 fixes the following issues:

• Mobile devices experienced delays in receiving notifications for the broadcaster leave channel event.
• Users experienced a black screen while watching video streams encoded with H.264 in older browser versions.
• Memory usage increased when using the SDK with the Virtual Background or Image Enhancer extension.
• The SDK continued to use the expired token during reconnection attempts after generating a new token using the renewToken method.

v4.17.2

v4.17.2 was released on April 20, 2023.

Issues fixed

This release fixes the issue where the getCurrentFrameData method returned abnormal data.

v4.17.1

v4.17.1 was released on April 19, 2023.

Compatibility changes