Release Notes

This page provides the release notes for the Agora Web SDK 4.x.

Overview

The Web SDK 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 and interactive live streaming services.

Compatibility

See Web SDK Compatibility.

Known issues

Chrome deprecates and removes the Plan B dialect

Chrome plans to deprecate and remove the Plan B dialect in WebRTC. For details, see the Chrome feature description. This change affects the following Agora Web SDK versions:

Web SDK version	Impact
v2.5.0-2.9.0 v3.0.0-3.6.1	After a stream is published, the method call of switchDevice causes video freezes or no sound issues.
v4.0.0-4.0.1	The publish and subscribe methods do not take effect.

If you use any of the above SDK versions, Agora recommends that you upgrade the SDK to the latest version.

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

Checking the visibility of the <video> HTML tag

After you call play, the SDK creates an <video> HTML tag for playing video tracks. v4.8.0 adds the following methods and events for checking the visibility of the <video> tag:

• localVideoTrack.on("video-element-visible-status")
• remoteVideoTrack.on("video-element-visible-status")
• localVideoTrack.getVideoElementVisibleStatus
• remoteVideoTrack.getVideoElementVisibleStatus

When localTrack.isPlaying or remoteTrack.isPlaying is true but you cannot see any video, the above methods or events can help you check whether the <video> tag is visible or not and learn the reason when the <video> tag is invisible.

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

Added

• localVideoTrack.on("video-element-visible-status")
• remoteVideoTrack.on("video-element-visible-status")
• localVideoTrack.getVideoElementVisibleStatus
• remoteVideoTrack.getVideoElementVisibleStatus

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 an audio or video call was interrupted, the Web SDK failed to resume playing the remote media.

v4.7.2

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

• Avoided the issue that on the Safari browser in iOS 15, after an audio or video call was interrupted by a phone call, the Web SDK might fail to resume sending the local media and playing the remote media.
• Avoided the black screen issue that might occur when using videoTrack.play(element, {mirror: true}) to play the video on the desktop or mobile Safari 15 browser.
• 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 Web SDK 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 Web SDK 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:

• After the method call of localVideoTrack.setEnabled(false) to stop sending video, the SDK also immediately turns off the camera light and stops video capture, while localVideoTrack.setMuted does not stop video capture.
• Calling setEnabled(true) takes longer to resume sending the media data than by than calling setMuted(false).

For more information, see What are the differences between setEnabled and setMuted?

Improvements

Dealing with autoplay blocking

To deal with the autoplay blocking of video on iOS, v4.6.0 deprecates the onAudioAutoplayFailed callback, and adds the onAutoplayFailed callback instead to indicate an audio or video autoplay failure.

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 scenario 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 Media Stream Encryption.

Network geofencing

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

The preset video encoder configurations for screen sharing

v4.5.0 adds the following preset video encoder configurations for screen sharing in ScreenEncoderConfigurationPreset:

• "480p_3": The resolution is 640 × 480 and the frame rate is 15 fps.
• "720p_3": The resolution is 1280 × 720 and the frame rate is 15 fps.
• "1080p_3": The resolution is 1920 × 1080 and the frame rate is 15 fps.

Issues fixed

v4.5.0 fixes the following issues:

• The OptimizationMode setting did not take effect.
• On iOS, when the Web SDK captures media, noises might occur on the local client.
• On Firefox, after the stream transmitted by the SDK switched from high quality to low quality, the video resolution obtained by the getRemoteVideoStats method was still the resolution of the high-quality stream.
• 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 scenarios 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

v4.4.0 adds the client.on("is-using-cloud-proxy") event. The SDK triggers this event after the local client successfully publishes a media stream to indicate whether the media stream is forwarded by the cloud proxy service.

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 Web SDK in environments with restricted network access. The optimized Agora cloud proxy service also supports regional connection.

You can contact support@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 Use Cloud Proxy.

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 scenarios that have regional restrictions.

Video transmission optimization strategy

This release adds the localVideoTrack.setOptimizationMode method for setting the video transmission optimization mode:

• "balanced": Uses the default transmission optimization strategy.
• "detail": Prioritizes clarity.
• "motion": Prioritizes smoothness.

See the API reference for the introduction to each transmission optimization mode. This method applies to scenarios where you need to dynamically adjust the optimization mode during a video call, live streaming, or screen sharing. For example, during the screen sharing, before you change the shared content from slides to a video, you can change the optimization mode from "detail" to "motion" to ensure smoothness in poor network conditions.

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 disabling an audio or video tracks by calling setEnabled, you can still call setDevice to switch devices.
• 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.

