Agora Web SDK API Reference

Parameters

• appid: string

  The App ID of your Agora project.

• channel: string

  A string that provides a unique channel name for the call. The length must be within 64 bytes. Supported character scopes:

  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".

• token: string | null

  The token generated at your server:

  • For low-security requirements: You can use the temporary token generated at Console. For details, see Get an RTC temporary token.
  • For high-security requirements: Set it as the token generated at your server. For details, see Authenticate Your Users with Tokens.

• Optional uid: UID | null

  The user ID, an integer or a string, ASCII characters only. Ensure this ID is unique. If you set the uid to null, the Agora server assigns a number uid and returns it in the Promise object.

  To ensure better end-user experience, Agora highly suggests not using a string as the user ID.

  Note:

  • All users in the same channel should have the same type (number or string) of uid.
  • If you use a number as the user ID, it should be a 32-bit unsigned integer with a value ranging from 0 to (2³²-1).
  • If you use a string as the user ID, the maximum length is 255 characters.
  • You can use string UIDs to interoperate with the Native SDK 2.8 or later. Ensure that the Native SDK uses the User Account to join the channel. See Use String User Accounts.

Returns Promise<UID>

A Promise object with the user ID.

• If you pass a number as the user ID, the SDK returns a number uid.
• If you pass a string as the user ID, the SDK returns a string uid.
• If you leave the uid parameter empty or set it as null, the Agora server assigns a number uid and returns it.

Returns Promise<void>

Parameters

• tracks: ILocalTrack | ILocalTrack[]

  Local tracks created by AgoraRTC.createMicrophoneAudioTrack / AgoraRTC.createCameraVideoTrack or other methods.

Returns Promise<void>

await client.subscribe(user，"audio");
user.audioTrack.play();

Parameters

• user: IAgoraRTCRemoteUser

  The remote user.

• mediaType: "video"

  The media type of the tracks to subscribe to.

  • "video": Subscribe to the video track only.
  • "audio": Subscribe to the audio track only.

Returns Promise<IRemoteVideoTrack>

When the subscription succeeds, the SDK adds the subscribed tracks to user.audioTrack and user.videoTrack. You can go on to call audioTrack.play or videoTrack.play to play the tracks.

The Promise object throws the TRACK_IS_NOT_PUBLISHED error if the specified tracks do not exist.

await client.subscribe(user，"audio");
user.audioTrack.play();

Parameters

• user: IAgoraRTCRemoteUser

  The remote user.

• mediaType: "audio"

  The media type of the tracks to subscribe to.

  • "video": Subscribe to the video track only.
  • "audio": Subscribe to the audio track only.

Returns Promise<IRemoteAudioTrack>

When the subscription succeeds, the SDK adds the subscribed tracks to user.audioTrack and user.videoTrack. You can go on to call audioTrack.play or videoTrack.play to play the tracks.

The Promise object throws the TRACK_IS_NOT_PUBLISHED error if the specified tracks do not exist.

await client.subscribe(user，"audio");
user.audioTrack.play();

Parameters

• user: IAgoraRTCRemoteUser

  The remote user.

• mediaType: "video" | "audio"

  The media type of the tracks to subscribe to.

  • "video": Subscribe to the video track only.
  • "audio": Subscribe to the audio track only.

Returns Promise<IRemoteTrack>

When the subscription succeeds, the SDK adds the subscribed tracks to user.audioTrack and user.videoTrack. You can go on to call audioTrack.play or videoTrack.play to play the tracks.

The Promise object throws the TRACK_IS_NOT_PUBLISHED error if the specified tracks do not exist.

Parameters

• Optional tracks: ILocalTrack | ILocalTrack[]

  The tracks to unpublish. If left empty, all the published tracks are unpublished.

Returns Promise<void>

Parameters

• user: IAgoraRTCRemoteUser

  The remote user.

• Optional mediaType: "video" | "audio"

  The media type of the tracks to unsubscribe from:

  • "video": Unsubscribe from the video track only.
  • “audio”: Unsubscribe from the audio track only.
  • empty: Unsubscribe from all the tracks published by the remote user.

Returns Promise<void>

The Promise object throws the TRACK_IS_NOT_SUBSCRIBED error if the specified tracks do not exist.

client.startChannelMediaRelay(config).then(() => {
  console.log("startChannelMediaRelay success");
}).catch(e => {
  console.log("startChannelMediaRelay failed", e);
})

Parameters

• config: IChannelMediaRelayConfiguration

  Configurations of the media stream relay.

Returns Promise<void>

A Promise object, which is resolved if the media relay starts successfully.

Returns Promise<void>

A Promise object, which is resolved if the relay stops successfully.

Parameters

• config: IChannelMediaRelayConfiguration

  Configurations of the media stream relay.

Returns Promise<void>

A Promise object, which is resolved if the update succeeds. If the update fails, the media relay state is reset, and you need to call startChannelMediaRelay again to restart the relay.

Returns Promise<void>

client.enableDualStream().then(() => {
  console.log("Enable Dual stream success!");
}).catch(err => {
  console.log(err);
})

Returns Promise<void>

Parameters

• streamParameter: LowStreamParameter

  The video profile of the low-quality video stream.

Returns void

Parameters

