Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Release notes

Updated

Information about changes in each release of Voice Calling.

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:

      VersionImpact
      v4.0.0-4.0.1The 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.

When automatic subscription to the host’s media stream is enabled, Agora delivers the media stream and starts billing for usage as soon as the user joins the channel.

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:

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.

Safari does not support VP9 SVC.

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.

If your browser does not support audio sharing, passing ScreenAudioTrackInitConfig will only return the video track.

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.

After integrating this version of the SDK into your app, you might encounter an error if you use Webpack 4.x to bundle your app. To resolve this issue:

  • If you intend to use Webpack 4.x, upgrade the SDK to v4.19.1.
  • If you prefer to continue using v4.19.0, Agora recommends bundling your app with Webpack 5.x or other tools such as Vite.

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

These methods support the following event names as parameters:

  • "camera-changed"
  • "microphone-changed"
  • "playback-device-changed"
  • "autoplay-failed"
  • "security-policy-violation"

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

Chrome 107 prevents users from sharing the current tab by default. If you need to allow users to share the current tab on Chrome 107 and later versions, please upgrade your SDK to v4.17.1 or later as soon as possible.

To accommodate changes related to screen sharing in Chrome 107 (refer to Chrome documentation), this release introduces the following changes to the config parameter in the createScreenVideoTrack method:

  • Deprecates the screenSourceType property. If you are using this property, replace it with the newly added displaySurface property after upgrading to this version.
  • Adds new properties: selfBrowserSurface, surfaceSwitching, and systemAudio.

For detailed explanations of these properties, see ScreenVideoTrackInitConfig in the API reference.

Improvements

Improved flexibility in setting video profiles

This release improves the flexibility in setting video profiles for different types of video tracks:

  • You can now specify the resolution and the frame rate when calling createCustomVideoTrack to create a custom video track, by passing in values for the width, height, and frameRate parameters.
  • After creating a screen track or a custom video track, you can dynamically adjust the video profile using LocalVideoTrack.setEncoderConfiguration. Please note that there is a known issue with calling this method on a screen track in certain versions of macOS Safari. See issue details.

For details, see more about Configure video encoding.

Other improvements

This release also includes the following improvements:

  • The time required to create tracks using createMicrophoneAudioTrack or createMicrophoneAndCameraTracks on Safari browsers is reduced.

  • When you have two AgoraRTCClient objects created locally, you have the option to block certain callbacks from one AgoraRTCClient to another. These callbacks include those triggered when joining or leaving a channel, and publishing or unpublishing streams. For example, if you are using Client A for publishing a screen track and Client B for publishing a camera track, and you enable this feature to block callbacks, Client A and B will not receive the following callbacks from each other:

  • AgoraRTCClient.on("user-published")

  • AgoraRTCClient.on("user-joined")

  • AgoraRTCClient.on("user-unpublished")

  • AgoraRTCClient.on("user-left")

  • AgoraRTCClient.on("published-user-list")

  • AgoraRTCClient.on("user-info-update")

To enable this feature, contact technical support.

API changes

Added

  • displaySurface (replacement for screenSourceType), selfBrowserSurface, surfaceSwitching, and systemAudio in the ScreenVideoTrackInitConfig interface
  • width, height, and frameRate in the createCustomVideoTrack method
  • LocalVideoTrack.setEncoderConfiguration

Deleted

  • ILocalVideoTrack.setBeautyEffect

v4.17.0

v4.17.0 was released on March 22, 2023.

New features

Dynamic switching of local video streams

This release adds the ILocalVideoTrack.replaceTrack method to increase the flexibility to switch local video tracks.

For example, to switch from one camera to another before v4.17.0, you needed to call IAgoraRTCClient.unpublish to unpublish the current track and then call IAgoraRTCClient.publish to publish a new track. As of v4.17.0, you can call ILocalVideoTrack.replaceTrack directly.

Improvements

Optimized reconnection mechanism

As of v4.17.0, the SDK defaults to showing the last video frame before disconnection during reconnection, which prevents a black screen during the reconnection process. This optimization is not available on Safari due to Safari's limitations.

Other improvements

This release also includes the following improvements:

  • The accuracy of SDK-related quality metrics on Analytics is improved.
  • The time required to join a channel is reduced. This optimization is not available on Firefox due to Firefox's limitations.

API changes

Added

  • ILocalVideoTrack.replaceTrack

Deleted

  • ILocalVideoTrack.setBeautyEffect

Issues fixed

On Safari on iOS 14.7 and later, performing subscribing and unsubscribing operations repeatedly to multiple audio streams could result in not hearing remote users.

v4.16.1

Voice Calling v4.16.1 was released on February 7, 2023.

Issues fixed

This release fixes the following issue:

  • When using Video SDK for Web v4.16.0, the video freeze rate showed in Agora Analytics is much higher than the correct value.

v4.16.0

Voice Calling v4.16.0 was released on January 5, 2023.

Improvements

This release adds the following enhancements:

Compatibility for deprecated RTCMediaStreamTrackStats on Chrome

Chrome plans to deprecate the stats dictionary RTCMediaStreamTrackStats. See the service announcement on discuss-webrtc@googlegrooups.com. This change affects the following media track statistics returned by the SDK:

StatisticsAffected fields
LocalVideoTrackStats

  • sendFrameRate

  • sendResolutionHeight

  • sendResolutionWidth

RemoteVideoTrackStats

  • receiveFrameRate

  • receiveResolutionHeight

  • receiveResolutionWidth

  • renderFrameRate

  • receiveDelay

RemoteAudioTrackStats

  • receiveDelay

  • receiveLevel

To ensure the accuracy of these media track statistics on Chrome, please upgrade the SDK to v4.16.0 or later as soon as possible.

Other improvements

This version of the SDK also includes the following improvements:

Issues fixed

This release fixes the following issues:

  • Media operations failed when the SDK was attempting to reconnect to the network.
  • When relaying media streams across channels, ChannelMediaRelayConfiguration.addDestChannelInfo could not set uid to 0 to identify the relay stream in the destination channel.
  • Some known issues on iOS 14.x.

v4.15.1

v4.15.1 was released on December 2, 2022.

Issues fixed

This release fixes the following issue:

  • No audio was received on iOS 13.7.

v4.15.0

v4.15.0 was released on October 31, 2022.

New features

The latest features in this release are:

Audio stream filter (Beta)

v4.15.0 introduces filtering audio streams based on volume. Once this function is enabled, Agora SDRTN® ranks all subscribed audio streams by volume. By default, the three audio streams with the highest volume are transported to others in the channel. To change the number of audio streams to be transported, contact support@agora.io.

Agora enables channel hosts to control whether the audio streams being published are filtered based on volume. Streams that are not filtered bypass this filter mechanism and are transported directly to the receivers. In use-cases with a large number of publishers, enabling this function helps reduce the bandwidth and device system pressure for the receivers.

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

VP9 codec

Video SDK for Web v4.15.0 adds support for the VP9 codec in the following browsers:

Supported browsers①
Desktop

  • Chrome 65 or later

  • Firefox 69 or later

  • Edge 79 or later

  • Safari 16 or later

Android

  • Chrome 68 or later

  • Wechat v8.0.6 or later

  • Other apps that use WKWebView: WebView v65.0.3325.109 or later

iOSSafari 16 or later

① To ensure the best user experience, best practice is to use the latest version of the browsers listed above.

To start a call using the VP9 codec, apps you connect to built using for Android, iOS, Windows, or macOS must use Video SDK v4.0.1 or greater.

CSP violation callback

v4.15.0 adds the AgoraRTC.onSecurityPolicyViolation callback. When Agora fails to load a resource or send a request due to Content Security Policy(CSP) violations, the Video SDK triggers this callback. When you receive this callback, modify your CSP configuration to ensure that you can access Agora-related services.

Improvements

The SDK has the following improvements:

  • The accuracy of network quality reported by AgoraRTCClient.on("network-quality") in certain use-cases has increased.
  • Resumption of audio or video streams when the user switches between Wi-Fi networks is faster.

API changes

Added

  • IAgoraRTC.onSecurityPolicyViolation

Compatibility changes

Cloud Proxy default mode has changed. In Video SDK for Web v4.15.0, the mode parameter in startProxyServer defaults to 3. This represents the Force UDP cloud proxy mode. In this mode, Video SDK always transmits data over UDP. For details, see Restricted network connection with Cloud Proxy.

v4.14.2

v4.14.2 was released on October 27, 2022.

Issues fixed

This release fixes the following issue:

  • When using WeChat browsers on iOS 14.x, no audio is received from the first channel the user subscribes to.

v4.14.1

v4.14.1 was released on October 24, 2022.

Issues fixed

This release fixes the following issues:

  • On Electron v17.x, screen sharing did not work properly. To solve this issue, add the following code in the main process:
const { ipcMain, desktopCapturer } = require("electron");

ipcMain.handle("DESKTOP_CAPTURER_GET_SOURCES", (event, opts) => desktopCapturer.getSources(opts));
  • On desktop Safari, if autoplay was blocked for all videos, they kept trying to replay resulting in video freeze.
  • On mobile browsers, the video freeze rate calculated by the SDK was higher than the actual value when the browser was running in the background.
  • In Android WebView, the default poster (a gray play button) of the video element showed before video playback.
  • Media stream relay failed after the SDK resumed connection to the network.
  • During a media stream relay, the SDK continued to send heartbeats after the user left the source channel.

v4.14.0

v4.14.0 was released on August 31, 2022.

Compatibility changes

getVolumeLevel accuracy improvement

As of v4.14.0, the SDK calibrates the calculation of the volume returned in getVolumeLevel. The volume range is still [0,1], where 1 represents the highest audio level. If your business use-case depends on the volume returned in getVolumeLevel (for example, a speaker icon shows according to the volume), ensure that you check the returned volume after upgrading to v4.14.0.

