This page provides the release notes for the Agora Web SDK 4.x.
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.
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 |
---|---|
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.14.0 was released on August 31, 2022. This release fixed the following issues:
decodeFrameRate
returned by the getRemoteVideoStats
method was 0.LocalVideoTrack.setBeautyEffect
to enable image enhancement, calling LocalVideoTrack.unpipe
caused an error.v4.13.0 was released on July 25, 2022.
Adding support for media processing extensions
As of v4.13.0, the SDK supports using media processing extensions on remote audio and video tracks (extension support for local audio and video tracks was added in v4.10.0).
Currently, Agora provides the following extension for remote audio tracks:
Extension | Description | Documentation |
---|---|---|
Spatial Audio Extension (Beta) | Enables a real-time audio blurring or air absorption effect for a user's audio based on the user's position relative to other users, which makes conversations more immersive. | Contact support@agora.io for full details. |
AI Denoiser and virtual background
The AI Denoiser extension and virtual background extension are converted from beta release to official release. To experience the AI Denoiser 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.
Added
RemoteAudioTrack.pipe
RemoteAudioTrack.unpipe
RemoteVideoTrack.pipe
RemoteVideoTrack.unpipe
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 SD-RTN™; if the attempt fails, the SDK automatically switches to TCP/TLS 443).
v4.12.1 was released on June 27, 2022. This release fixed the following issues:
v4.12.0 was released on June 15, 2022.
Media processing extensions
Media processing extensions have the following changes:
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 was released on May 9, 2022. This release fixed the following issues:
v4.11.0 was released on April 1, 2022.
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 SD-RTN™; 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")
.
Channel capacity improvement
As of v4.11.0, a single channel can support up to 128 concurrent online hosts, who can publish audio and video streams at the same time. The number of audience members in a channel is unlimited. Each host or audience member can subscribe to a maximum of 50 hosts at the same time.
To experience this improvement, contact support@agora.io.
v4.11.0 fixed the following issues:
Promise.finally
was called in the SDK.unpublish
without parameters caused the method call to fail.Added
AgoraRTCClient.massSubscribe
AgoraRTCClient.massUnsubscribe
AgoraRTCClient.on('published-user-list')
ERR_TOO_MANY_BROADCASTERS
ERR_TOO_MANY_SUBSCRIBERS
v4.10.2 was released on March 24, 2022. This release fixed the issue that calling join
in certain scenarios might cause proxy exceptions.
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 was released on March 11, 2022.
Adding support for media processing extensions
v4.10.0 supports using media processing extensions in the Web SDK. The following extensions are currently free to use during the beta period. For guidance on how to integrate and use the extensions, refer to the documentation listed in the following table:
Extension | Description | Documentation |
---|---|---|
Virtual Background Extension (Beta) | Enables users to replace their actual background with a solid color or custom image, or to blur their background. | Use the Virtual Background Extension |
AI Denoiser Extension (Beta) | Reduces many types of sudden noise and reduces vocal distortion when multiple people speak at the same time. | Use the AI Denoiser Extension |
Added
AgoraRTC.registerExtensions
LocalAudioTrack.pipe
LocalAudioTrack.unpipe
LocalVideoTrack.pipe
LocalVideoTrack.unpipe
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 was released on March 3, 2022. This release fixed several internal issues.
v4.9.1 was released on February 24, 2022. This release fixed several internal issues.
v4.9.0 was released on February 17, 2022.
Setting the video stream type of all remote users
v4.9.0 adds the setRemoteDefaultVideoStreamType
method. After you call enableDualStream
to enable dual-stream mode on the senders' clients, setRemoteDefaultVideoStreamType
enables receivers to choose whether to receive the high-quality or low-quality stream of all remote users.
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
.
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.
client.on("is-using-cloud-proxy")
event.v4.9.0 fixed the following issues:
play
to play a local video track and pass in a DOM element from another window, the SDK reported an error.Added
setRemoteDefaultVideoStreamType
client.on("join-fallback-to-proxy")
localVideoTrack.on("video-element-visible-status")
remoteVideoTrack.on("video-element-visible-status")
localVideoTrack.getVideoElementVisibleStatus
remoteVideoTrack.getVideoElementVisibleStatus
v4.8.2 was released on January 27, 2022. This release fixed the issue that on iOS WeChat, the video playback might go black after being interrupted by a screen lock.
v4.8.1 was released on January 6, 2022. This release fixed an internal issue.
v4.8.0 was released on December 29, 2021.
v4.8.0 made some internal improvements.
v4.8.0 fixed the following issues:
client.on("volume-indicator")
event was 0.setDevice
and then setEncoderConfiguration
, the SDK returns an error.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 was released on October 14, 2021, with the following changes:
videoTrack.play(element, {mirror: true})
to play the video on the desktop or mobile Safari 15 browser. AgoraRTC.checkSystemRequirements()
on the Edge browser only returned false
.v4.7.1 was released on September 13, 2021. This release fixed some issues on Safari 11 and iPad Chrome.
v4.7.0 was released on September 1, 2021.
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.
This release makes the following improvements:
getVolumeLevel
.This release fixed the following issues:
LocalAudioTrack.setVolume
to adjust the local volume, the local user could not perceive the volume change.LocalAudioTrack.setDevice
could get stuck in a pending state.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 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 was released on July 21, 2021. This release fixed an internal error.
v4.6.0 was released on July 16, 2021.
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:
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:
createClient
to create a client object, set the role
parameter as "audience"
and the level
parameter in clientRoleOptions
as 1
.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:
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.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?
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.
v4.6.0 fixes the following issues:
localAudioTrack.setVolume
did not take effect immediately.Added
localTrack.setMuted
onAutoplayFailed
clientRoleOptions
in ClientConfig
options
in the setClientRole
methodDeprecated
onAudioAutoplayFailed
v4.5.0 was released on May 25, 2021.
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.
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.v4.5.0 fixes the following issues:
OptimizationMode
setting did not take effect.getRemoteVideoStats
method was still the resolution of the high-quality stream.remoteAudioTrack.setVolume
to adjust the volume, if the playback was paused and then resumed, the volume changed back to the original one.LocalAudioTrack.setVolume
method did not take effect.Added
processExternalMediaAEC
clientRoleOptions
in ClientConfig
options
in the setClientRole
methodsalt
in the setEncryptionConfig
method"aes-128-gcm"
and "aes-256-gcm"
in EncryptionMode
excludedArea
in the setArea
methodv4.4.0 was released on April 2, 2021.
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.
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
.
v4.4.0 fixes the following issues:
"first-frame-decoded"
event for a remote audio track.AgoraRTC.checkSystemRequirement
was inaccurate.Added
client.on("is-using-cloud-proxy")
"aes-128-gcm"
and "aes-256-gcm"
in EncryptionMode
v4.3.0 was released on January 26, 2021.
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 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 was released on December 1, 2020.
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:
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
.
setEnabled
, you can still call setDevice
to switch devices.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.setEnabled(false)
to disable a video track during the process of publishing, the publishing failed and could not be recovered.BufferSourceAudioTrack
could be distorted.onMicrophoneChanged
, onCameraChanged
, or onPlaybackDeviceChanged
). The SDK only triggered these events for a subsequent device change.Added
AgoraRTC.setArea
localVideoTrack.setOptimizationMode
AgoraRTCClient.getRemoteNetworkQuality
Changed
mode
parameter in AgoraRTCClient.startProxyServer
from boolean
to number
v4.1.1 was released on October 27, 2020. This release fixed the following issues:
event_network_quality
event.createCameraVideoTrack
did not stop on Safari when the SDK cannot find a video capture device.unsubscribe
to unsubscribing from an unpublished track of a remote user, the subsequent subscribing and unsubscribing operations failed to take effect.setEnabled
to enable and disable a video track in dual-stream mode.client.getLocalVideoStats
was called on Safari.v4.1.0 was released on September 4, 2020.
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.network-quality
event.checkVideoTrackIsActive
on Safari is inaccurate.setEnabled
after leaving the channel.UNEXPECTED_RESPONSE: ERR_SUBSCRIBE_REQUEST_INVALID
error.Added
LocalVideoTrack.getCurrentFrameData
RemoteVideoTrack.getCurrentFrameData
AgoraRTC.getPlaybackDevices
LocalAudioTrack.setPlaybackDevice
RemoteAudioTrack.setPlaybackDevice
AgoraRTC.onPlaybackDeviceChanged
Client.getLocalAudioStats
Client.getRemoteAudioStats
Client.getLocalVideoStats
Client.getRemoteVideoStats
Deprecated
LocalTrack.getStats
and RemoteTrack.getStats
methods. Use the Client.getLocalAudioStats
, Client.getRemoteAudioStats
, Client.getLocalVideoStats
and Client.getRemoteVideoStats
methods instead.v4.0.1 was released on July 18, 2020. This release fixed the following issues:
v4.0.0 was released on July 15, 2020.
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:
Client.on("user-mute-updated")
callback when the remote user calls setMute
to change the mute state.Client.on("user-unpublished")
or Client.on("user-published")
callbacks when the remote user calls setEnabled
to enable or disable a track.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 thePromise
object.
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."motion"
: Prioritizes video smoothness.The
optimizationMode
property of the video track created by calling createScreenVideoTrack is set as"detail"
by default.
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. 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:Client.subscribe
method.Client.on("user-published")
and Client.on("user-unpublished")
callbacks.v4.0.0 fixed the following issues:
unpublish
, the SDK triggerred the Client.on("user-left")
callback on the remote side."rtc"
mode.publish
and unpublish
frequently.Client.on("network-quality")
callback was inaccurate.Added
Client.localTracks
interfaceLocalTrack.setEnabled
methodoptimizationMode
property in CameraVideoTrackInitConfig, ``ScreenVideoTrackInitConfig
, and CustomVideoTrackInitConfig
interfacesUpdated
auto
to the withAudio parameter in AgoraRTC.createScreenVideoTrack
."all"
from the mediaType parameter in Client.subscribe
.mediaType
parameter in the Client.on("user-published")
and Client.on("user-unpublished")
callbacks does report "all"
Deprecated
LocalAudioTrackStats.muteState
propertyLocalVideoTrackStats.muteState
propertyRemoteAudioTrackStats.muteState
propertyRemoteVideoTrackStats.muteState
propertyDeleted
Client.on("user-mute-updated")
callbackLocalTrack.setMute
methodAgoraRTCRemoteUser.audioMuted
propertyAgoraRTCRemoteUser.videoMuted
propertyLocalTrack.getUserId
method