• streamType: RemoteStreamType

  The remote video stream type:

  • 0: High-bitrate, high-resolution video stream.
  • 1: Low-bitrate, low-resolution video stream.

Returns Promise<void>

Parameters

• uid: UID

  The ID of the remote user.

• streamType: RemoteStreamType

  The remote video stream type:

  • 0: High-bitrate, high-resolution video stream.
  • 1: Low-bitrate, low-resolution video stream.

Returns Promise<void>

Parameters

• uid: UID

  The ID of the remote user.

• fallbackType: RemoteStreamFallbackType

  The fallback option. See RemoteStreamFallbackType for details.

Returns Promise<void>

Parameters

• url: string

  The URL address to be injected to the ongoing live broadcast. ASCII characters only, and the string length must be less than 1024 bytes. Valid protocols are RTMP, HLS, and HTTP-FLV.

  • Supported audio codec type: AAC.
  • Supported video codec type: H264(AVC).

• config: InjectStreamConfig

  Configurations for the injected stream.

Returns Promise<void>

Returns Promise<void>

Parameters

• config: LiveStreamingTranscodingConfig

  Configurations for live transcoding. See LiveStreamingTranscodingConfig for details.

Returns Promise<void>

Parameters

• url: string

  The CDN streaming URL in the RTMP format. ASCII characters only.

• Optional transcodingEnabled: undefined | false | true

  Whether to enable live transcoding. Transcoding sets the audio and video profiles and the picture-in-picture layout for the stream to be pushed to the CDN. It is often used to combine the audio and video streams of multiple hosts in a CDN live stream.

  If set as true, setLiveTranscoding must be called before this method.

  • true: Enable transcoding.
  • false: (Default) Disable transcoding.

Returns Promise<void>

Parameters

• url: string

  The URL to be removed.

Returns Promise<void>

client.enableAudioVolumeIndicator();
client.on("volume-indicator", volumes => {
  volumes.forEach((volume, index) => {
    console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
  });
})

Returns void

Returns LocalAudioTrackStats

Returns LocalVideoTrackStats

Returns AgoraRTCStats

The statistics of the call.

Returns object

• [uid: string]: RemoteAudioTrackStats

Returns object

• [uid: string]: NetworkQuality

Returns object

• [uid: string]: RemoteVideoTrackStats

const result = await client.massSubscribe([{user:userA, mediaType:'audio'}, {user: userB, mediaType:'audio'}]);

for(const {track, mediaType, error} of result) {
  if(error) {
    console.error(error);
    continue;
  }

  if(track) {
    if(mediaType === 'audio') {
      track.play();
    }else{
      track.play(document.querySelector('.video-container'));
    }
  }
}

Parameters

• subscribeList: object[]

  The list of remote users to subscribe to. Each list entry contains the following information:

  • user: The remote user. See AgoraRTCRemoteUser.
  • mediaType: The media type of the tracks to subscribe to.
    • "video": Subscribe to this user's video track.
    • "audio": Subscribe to this user's audio track.

Returns Promise<object[]>

Normally, the returned list has the same length and order as subscribeList, and each list entry contains the following information:

• user: The remote user. See AgoraRTCRemoteUser.
• mediaType: The media type of the tracks subscribed to:
  • "video": The video track is subscribed to.
  • "audio": The audio track is subscribed to.
• track: The remote track. See RemoteTrack.
• error: The error message. If subscription of a user's audio and/or video tracks fails, the error message is returned through this parameter.

client.massUnsubscribe([{user:userA}, {user: userB}]);

Parameters

• unsubscribeList: object[]

  The list of remote users to unsubscribe from. Each list entry contains the following information:

  • user: The remote user. See AgoraRTCRemoteUser.
  • mediaType: The media type of the tracks to unsubscribe from.
    • "video": Unsubscribe from this user's video track.
    • "audio": Unsubscribe from this user's audio track.
    • empty: Unsubscribe from all the tracks published by this user.

Returns Promise<void>

Parameters

• token: string

  The new token.

Returns Promise<void>

Parameters

• reports: EventCustomReportParams[] | EventCustomReportParams

Returns Promise<void>

Parameters

• role: ClientRole

  The role of the user.

• Optional options: ClientRoleOptions

  The detailed options of a user, including user level.

Returns Promise<void>

Parameters

• encryptionMode: EncryptionMode

  The encryption mode.

• secret: string

  The encryption secret. ASCII characters only. When a user uses a weak secret, the SDK outputs a warning message to the Web Console and prompts the users to set 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. Due to browser encryption algorithm limitations, the secret length cannot exceed 62 characters. Agora recommends you use OpenSSL to generate the secret on your server. For details, see Media Stream Encryption.

• Optional salt: Uint8Array

  The salt. Only valid when you set the encryption mode as "aes-128-gcm2" or "aes-256-gcm2". Agora recommends you use OpenSSL to generate the salt on your server. For details, see Media Stream Encryption.

Returns void

Parameters

• license: string

Returns void

Parameters

• Optional mode: undefined | number

  Cloud proxy mode:

  • 3: The cloud proxy for the UDP protocol, that is, the Force UDP cloud proxy mode. In this mode, the SDK always transmits data over UDP.
  • 5: The cloud proxy for the TCP (encryption) protocol, that is, the Force TCP cloud proxy mode. In this mode, the SDK always transmits data over TLS 443.

Returns void

Returns void