Issues fixed

This release fixes the following issue:

  • The received Opus stereo audio had no stereo effect.
  • On versions earlier than Chrome 76, the decodeFrameRate returned by the getRemoteVideoStats method was 0.
  • On WeChat browsers running on iOS 14.1 and 14.2, the first subscribed audio stream was silent.
  • After calling LocalVideoTrack.setBeautyEffect to enable image enhancement, calling LocalVideoTrack.unpipe caused an error.
  • On Windows Chrome 103 and later versions, enabling the dual-stream mode did not take effect in certain use-cases.

v4.13.0

v4.13.0 was released on July 25, 2022.

New features

Improvements

AI Noise Suppression and virtual background

The AI Noise Suppression extension and virtual background extension are converted from beta release to official release. To experience the AI Noise Suppression or virtual background extension, contact support@agora.io.

Callback for token expiration

v4.13.0 improved the logic of triggering the callback for token expiration. If a token expires when the user's device is in sleep mode or disconnected from network, the SDK triggers the token-privilege-did-expire event when the device resumes operation and attempts to reconnect to the SDK.

API changes

Added

  • RemoteAudioTrack.pipe
  • RemoteAudioTrack.unpipe

v4.12.2

v4.12.2 was released on July 7, 2022. This release improved the automatic mode for SDK connectivity (In this mode, the SDK first attempts a direct connection to Agora SDRTN®; if the attempt fails, the SDK automatically switches to TCP/TLS 443).

v4.12.1

v4.12.1 was released on June 27, 2022. This release fixed the following issues:

  • Subscribing to remote streams occasionally failed after disconnection.

v4.12.0

v4.12.0 was released on June 15, 2022.

Improvements

Media processing extensions

Media processing extensions have the following changes:

Issues fixed

v4.12.0 fixed the issue that when dual-stream mode was enabled on Safari, calling methods such as Track.setEnabled(false) and Track.close() could not turn off the camera indicator light.

v4.11.1

v4.11.1 was released on May 9, 2022. This release fixed the following issues:

  • Subscribing to audio streams might cause no sound on Firefox.
  • Compatibility issues occurred in Safari on iOS 12 and in the WeChat built-in browser on iOS 13.

v4.11.0

v4.11.0 was released on April 1, 2022.

Compatibility changes

As of v4.11.0, the SDK adopts an automatic mode by default to ensure connectivity. In this mode, the SDK first attempts a direct connection to Agora SDRTN®; if the attempt fails, the SDK automatically switches to TCP/TLS 443. You can listen for such auto-switch events through client.on("join-fallback-to-proxy").

Improvements

Channel capacity improvement

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

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

Fixed issues

v4.11.0 fixed the following issues:

  • Angular’s dependency zone.js caused an error when Promise.finally was called in the SDK.

  • On Chrome, AEC could not be enabled when sending stereo sound.

  • On Chrome 100, the SDK reported inaccurate statistics for the decoding frame rate and sending frame rate.

  • When dual-stream mode was enabled, calling unpublish without parameters caused the method call to fail.

v4.10.2

v4.10.2 was released on March 24, 2022. This release fixed the issue that calling join in certain use-cases might cause proxy exceptions.

v4.10.1

v4.10.1 was released on March 17, 2022 and added the dependency of TypeScript type definitions for Agora Extension agora-rte-extension in package.json. If you use TypeScript for type checking, Agora suggests that you update TypeScript to v4.3.2 or later.

v4.10.0

v4.10.0 was released on March 11, 2022.

New features

API changes

Added

  • AgoraRTC.registerExtensions

  • LocalTrack.pipe

  • LocalTrack.unpipe

  • LocalTrack.processorDestination

v4.9.4

v4.9.4 was released on March 16, 2022 and fixed the failure to access localStorage when loading the SDK in an iFrame in Chrome Incognito mode.

v4.9.3

v4.9.3 was released on March 3, 2022. This release fixed several internal issues.

v4.9.1

v4.9.1 was released on February 24, 2022. This release fixed several internal issues.

v4.9.0

v4.9.0 was released on February 17, 2022.

New features

Cloud Proxy Force TCP mode

v4.9.0 adds Force TCP mode for the Agora Cloud Proxy service. In this mode, the SDK always transmits data over TLS 443. To use this mode, set mode as 5 when calling startProxyServer.

Improvements

  • Improves the accuracy of the client.on("is-using-cloud-proxy") event.

Issues fixed

v4.9.0 fixed the following issues:

  • When using v4.8.0 together with Angular and zone.js, users might fail to join a channel because zone.js modified the promise object.

  • Several known issues on iOS.

API changes

Added

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

v4.8.2

v4.8.1

v4.8.1 was released on January 6, 2022. This release fixed an internal issue.

v4.8.0

v4.8.0 was released on December 29, 2021.

New features

Improvements

v4.8.0 made some internal improvements.

