AgoraWebSDK NG API Docs

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.
  • Switch the version number in the drop-down box in the upper right corner to see the API reference of earlier versions.
  • 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.

    The Agora Web SDK is compatible with mainstream browsers. For details, see Compatibility.

    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. 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 a promise 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. None
    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 network-quality event and retry.
    WEB_SECURITY_RESTRICT Browser security policy restrictions. Ensure that the webpage runs in the security context.

    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 network-quality 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 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 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
    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

    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

    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

    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 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 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.

    Pushing streams to CDN

    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

    Error code Description
    CROSS_CHANNEL_WAIT_STATUS_ERROR An error occurs when triggering the "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.