Agora Web SDK API Reference

The Agora Web SDK provides a JavaScript and Typescript library. Powered by WebRTC, it enables you to establish and manage audio and video communications or live broadcast services from a web browser.

Ensure that you use the HTTPS protocol or localhost, otherwise the error WEB_SECURITY_RESTRICT occurs.

Global module

AgoraRTC is the entry point for all the methods provided by the Agora Web SDK. AgoraRTC provides the following methods:

Core methods

Method	Description
createClient	Creates a local client object.

Local audio and video methods

Method	Description
createMicrophoneAudioTrack	Creates an audio track from the audio sampled by a microphone.
createCameraVideoTrack	Creates a video track from the video captured by a camera.
createMicrophoneAndCameraTracks	Creates an audio track and a video track.
createScreenVideoTrack	Creates a video track for screen sharing.
createBufferSourceAudioTrack	Creates an audio track from an audio file.
createCustomAudioTrack	Creates a customized audio track.
createCustomVideoTrack	Creates a customized video track.

Media device methods

Method	Description
getDevices	Enumerates the media input and output devices available.
getCameras	Enumerates the video capture devices available, such as cameras.
getMicrophones	Enumerates the audio sampling devices available, such as microphones.
getPlaybackDevices	Enumerates the audio playback devices available, such as speakers.
getElectronScreenSources	Gets the sources for screen-sharing with Electron.

Logger methods

Method	Description
enableLogUpload	Enables log upload
disableLogUpload	Disables log upload
setLogLevel	Sets the output log level of the SDK

Global callbacks

Callback	Description
onCameraChanged	Occurs when a video capture device is added or removed.
onMicrophoneChanged	Occurs when an audio sampling device is added or removed.
onAudioAutoplayFailed	Occurs when the autoplay of an audio track fails.

Other methods

Method	Description
checkSystemRequirements	Checks the compatibility of the current browser.
getSupportedCodec	Gets the codecs that the browser supports.
createChannelMediaRelayConfiguration	Creates a ChannelMediaRelayConfiguration object

AgoraRTCClient

Call createClient to create an AgoraRTCClient object, which represents a local user in a voice or video communication or live broadcast. The AgoraRTCClient interface provides the major functions for a voice or video communication or live broadcast.

Method	Description
join	Joins a channel.
leave	Leaves a channel.
publish	Publishes local audio and/or video tracks to a channel.
unpublish	Unpublishes the local audio and/or video tracks.
subscribe	Subscribes to the audio and/or video tracks of a remote user.
unsubscribe	Unsubscribes from the audio and/or tracks of a remote user.

LocalTrack

localTrack is the abstract interface that defines local audio and video tracks and can be used for playing and publishing audio and video.

You can call different methods to create different local track objects based on the derived interfaces of localTrack:

Local audio tracks

The SDK provides the following three kinds of local audio tracks. LocalAudioTrack is derived from LocalTrack; MicrophoneAudioTrack and BufferSourceAudioTrack is derived from LocalAudioTrack.

Local Audio Track	Description
LocalAudioTrack	The basic interface for local audio tracks, providing the main methods of managing local audio, such as playing and setting volume. Created by calling AgoraRTC.createCustomAudioTrack.
MicrophoneAudioTrack	The interface for the audio sampled by a local microphone, adding functions such as switching devices. Created by calling AgoraRTC.createMicrophoneAudioTrack.
BufferSourceAudioTrack	The interface for the audio from a local audio file, adding functions for controlling the processing of the audio buffer. Created by calling AgoraRTC.createBufferSourceAudioTrack.

Local video tracks

The SDK provides the following two kinds of local video tracks. LocalVideoTrack is derived from LocalTrack, and CameraVideoTrack is derived from LocalVideoTrack.

Local Video Track	Description
LocalVideoTrack	The basic interface for local video tracks, providing the main methods for managing local video, such as playing and applying image enhancement. Created by calling AgoraRTC.createCustomVideoTrack or AgoraRTC.createScreenVideoTrack.
CameraVideoTrack	The interface for the video captured by a local camera, adding functions such as switching devices and adjusting video encoder configurations. Created by calling AgoraRTC.createCameraVideoTrack.

RemoteTrack

RemoteTrack is the abstract interface that defines remote audio and video tracks.

To get a remote track: Call subscribe to subscribe to a remote user, and then get the RemoteAudioTrack track and the RemoteVideoTrack track from AgoraRTCRemoteUser. Both RemoteAudioTrack and RemoteVideoTrack are derived from RemoteTrack.

Import the SDK

If you use <script> to import the Agora Web SDK, you can call AgoraRTC.createClient to get the exported modules.