Issues fixed

v4.8.0 fixed the following issues:

  • When receiving streams on iOS Safari as an audience member, the host’s voice could be heard, but the volume returned by the client.on("volume-indicator") event was 0.

  • When sending streams on iOS Safari, if you first call setDevice and then setEncoderConfiguration, the SDK returns an error.

API changes

v4.7.3

v4.7.3 was released on November 17, 2021. This release avoided the issue that on the Safari browser in iOS 15.1, after a call was interrupted, the Voice Calling failed to resume playing the remote media.

v4.7.2

v4.7.2 was released on October 14, 2021, with the following changes:

  • Fixed the issue that calling AgoraRTC.checkSystemRequirements() on the Edge browser only returned false.

v4.7.1

v4.7.1 was released on September 13, 2021. This release fixed some issues on Safari 11 and iPad Chrome.

v4.7.0

v4.7.0 was released on September 1, 2021.

Compatibility changes

As of v4.7.0, if you enable media stream encryption, the SDK automatically disables encryption and resets the encryption configurations after a user leaves the channel. To re-enable the encryption, call setEncryptionConfig before the user joins the channel again.

Improvements

This release makes the following improvements:

  • Optimizes the end-user experience of the Voice Calling on the mobile browser.

  • Improves the accuracy of the volume obtained by getVolumeLevel.

  • Adds the support of enabling dual-stream mode on Safari.

Issues fixed

This release fixed the following issues:

  • After calling LocalAudioTrack.setVolume to adjust the local volume, the local user could not perceive the volume change.

  • When the log level was set to none, the SDK nevertheless output the initialization logs.

  • The promise returned by LocalAudioTrack.setDevice could get stuck in a pending state.

v4.6.3

v4.6.3 was released on August 10, 2021. This release fixed an occasional issue: After the user closes a tab or browser on the local client, the remote client does not receive the user-left event immediately.

v4.6.2

v4.6.2 was released on July 30, 2021. This release fixed the issue that the SDK did not destroy all the media players created during a call or live streaming. Chrome 92 introduced a limit on the number of media players that can be created in a particular tab: 75 for the desktop. After you play tracks several times, the undestroyed media players in the SDK might cause the playback failure in the tab.

v4.6.1

v4.6.1 was released on July 21, 2021. This release fixed an internal error.

v4.6.0

v4.6.0 was released on July 16, 2021.

New features

Interactive Live Streaming Standard

As of v4.6.0, the Voice Calling supports Interactive Live Streaming Standard. The major difference between Agora Interactive Live Streaming Standard and Agora Live Interactive Streaming Premium is the latency level on the audience’s client:

  • Interactive Live Streaming Premium: Ultra-low latency (400 ms to 800 ms) from the host’s client to an audience member’s client.

  • Interactive Live Streaming Standard: Low latency (1500 ms to 2000 ms) from the host’s client to an audience member’s client.

The charges for Standard and Premium are different. For details, see the product overview and pricing of Interactive Live Streaming Standard.

You can set the latency level of the audience role in the following two ways:

  • When calling createClient to create a client object, set the role parameter as "audience" and the level parameter in clientRoleOptions as 1.

  • When calling the setClientRole method, set the role parameter as "audience" and the level parameter in clientRoleOptions as 1.

The mute states of local tracks

v4.6.0 adds the localTrack.setMuted method to stop sending the media data of local tracks. The differences between this method and localTrack.setEnabled are as follows:

  • Calling setEnabled(true) takes longer to resume sending the media data than by than calling setMuted(false).

Improvements

Dealing with autoplay blocking

On most web browsers, inaudible media are not affected by autoplay blocking. However, on iOS Safari with low power mode enabled, or on other iOS in-app browsers that implement a custom autoplay policy, such as the WeChat browser, the autoplay of inaudible media is blocked.

Issues fixed

v4.6.0 fixes the following issues:

  • The method call of localAudioTrack.setVolume did not take effect immediately.

  • Using multiple clients on one web page caused unexpected issues.

  • The SDK did not check whether the App ID was a string of 1 to 256 bytes in size.

API changes

Added

  • localTrack.setMuted

  • onAutoplayFailed

  • clientRoleOptions in ClientConfig

  • options in the setClientRole method

Deprecated

  • onAudioAutoplayFailed

v4.5.0

v4.5.0 was released on May 25, 2021.

New features

AEC (Acoustic Echo Canceller) for the audio played on the local client

In a use-case where multiple users play a media file at the same time, such as watching a movie together, if the user A plays the media file through HTMLMediaElement on Chrome with a speaker, the SDK captures the audio played by a speaker together with the voice of the user A. The other users can hear the audio sent by the user A and the audio played locally, which sounds like an echo. To deal with this echo issue, v4.5.0 adds the processExternalMediaAEC method. You can call processExternalMediaAEC and pass in the HTMLMediaElement to enable the AEC for the audio played on the local client.

Improvements

Channel encryption

