Agora Web SDK API Reference

The Agora Web SDK is a JavaScript library loaded by an HTML web page. The Agora Web SDK library uses APIs in the web browser to establish connections and control the communication and live broadcast services.

The Agora Web SDK supports all mainstream browsers, see Browser support for details. If you need to use the Agora Web SDK on mobile devices, see FAQ for more information.

AgoraRTC is the entry point for all the methods that can be called in Agora Web SDK.

AgoraRTC provides the following methods.

Method	Description
createClient	Creates a client object.
createStream	Creates a stream object.
getDevices	Enumerates the available media input and output devices.
getSupportedCodec	Gets the supported codec of the web browser.
checkSystemRequirements	Checks the web browser compatibility.

Client

Use the createClient method to create a Client object and get started.

For easier debugging, we recommend you enable the log upload by calling enableLogUpload before creating the client.

A Client object is a representation of a local or remote user in a call session, and provides access to much of the core AgoraRTC functionality, see the table below.

Method	Description
init	Initializes a client object.
off	Unbinds events.
join	Joins an AgoraRTC channel.
leave	Leaves an AgoraRTC channel.
publish	Publishes a local stream.
unpublish	Unpublishes the local stream.
subscribe	Subscribes to a remote stream.
unsubscribe	Unsubscribes from the remote stream.
setClientRole	Sets the role of the user (live mode only).
enableDualStream	Enables the dual-stream mode on the publisher side. The term dual streams refers to a hybrid of a high-bitrate, high-resolution video stream and a low-bitrate, a low-resolution video stream.
setLowStreamParameter	Sets the low-video stream profile if the dual-stream mode is enabled.
setRemoteVideoStreamType	When a remote user sends dual streams, this method decides on which stream to receive on the subscriber side.
setStreamFallbackOption	Use this method to set stream fallback option on the subscriber. Under poor network conditions, the SDK can choose to subscribe to the low-video stream or only the audio stream.
disableDualStream	Disables the dual-stream mode.
enableAudioVolumeIndicator	Enables the SDK to report the active speaker and his/her volume regularly.
startLiveStreaming	Sends a stream to a URL address and starts a CDN live streaming.
setLiveTranscoding	Sets the video layout and audio for CDN live. (CDN live only)
stopLiveStreaming	Removes the voice or video stream URL from a live broadcast and stops live streaming.
addInjectStreamUrl	Injects an online media stream to a live broadcast.
removeInjectStreamUrl	Removes the injected online media stream from a live broadcast.
startChannelMediaRelay	Starts to relay media streams across channels.
updateChannelMediaRelay	Updates the channels for media stream relay.
stopChannelMediaRelay	Stops the media stream relay.
startProxyServer	Enables cloud proxy.
stopProxyServer	Disables cloud proxy.
setEncryptionSecret	Enables the built-in encryption.
setEncryptionMode	Sets the encryption mode.
renewToken	Renews the token. If you have used Token when joining the channel, call this method to renew your Token when it expires.
renewChannelKey	Renews the channel key. If you have used channel key when joining the channel, call this method to renew your channel key when it expires.
getSystemStats	Retrieves the statistics of the system.
getRecordingDevices	Enumerates the audio input devices such as microphones.
getPlayoutDevices	Enumerates the audio output devices such as speakers.
getCameras	Enumerates the video input devices such as cameras.
getRemoteAudioStats	Retrieves the audio statistics of the remote streams.
getLocalAudioStats	Retrieves the audio statistics of the published local streams.
getRemoteVideoStats	Retrieves the video statistics of the remote streams.
getLocalVideoStats	Retrieves the video statistics of the published local streams.
getTransportStats	Retrieves the transmission statistics between the App and the Agora service.
getSessionStats	Retrieves the statistics of the session connection.
getConnectionState	Gets the connection state.

Stream

Call the createStream method to create a Stream object.

A Stream object represents a published local or remote media stream object in a call session, and provides methods for stream settings, listed in the table below.