If you use npm to import the SDK, see the following code:

import AgoraRTC from "agora-web-sdk-ng"
console.log(AgoraRTC.createClient);

Typed modules (for Typescript)

Agora provides a .d.ts file for Typescript developers to export all type definitions. After integrating the SDK through npm, you can find the file under node_modules/agora-rtc-sdk-ng. See Global for all the modules and types that the Agora Web SDK exports.

import AgoraRTC, { IAgoraRTCClient } from "agora-rtc-sdk-ng";

const client: IAgoraRTCClient = AgoraRTC.createClient();

Error codes

The Agora Web SDK may throw an error code in the following scenarios:

• When the promise that the SDK returns to notify the result of an asynchronous operation is rejected, the SDK throws an error code.
• When a synchronous method fails, the SDK directly throws an error.
• The SDK may also throw some network-related error codes during its runtime.

This page lists the error codes that the SDK may throw and provides solutions accordingly.

General error codes

Error code	Description	Solution
UNEXPECTED_ERROR	Unexpected error that the SDK cannot handle. In most cases, this error has a more detailed error message.	Check the detailed error message.
UNEXPECTED_RESPONSE	The server returns an unexpected response. In most cases, the SDK throws this error when the state of clients is inconsistent with Agora servers due to poor network conditions.	Retry after the network recovers.
INVALID_PARAMS	Incorrect parameter.	Pass in a correct parameter according to the API reference.
NOT_SUPPORTED	Not supported by the browser.	See Browser Support.
INVALID_OPERATION	Illegal operation, usually because you cannot perform this operation in the current state.	Check if there is any precondition for your operation. For example, you must join a channel before publishing a track.
OPERATION_ABORTED	The operation is aborted because the SDK fails to communicate with Agora servers due to poor network conditions or disconnection.	Check the local network quality by listening for the AgoraRTCClient.on("user-joined") event and retry.
WEB_SECURITY_RESTRICT	Browser security policy restrictions.	Ensure that the webpage runs in the security context.
NO_ACTIVE_STATUS	Your project is not active or disabled.	Log into Agora Console to check whether the status of your project is active.

Request-related error codes

Network connection

Error code	Description	Solution
NETWORK_TIMEOUT	Timeout because the SDK fails to communicate with Agora servers due to poor network conditions or disconnection.	Check the local network quality by listening for the AgoraRTCClient.on("user-joined") event and retry.
NETWORK_RESPONSE_ERROR	An error occurs in the server response.	Pass in a correct parameter according to the API document.
NETWORK_ERROR	Fails to locate the network error.	None

Internal request to Agora servers

Error code	Description	Solution
WS_ABORT	WebSocket disconnected when requesting for the Agora servers.	Listen for the AgoraRTCClient.on("connection-state-change") event. Retry when the connection state changes to CONNECTED.
WS_DISCONNECT	WebSocket disconnected before requesting for the Agora servers	Listen for the AgoraRTCClient.on("connection-state-change") event. Retry when the connection state changes to CONNECTED.
WS_ERR	WebSocket connection error.	Check whether the current browser supports WebSocket.

Device-related error codes

Error code	Description	Solution
ENUMERATE_DEVICES_FAILED	Fails to enumerate local devices, usually due to browser restrictions.	None
DEVICE_NOT_FOUND	Fails to find the specified device.	Pass in the correct device ID.

Track-related error codes

Error code	Description	Solution
TRACK_IS_DISABLED	The track is disabled, usually because you have called Track.setEnabled(false) to disable the track.	Call Track.setEnabled(true) to enable the track and retry.
SHARE_AUDIO_NOT_ALLOWED	The end user does not click Share Audio.	Requests the end user to check Share Audio in the pop-up window for screen sharing.
CHROME_PLUGIN_NO_RESPONSE	No response from Agora's Chrome Extension for Screen Sharing	Check the status of the Chrome Extension for Screen Sharing or reinstall the extension.
CHROME_PLUGIN_NOT_INSTALL	Agora's Chrome Extension for Screen Sharing has not been installed.	Install the Chrome Extension for Screen Sharing.
MEDIA_OPTION_INVALID	Invalid parameter for media capturing.	Modify the parameter for media capturing or use the preset configuration.
CONSTRAINT_NOT_SATISFIED	Invalid parameter for media capturing.	Modify the parameter for media capturing or use the preset configuration.
PERMISSION_DENIED	Fails to get access to the media device.	Click Allow in the pop-up window for acquiring device permissions
NOT_READABLE	Although the user granted device permission, access to the media device is prevented.	Check whether an error occurred at the capturing device or driver level.
FETCH_AUDIO_FILE_FAILED	Fails to download the online audio file.	Check the URL of the online audio file and make sure it is accessible.
READ_LOCAL_AUDIO_FILE_ERROR	Fails to read the local audio file.	Check the path to the online audio file.
DECODE_AUDIO_FILE_FAILED	Fails to decode the audio file mainly because the codec of the audio file is not supported by WebAudio.	Check whether the codec of the audio file is supported by WebAudio.