To strengthen the security of the key, v4.5.0 adds two encryption modes, "aes-128-gcm2" and "aes-256-gcm2", which use the PBKDF2 (Password-Based Key Derivation Function 2). When calling setEncryptionConfig and setting the encryption mode as "aes-128-gcm2" or "aes-256-gcm2", you need to set secret and salt. For how to generate and set secret and salt, see Secure channel encryption.

Restrict media zones

As of v4.5.0, when calling setArea to specify the media zone for connection, you can use the areaCode parameter to specify a large zone and use the excludedArea parameter to specify a small zone. The region for connection is the large zone excluding the small zone. You can only specify the large zone as "GLOBAL". For details, see Restrict media zones.

Issues fixed

v4.5.0 fixes the following issues:

  • The OptimizationMode setting did not take effect.

  • On iOS, when the Voice Calling captures media, noises might occur on the local client.

  • On Chrome, after you called remoteAudioTrack.setVolume to adjust the volume, if the playback was paused and then resumed, the volume changed back to the original one.

  • On Chrome, the LocalAudioTrack.setVolume method did not take effect.

API changes

Added

  • processExternalMediaAEC

  • clientRoleOptions in ClientConfig

  • options in the setClientRole method

  • salt in the setEncryptionConfig method

  • "aes-128-gcm" and "aes-256-gcm" in EncryptionMode

  • excludedArea in the setArea method

v4.4.0

v4.4.0 was released on April 2, 2021.

Compatibility changes

Firewall domain whitelist

As of v4.4.0, the destination domains required for your firewall whitelist changes to:

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

If you upgrade the SDK to v4.4.0, update your firewall domain whitelist to ensure you can use Agora products in environments with restricted network access.

Improvements

AES-GCM encryption mode

In use-cases requiring high security, to ensure the confidentiality, integrity and authenticity of data, and to improve the computational efficiency of data encryption, v4.4.0 adds the following encryption modes in EncryptionMode:

  • "aes-128-xts": 128-bit AES encryption, GCM mode.

  • "aes-256-gcm": 256-bit AES encryption, GCM mode.

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

Cloud proxy

Error code

If you start media capturing after disabling the media capture device on Windows, the error thrown by the SDK changes from UNEXPECTED_ERROR to NOT_READABLE.

Issues fixed

v4.4.0 fixes the following issues:

  • The SDK did not trigger the "first-frame-decoded" event for a remote audio track.

  • The return value of AgoraRTC.checkSystemRequirement was inaccurate.

  • When the network had multiple IP addresses, the cloud proxy service did not take effect.

API changes

Added

  • client.on("is-using-cloud-proxy")

  • "aes-128-gcm" and "aes-256-gcm" in EncryptionMode

v4.3.0

v4.3.0 was released on January 26, 2021.

New features

Cloud proxy

This release optimizes the Agora cloud proxy architecture and enhances the connectivity of the Voice Calling in environments with restricted network access. The optimized Agora cloud proxy service also supports regional connection.

You can contact (mailto

@agora.io) to apply for using the optimized Agora cloud proxy service and set the mode parameter as 3 when calling startProxyServer. For details, see Cloud proxy service.

v4.2.1

v4.2.1 was released on December 23, 2020. This release fixed the incorrect error that the SDK throws when you pass an illegal parameter in the client.publish method.

v4.2.0

v4.2.0 was released on December 1, 2020.

New features

Regional connection

This release adds the AgoraRTC.setArea method for specifying the region for connection. After specifying the region, the SDK connects to the Agora servers within that region. The following regions are supported:

  • China

  • North America

  • Europe

  • Asia, excluding Mainland China

  • Japan

  • India

  • Global

This advanced feature applies to use-cases that have regional restrictions.

Network quality of remote users

This release adds the AgoraRTCClient.getRemoteNetworkQuality method for getting the uplink and downlink network quality of all the remote users to whom the local user subscribes.

Cloud proxy

This release changes the mode parameter of the AgoraRTCClient.startProxyServer method from boolean to number.

Improvements

  • After you call AgoraRTCClient.setEncryptionConfig to enable the built-in encryption, when the user uses a weak secret, the SDK outputs a warning message to the Web Console and prompts the user to use a strong secret. A strong secret must contain at least eight characters and be a combination of uppercase and lowercase letters, numbers, and special characters.

Issues fixed

  • After an audience member tried to publish a local track in live mode but failed, the audience member could not publish this track even after switching the role to host.

  • After dual-stream mode was enabled, a bug during the disconnection would occasionally cause publishing to fail after reconnection.

  • Due to Safari’s limited support for WebAudio, the audio of BufferSourceAudioTrack could be distorted.

  • When the SDK gained device permission for the first time, it did not trigger the media device change events (onMicrophoneChanged, onCameraChanged, or onPlaybackDeviceChanged). The SDK only triggered these events for a subsequent device change.

API changes

Added

  • AgoraRTC.setArea

  • AgoraRTCClient.getRemoteNetworkQuality