Fixed issues

• When you disabled a local video track, you could not publish another video track.
• After enabling dual-stream mode, if you called setEnabled(false) to disable a video track during the process of publishing, the publishing failed and could not be recovered.
• 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.
• After unpublishing a local camera video track and then publishing a screen-sharing track, the video bitrate was fixed at around 700 Kbps, and the resolution and frame rate dropped.
• 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
• localVideoTrack.setOptimizationMode
• 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.
• The method call of createCameraVideoTrack did not stop on Safari when the SDK cannot find a video capture device.
• After calling unsubscribe to unsubscribing from an unpublished track of a remote user, the subsequent subscribing and unsubscribing operations failed to take effect.
• Reduced the performance degradation due to frequent method calls of setEnabled to enable and disable a video track in dual-stream mode.
• Occasional errors when client.getLocalVideoStats was called on Safari.

v4.1.0

v4.1.0 was released on September 4, 2020.

New features

Screenshot capture

v4.1.0 adds the getCurrentFrameData method which gets the data of the video frame being rendered.

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.

Fixed issues

• Information retrieved by checkVideoTrackIsActive on Safari is inaccurate.
• 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

• LocalVideoTrack.getCurrentFrameData
• RemoteVideoTrack.getCurrentFrameData
• AgoraRTC.getPlaybackDevices
• LocalAudioTrack.setPlaybackDevice
• RemoteAudioTrack.setPlaybackDevice
• AgoraRTC.onPlaybackDeviceChanged
• Client.getLocalAudioStats
• Client.getRemoteAudioStats
• Client.getLocalVideoStats
• Client.getRemoteVideoStats

Deprecated

• The LocalTrack.getStats and RemoteTrack.getStats methods. Use the Client.getLocalAudioStats, Client.getRemoteAudioStats, Client.getLocalVideoStats and Client.getRemoteVideoStats methods instead.

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.
• After you call setMute(true), the SDK sends black video frames or silenced audio frames. If you mute a local video track, the camera light stays on, which might adversely impact the user experience. In contrast, if you disable a local video track by calling setEnabled(false), the SDK immediately turns off the camera and stops capturing video.

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

New features

Video encoding strategy

v4.0.0 adds the optimizationMode property in the CameraVideoTrackInitConfig, ScreenVideoTrackInitConfig, and CustomVideoTrackInitConfig interfaces. When creating a video track by calling createCameraVideoTrack, createCustomVideoTrack, or createScreenVideoTrack, you can choose whether to prioritize video quality or smoothness by setting optimizationMode as the following:

• "detail": Prioritizes video quality.
  • The SDK ensures high-quality images by automatically calculating a minimum bitrate based on the capturing resolution and frame rate. No matter how poor the network condition is, the sending bitrate will never be lower than the minimum value.
  • In most cases, the SDK does not reduce the sending resolution, but may reduce the frame rate.
• "motion": Prioritizes video smoothness.
  • In poor network conditions, the SDK reduces the sending bitrate to minimize video freezes.
  • In most cases, the SDK does not reduce the frame rate, but may reduce the sending resolution.

The optimizationMode property of the video track created by calling createScreenVideoTrack is set as "detail" by default.

Improvements

• Redesigns the withAudio parameter in AgoraRTC.createScreenVideoTrack. In addition to enable and disable, you can also set withAudio as auto. In this setting, the SDK shares the audio, dependent on whether the browser supports this function.
• Does not allow setting the withAudio parameter as "all" any more to avoid code repetition. As of v4.0.0, you can only set withAudio as "audio" or "video". This change involves the following APIs:
  • The Client.subscribe method.
  • The Client.on("user-published") and Client.on("user-unpublished") callbacks.

Fixed issues

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.
• Periodic video blur when sharing the screen in "rtc" mode.
• 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
• The optimizationMode property in CameraVideoTrackInitConfig, ``ScreenVideoTrackInitConfig, and CustomVideoTrackInitConfig interfaces

Updated

• Adds the value of auto to the withAudio parameter in AgoraRTC.createScreenVideoTrack.
• 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 LocalVideoTrackStats.muteState property
• The RemoteAudioTrackStats.muteState property
• The RemoteVideoTrackStats.muteState property

Deleted

• The Client.on("user-mute-updated") callback
• The LocalTrack.setMute method
• The AgoraRTCRemoteUser.audioMuted property
• The AgoraRTCRemoteUser.videoMuted property
• The LocalTrack.getUserId method