Method	Description
init	Initializes the stream object.
play	Plays the audio or video stream.
stop	Stops playing the stream.
isPlaying	Checks whether the stream is playing.
close	Closes the media input device, for example a camera.
unmuteAudio	Enables the audio track in the stream.
muteAudio	Disables the audio track in the stream.
unmuteVideo	Enables the video track in the stream.
muteVideo	Disables the video track in the stream.
hasAudio	Retrieves the audio flag.
hasVideo	Retrieves the video flag.
getAudioLevel	Retrieves the current audio level.
getAudioTrack	Retrieves the audio track in the stream.
getVideoTrack	Retrieves the video track in the stream.
replaceTrack	Replaces the audio or video track in the local stream.
addTrack	Adds audio or video tracks to the stream.
removeTrack	Removes the audio or video tracks from the stream.
setAudioProfile	Sets the audio profile of the stream.
setAudioVolume	Sets the volume of the remote stream.
setAudioOutput	Sets the audio output device of the remote stream. You can use it to switch between the microphone and the speakerphone.
switchDevice	Switches the media input devices, for example microphones and cameras.
setVideoProfile	Sets the video profile of the stream.
setVideoEncoderConfiguration	Customizes the video encoder configuration.
setBeautyEffectOptions	Sets the image enhancement options.
setScreenProfile	Sets the screen profile in screen-sharing.
startAudioMixing	Starts audio mixing.
stopAudioMixing	Stops audio mixing.
pauseAudioMixing	Pauses audio mixing.
resumeAudioMixing	Resumes audio mixing.
adjustAudioMixingVolume	Adjusts the volume while audio mixing.
getAudioMixingDuration	Retrieves the duration (ms) of the audio mixing.
getAudioMixingCurrentPosition	Retrieves the playback position (ms) of the audio mixing.
setAudioMixingPosition	Sets the playback position of the audio mixing file to a different start position (by default played from the beginning).
playEffect	Plays a specified audio effect.
stopEffect	Stops playing a specified audio effect.
pauseEffect	Pauses a specified audio effect.
resumeEffect	Resumes playing a specified audio effect.
setVolumeOfEffect	Sets the volume of a specified audio effect.
preloadEffect	Preloads a specified audio effect file into the memory.
unloadEffect	Releases a specified preloaded audio effect from the memory.
getEffectsVolume	Gets the volume of all the audio effects.
setEffectsVolume	Sets the volume of all the audio effects.
stopAllEffects	Stops playing all audio effects.
pauseAllEffects	Pauses all audio effects.
resumeAllEffects	Resumes playing all audio effects.
getId	Retrieves the stream ID.
getStats	Retrieves the connection statistics of the stream.

Events

Use the Client.on and Stream.on methods to add event listeners for events dispatched by the Client and Stream methods.

Error Codes

The following table lists possible error codes that the SDK throws.