Changed

  • Changed the type of the mode parameter in AgoraRTCClient.startProxyServer from boolean to number

v4.1.1

v4.1.1 was released on October 27, 2020. This release fixed the following issues:

  • Improved the accuracy of the event_network_quality event.

  • After calling unsubscribe to unsubscribing from an unpublished track of a remote user, the subsequent subscribing and unsubscribing operations failed to take effect.

v4.1.0

v4.1.0 was released on September 4, 2020.

New features

Audio playback device management

v4.1.0 adds the following APIs to manage audio playback devices:

  • setPlaybackDevice: Sets the audio playback device, for example, the speaker. This method supports Chrome only.

  • getPlaybackDevices: Retrieves the audio playback devices available.

  • onPlaybackDeviceChanged: Occurs when an audio playback device is added or removed.

Improvements

  • Fully supports Chromium-based versions of Microsoft Edge (versions 80 and later).

  • Improves the accuracy of the network-quality event.

  • Supports sharing audio when sharing Chrome tabs on macOS.

Issues fixed

  • Occasional failure of reconnection after enabling dual-stream mode.

  • Occasional failure to call setEnabled after leaving the channel.

  • Failure to push streams to CDN with transcoding and without transcoding at the same time.

  • Occasional failure to automatically re-subscribe to the remote streams after disconnection, indicated by the UNEXPECTED_RESPONSE: ERR_SUBSCRIBE_REQUEST_INVALID error.

  • Failure to join different channels with the same UID in one browser tab.

  • Occasional misreport on connection states due to frequent channel join and leave.

API changes

Added

  • AgoraRTC.getPlaybackDevices

  • LocalAudioTrack.setPlaybackDevice

  • RemoteAudioTrack.setPlaybackDevice

  • AgoraRTC.onPlaybackDeviceChanged

  • Client.getLocalAudioStats

  • Client.getRemoteAudioStats

Deprecated

v4.0.1

v4.0.1 was released on July 18, 2020. This release fixed the following issues:

  • Failure to publish local tracks on Chrome 70.
  • Publish operation may not be aborted when leaving the channel.

v4.0.0

v4.0.0 was released on July 15, 2020.

Compatibility changes

v4.0.0 deletes the LocalTrack.setMute method and adds the LocalTrack.setEnabled method for enabling or disabling a local track. The advantages of this change are as follows:

  • Eliminates the concept of "mute" to avoid confusion between mute states and publishing states.

  • In versions earlier than v4.0.0, the SDK triggers the Client.on("user-mute-updated") callback when the remote user calls setMute to change the mute state.

  • As of v4.0.0, the SDK triggers the existing Client.on("user-unpublished") or Client.on("user-published") callbacks when the remote user calls setEnabled to enable or disable a track.

The setEnabled method changes media input behaviors, so it is an asynchronous operation and returns the result through the Promise object.

New features

Improvements

  • The Client.subscribe method.

  • The Client.on("user-published") and Client.on("user-unpublished") callbacks.

Issues fixed

v4.0.0 fixed the following issues:

  • After the local user called unpublish, the SDK triggerred the Client.on("user-left") callback on the remote side.

  • Occasional publishing failure when calling publish and unpublish frequently.

  • The Client.on("network-quality") callback was inaccurate.

API changes

Added

  • The Client.localTracks interface

  • The LocalTrack.setEnabled method

Updated

  • Removes the value of "all" from the mediaType parameter in Client.subscribe.

  • The mediaType parameter in the Client.on("user-published") and Client.on("user-unpublished") callbacks does report "all"

Deprecated

  • The LocalAudioTrackStats.muteState property

  • The RemoteAudioTrackStats.muteState property

Deleted

  • The Client.on("user-mute-updated") callback

  • The LocalTrack.setMute method

  • The AgoraRTCRemoteUser.audioMuted property

  • The LocalTrack.getUserId method

AI Noise Suppression

Agora charges additionally for this extension. See Pricing.

v2.0.2

Released on June 24, 2026.

New features

  • Added background voice removal.
  • Suitable for noisy environments or scenarios with multiple speakers to further highlight the target voice and improve audio capture.

v2.0.1

Released on April 1, 2026.

Compatibility changes

This version no longer supports calling the disable method before pipe to disable the processor. Ensure that you call pipe before invoking disable.

New features

  • Added the setLogLevel method to the IAIDenoiserExtension interface class to set the log level for the plugin and WASM module.
  • Added the setLatency method to the IAIDenoiserProcessor interface class to configure latency for noise reduction processing.

Improvements

  • Updated the noise reduction algorithm for improved noise suppression, voice fidelity, and overall robustness.
  • Significantly improved voice fidelity after AI noise suppression in scenarios with sampling rates of 16 kHz and above.
  • Optimized CPU resource allocation strategy to enhance runtime efficiency.

API changes

The implementation of callbacks has been revised in this version. The original callbacks onloaderror, onoverload, ondump, and ondumpend are deprecated. Use the on method with event names "pipeerror", "overload", "dump", or "dumpend" to listen for the corresponding events instead.

