Voice SDK for Web v4.20.2

This document only applies to the Agora Web SDK 4.x, which refactors the Web SDK 3.x and is not backward compatible. See the introduction and migration guide of the Web SDK 4.x.

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.

The AgoraRTCError objects of the SDK extend from the browser's Error objects. To print the error code in the browser console, you need to use AgoraRTCError.code. Printing an AgoraRTCError object only shows the error message.

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.