Error Code	Description	Solution
STREAM_ALREADY_PUBLISHED	The stream has already been published.	Call unpublish and then call publish again.
INVALID_LOCAL_STREAM	The stream is illegal.	Check whether the object passed to publish is the stream object created by createStream and whether it has been initialized by Stream.init.
INVALID_OPERATION	The user has failed to join the channel, or joined the same channel.	Ensure that the user has successfully joined the channel and the SDK is connected to Agora's edge server. To check the connection state, use getConnectionState.
PUBLISH_STREAM_FAILED	The user has failed to publish the stream.	Call unpublish and then call publish again.
PEERCONNECTION_FAILED	P2P connection failed.	Call unpublish and then call publish again.
STREAM_NOT_YET_PUBLISHED	The stream has not yet been published.	Ensure that you call unpublish after the publish method call succeeds, and check if you have repeatedly called unpublish.
INVALID_REMOTE_STREAM	The remote stream is illegal.	Check whether the object passed to subscribe is the stream object retrieved from the stream-added event.
NO_SUCH_REMOTE_STREAM	There is no such remote stream in the channel.	Subscribe to the remote stream after the stream-added event occurs. This error also occurs when the connection is lost or the user leaves the channel. Try joining the channel again.
INVALID_PARAMETER	Incorrect parameter type.	Find the invalid parameter in the console log of the browser.
UID_CONFLICT	The UID conflicts with other UIDs in the channel.	This error is caused by two clients joining the same channel with the same user ID in one browser window. Ensure that each user in the channel has a unique user ID.
IOS_NOT_SUPPORT	The iOS Safari browser does not support dual-stream mode.	Do not enable dual-stream mode on iOS.
STILL_ON_PUBLISHING	Cannot enable/disable dual-stream mode when publishing a stream.	Enable/disable dual-stream mode after the publish method call succeeds.
ENABLE_DUALSTREAM_FAILED	Failed to enable dual-stream mode.	Try calling enableDualStream again. If repeated attempts fail, it's probably because the system does not support dual-stream mode.
SHARING_SCREEN_NOT_SUPPORT	The screen-share function does not support dual-stream mode.	Do not enable dual-stream mode when sharing the screen.
HIGH_STREAM_NOT_VIDEO_TRACE	Unable to get the video track of the high-quality video stream when enabling dual-stream mode.	Use Stream.hasVideo to make sure that the local stream contains a video track.
DISABLE_DUALSTREAM_FAILED	Failed to disable dual-stream mode.	Try calling disableDualStream again. If repeated attempts fail, it's probably because dual-stream mode is not enabled.

The following table lists possible errors in the console log of the browser.

Error Code	Description
ERR_JOIN_CHANNEL_TIMEOUT(2002)	Timeout in joining the channel.
ERR_JOIN_BY_MULTI_IP(2004)	The current network has multiple IP addresses. The SDK will reconnect automatically. You can ignore this error.
ERR_FAILED(1)	General error (the reason is not classified specifically)
ERR_INVALID_VENDOR_KEY(101)	The specified App ID is invalid.
ERR_INVALID_CHANNEL_NAME(102)	The specified Channel Name is invalid.
ERR_DYNAMIC_KEY_TIMEOUT(109)	The authorization of current Channel Key or Token times out. Once a token is generated, you must use it to access Agora's service within 24 hours. Otherwise, the token times out and you can no longer use it.
ERR_NO_AUTHORIZED(110)	The current Channel Key or Token is invalid.
ERR_NO_ACTIVE_STATUS(116)	The current App ID is not activated.
ERR_INVALID_UID(117)	The UID is invalid.
ERR_DYNAMIC_KEY_EXPIRED(118)	(Before SDK v2.9.0) The current Channel Key or Token has expired, and is no longer valid.
ERR_STATIC_USE_DYNAMIC_KEY(119)	The static user has used the dynamic key.
ERR_DYNAMIC_USE_STATIC_KEY(120)	The dynamic user has used the static key.
K_TIMESTAMP_EXPIRED(2)	(SDK v2.9.0 or later) The Channel Key or Token has expired, and is no longer valid.

Warning Codes

Warning codes occur when the SDK encounters an error that might be recovered automatically. These are only notifications, and can generally be ignored.

Warn Code	Value	Description
WARN_NO_AVAILABLE_CHANNEL	103	No channel resources are available. Such as the server cannot allocate any channel resource.
WARN_LOOKUP_CHANNEL_TIMEOUT	104	A timeout when looking up the channel. When joining a channel, the SDK looks up the specified channel. The warning usually occurs when the network condition is too poor to connect to the server.
WARN_LOOKUP_CHANNEL_REJECTED	105	The server rejected the request to look up the channel. The server cannot process this request or the request is illegal.
WARN_OPEN_CHANNEL_TIMEOUT	106	A timeout when opening the channel. Once the specific channel is found, the SDK opens the channel. The warning usually occurs when the network condition is too poor to connect to the server.
WARN_OPEN_CHANNEL_REJECTED	107	The server rejected the request to open the channel. The server cannot process this request or the request is illegal.
WARN_REQUEST_DEFERRED	108	The user’s request is deferred.