v1.1.0

Improvement

This release improves the calculation performance of the AI-powered noise suppression algorithm.

New features

This release adds the following APIs and parameters:

  • APIs:
    • checkCompatibility: Checks whether the AI Noise Suppression extension is supported on the current browser.
    • setMode: Sets the noise suppression mode as AI noise suppression or stationary noise suppression.
    • setLevel: Sets the AI noise suppression level.
  • Parameters:
    • elapsedTime in onoverload: Reports the time in ms that the extension needs to process one audio frame.

For API details, see AI Noise Suppression.

Compatibility changes

This release brings the following changes:

  • AI Noise Suppression supports Agora Video SDK for Web v4.15.0 or later.
  • The extension has Wasm dependencies only. Because JS dependencies are removed, you need to publish the Wasm files located in the node_modules/agora-extension-ai-denoiser/external directory again. If you have enabled the Content Security Policy (CSP), you need to modify the CSP configuration. See AI Noise Suppression for details.
  • The audio data is dumped in PCM format instead of WAV format.
  • To adjust the intensity of noise suppression, best practice is to call setLevel.

v1.0.0

First release.

Noise suppression for use cases involving AI

v1.0.0-beta2

agora-conversational-ai-denoiser v1.0.0-beta2 was released on March 5, 2025, to enhance the user experience in applications powered by Agora Conversational AI Engine.

The agora-conversational-ai-denoiser plugin has high CPU usage. Agora recommend using it only for AI-related use cases.

Key features:

  • Significantly improved voice protection, especially for singing.
  • Reduced risk of audio capture and playback stuttering during operation.
  • When AI noise suppression is enabled, the default maximum AGC gain is reduced from 24dB to 12dB.

Virtual background

Key Features

  • Seamless Integration.

    • Integrate directly through an HTML <script> tag or through npm using:

      import `VirtualBackgroundExtension` from "agora-extension-virtual-background"

    • Works within Agora WebRTC video processing pipelines.

  • Support for multiple background types.

    • Blurred Background: Users can blur their actual background with low, medium, or high blur intensity.
    • Image Background: Allows replacing the background with an image (HTMLImageElement).
    • Video Background: Supports setting a video as the virtual background.
    • Solid Color Background: Allows setting a solid color as the background.

Browser Support & Limitations

  • Safari & Firefox – Limited Support

    While the virtual background feature may work on Safari and Firefox, it is not officially supported due to performance limitations. Safari users may experience reduced performance due to browser-specific constraints, while Firefox users may encounter video freezing when minimizing the browser or switching tabs. For optimal performance and reliability, we recommend using the latest version of Chrome on desktop.

  • Mobile Browsers - Not optimal

    The virtual background feature requires significant CPU and GPU processing power, which exceeds the capabilities of most mobile devices. Due to these hardware-intensive requirements, performance on mobile browsers is inconsistent and varies across devices.

v2.1.0

v2.1.0 was released on April 29, 2025, with the following changes:

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

v2.0.0

v2.0.0 was released on December 18, 2024.

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

New Features

  • Support for VP9 codec, which provides better video compression and quality.

Improvements

  • Dynamic background switching. Users can change backgrounds without restarting the video stream.
  • Ability to disable/re-enable virtual backgrounds dynamically.
  • Processor optimization for better real-time segmentation.

Upgrading considerations

Version 2.0.0 is suitable for users who prioritize quality over frame rate especially in use-cases requiring:

  • Superior portrait edge detection
  • Complex background handling
  • Premium video quality

It is recommended for high-end devices such as:

  • Apple M1/M2
  • Latest iPhones (A13 Bionic and newer)
  • Premium Android devices (Snapdragon 865 or equivalent)

Version 1.3.0 is suitable for mid-range devices and is recommended for users who prioritize smooth performance over edge precision such as in standard video conferencing. It is recommended for use cases requiring:

  • Higher FPS
  • Lower resource consumption
  • Consistent performance

Implementation Guidelines:

  • For premium applications, implement device detection. Use 2.0.0 for capable devices and default to 1.3.0 for others.

  • For General applications, default to 1.3.0. Optionally, allow users to upgrade to 2.0.0 with a performance warning.

v1.2.0

v1.2.0 was released on December 10, 2023.

Compatibility changes

As of this version, the Virtual Background extension incorporates the necessary Wasm module. You no longer need to publish the Wasm file separately, and pass the wasmDir parameter when calling the init method to initialize the extension.

After upgrading to this version, please modify your code accordingly.

Improvements

This release upgrades the background segmentation algorithm of the extension, optimizing the segmentation effects on the subject, edges, and fingers in complex static and dynamic backgrounds.

Fixed issues

This release fixed the issue that checkCompatibility could return inaccurate results on specific devices.

API changes

The wasmDir parameter of the init method is now optional.

v1.1.3

Fixed issues