Client-related error codes

Joining a channel

The following table lists the error codes that the SDK throws when the operation of joining a channel fails.

Error code	Description	Solution
UID_CONFLICT	Duplicate UIDs in the channel.	Rejoin the channel with a different UID.
INVALID_UINT_UID_FROM_STRING_UID	Agora's service for allocating a UID returns an illegal number for UID.	Rejoin the channel with a different UID.
CAN_NOT_GET_PROXY_SERVER	Fails to get the IP addresses of the cloud proxy service.	None
CAN_NOT_GET_GATEWAY_SERVER	Fails to get the IP addresses of the Agora servers.	None

Publishing/unpublishing

The following table lists the error codes that the SDK throws when the operation of publish or unpublishing a track fails.

Error code	Description	Solution
INVALID_LOCAL_TRACK	The LocalTrack object that you pass is illegal.	Check the LocalTrack object.
CAN_NOT_PUBLISH_MULTIPLE_VIDEO_TRACKS	Publishes multiple video tracks at the same time.	An AgoraRTCClient object can publish only one video track at the same time. If you want to publish multiple video tracks, please create multiple AgoraRTCClient object.

Subscribing/unsubscribing

The following table lists the error codes that the SDK throws when the operation of subscribing or unsubscribing to a remote user fails.

Error code	Description	Solution
INVALID_REMOTE_USER	The remote user may not be in the channel or have not yet published any tracks.	Re-subscribe to the remote user after receiving the AgoraRTCClient.on("user-published") event.
REMOTE_USER_IS_NOT_PUBLISHED	The remote user has not yet published a track of the media type that you specify. For example, you try to subscribe to a video track, but the remote user only publishes an audio video.	Check the media type that you specify when subscribing to a remote user is consistent with the type given in the AgoraRTCClient.on("user-published") event, or call AgoraRTCRemoteUser.hasVideo and AgoraRTCRemoteUser.hasAudio to check the type of the tracks that the remote user publishes before you subscribe to this remote user.
ERR_TOO_MANY_BROADCASTERS	The number of hosts in the channel exceeds the limit.	Control the number of hosts. For example, call Client.setClientRole to switch the user role to host only when the user needs to publish the audio and/or video tracks.
ERR_TOO_MANY_SUBSCRIBERS	The number of hosts that the user has subscribed to exceeds the limit.	Subscribe to a host only when necessary.

Pushing streams to CDN

The following table lists the error codes that the SDK throws when the operation of publishing streams to CDN fails.

Error code	Description	Solution
LIVE_STREAMING_TASK_CONFLICT	The streaming task exists.	First call Client.stopLiveStreaming to stop the current streaming task and retry.
LIVE_STREAMING_INVALID_ARGUMENT	Incorrect streaming parameters.	Check the parameters of your streaming operation according to the API description of Client.startLiveStreaming.
LIVE_STREAMING_INTERNAL_SERVER_ERROR	An internal error occurs in the dedicated Agora server for pushing streams.	Call Client.startLiveStreaming again. If the method call fails again, refresh the webpage and try again.
LIVE_STREAMING_PUBLISH_STREAM_NOT_AUTHORIZED	The target URL is occupied.	Check whether the URL is occupied or try a new URL.
LIVE_STREAMING_CDN_ERROR	An error occurs in the target CDN.	Check the status of the target CDN.
LIVE_STREAMING_INVALID_RAW_STREAM	Timeout.	Check whether the stream that you want push to CDN exists.

Media stream relay

The following table lists the error codes that the SDK throws when the operation of relaying media streams across channels fails.

Error code	Description
CROSS_CHANNEL_WAIT_STATUS_ERROR	An error occurs when triggering the AgoraRTCClient.on("channel-media-relay-state") state.
CROSS_CHANNEL_FAILED_JOIN_SRC	Fails to send the relay request.
CROSS_CHANNEL_FAILED_JOIN_DEST	Fails to accept the relay request.
CROSS_CHANNEL_FAILED_PACKET_SENT_TO_DEST	The Agora server fails to receive the media stream.
CROSS_CHANNEL_SERVER_ERROR_RESPONSE	An error occurs in the server response.