This release fixes the occasional issue of jagged background images on Chrome for Android.

v1.1.2

New features

You can now specify the fit property when calling setOptions. This sets how the background is resized to fit the container. For API details, see Virtual background.

Compatibility changes

Virtual Background supports Agora Video SDK for Web v4.15.0 or later.

v1.1.1

New features

You can now call checkCompatibility and test if AI Noise Suppression extension is supported on the current browser. For API details, see Virtual background.

Fixed issues

A black bar is no longer displayed to the left of the virtual background.

v1.1.0

New features

You can create multiple VirtualBackgroundProcessor instances to process multiple video streams.

v1.0.0

First release.

Super clarity extension

This extension leverages Agora's AI quality enhancement algorithm to intelligently improves video quality without altering the resolution, thereby optimizing the viewing experience at the receiving end. For detailed integration steps, refer to the Super Clarity integration guide.

v2.0.1

Released on April 1, 2026.

This version optimizes the sharpening algorithm, improving video experience in some scenarios.

v2.0.0

Released on November 18, 2025

Improvements

This version includes the following improvements:

  • Reduces extension size by approximately 30%.
  • Handles WebGL context loss to improve video robustness.
  • Improves smoothness when the sender app goes to the background by aligning frame rates.
  • Expands compatibility with Safari browser.

v1.0.1

Released on November 10, 2024, this the first version of agora-extension-super-clarity. For detailed integration steps, refer to Super Clarity.

Watermark extension

v1.0.0

Released on November 18, 2025.

This the first version of agora-extension-video-watermark. For detailed integration steps, refer to Video Watermark.

Video Compositor extension

This extension enables local users to seamlessly merge multiple video streams and images into a single video track. This feature allows for the simultaneous display of multiple video feeds in the same video container.

v1.0.0-beta

Released on October 25, 2022.

This the first version of agora-extension-videp-compositor. For detailed integration steps, refer to Video Compositor.

Beauty Effect extension

This extension enables your users to apply beauty effects to their videos. They can adjust settings for whitening, skin smoothing, acne removal, and redness to achieve a natural beauty effect.

v1.0.2-beta

Released on November 26, 2022.

This the first version of agora-extension-beauty-effect. For detailed integration steps, refer to Beauty Effect.

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.

AI Noise Suppression

Agora charges additionally for this extension. See Pricing.

v2.0.1

Released on April 1, 2026.

Compatibility changes

This version no longer supports calling the disable method before pipe to disable the processor. Ensure that you call pipe before invoking disable.

New features

  • Added the setLogLevel method to the IAIDenoiserExtension interface class to set the log level for the plugin and WASM module.
  • Added the setLatency method to the IAIDenoiserProcessor interface class to configure latency for noise reduction processing.

Improvements

  • Updated the noise reduction algorithm for improved noise suppression, voice fidelity, and overall robustness.
  • Significantly improved voice fidelity after AI noise suppression in scenarios with sampling rates of 16 kHz and above.
  • Optimized CPU resource allocation strategy to enhance runtime efficiency.

API changes

The implementation of callbacks has been revised in this version. The original callbacks onloaderror, onoverload, ondump, and ondumpend are deprecated. Use the on method with event names "pipeerror", "overload", "dump", or "dumpend" to listen for the corresponding events instead.

v1.1.0

Improvement

This release improves the calculation performance of the AI-powered noise suppression algorithm.

New features

This release adds the following APIs and parameters:

  • APIs:
    • checkCompatibility: Checks whether the AI Noise Suppression extension is supported on the current browser.
    • setMode: Sets the noise suppression mode as AI noise suppression or stationary noise suppression.
    • setLevel: Sets the AI noise suppression level.
  • Parameters:
    • elapsedTime in onoverload: Reports the time in ms that the extension needs to process one audio frame.

For API details, see AI Noise Suppression.

Compatibility changes

This release brings the following changes:

  • AI Noise Suppression supports Agora Video SDK for Web v4.15.0 or later.
  • The extension has Wasm dependencies only. Because JS dependencies are removed, you need to publish the Wasm files located in the node_modules/agora-extension-ai-denoiser/external directory again. If you have enabled the Content Security Policy (CSP), you need to modify the CSP configuration. See AI Noise Suppression for details.
  • The audio data is dumped in PCM format instead of WAV format.
  • To adjust the intensity of noise suppression, best practice is to call setLevel.

v1.0.0

First release.

Noise suppression for use cases involving AI

v1.0.0-beta2

agora-conversational-ai-denoiser v1.0.0-beta2 was released on March 5, 2025, to enhance the user experience in applications powered by Agora Conversational AI Engine.

The agora-conversational-ai-denoiser plugin has high CPU usage. Agora recommend using it only for AI-related use cases.

Key features:

  • Significantly improved voice protection, especially for singing.
  • Reduced risk of audio capture and playback stuttering during operation.
  • When AI noise suppression is enabled, the default maximum AGC gain is reduced from 24dB to 12dB.

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved