Interface IAgoraRTCClient

An interface providing the local client with basic functions for a voice or video call, such as joining a channel, publishing tracks, or subscribing to tracks.

An AgoraRTCClient object is created by the [[createClient]] method.

interface IAgoraRTCClient {
    channelName?: string;
    connectionState: ConnectionState;
    localTracks: ILocalTrack[];
    remoteUsers: IAgoraRTCRemoteUser[];
    uid?: UID;
    disableDualStream(): Promise<void>;
    enableAudioVolumeIndicator(): void;
    enableDualStream(): Promise<void>;
    getListeners(event): Function[];
    getLocalAudioStats(): LocalAudioTrackStats;
    getLocalVideoStats(): LocalVideoTrackStats;
    getRTCStats(): AgoraRTCStats;
    getRemoteAudioStats(): {
        [uid: string]: RemoteAudioTrackStats;
    };
    getRemoteNetworkQuality(): {
        [uid: string]: NetworkQuality;
    };
    getRemoteVideoStats(): {
        [uid: string]: RemoteVideoTrackStats;
    };
    join(appid, channel, token, uid?): Promise<UID>;
    leave(): Promise<void>;
    massSubscribe(subscribeList): Promise<{
        error?: AgoraRTCError;
        mediaType: "audio" | "video";
        track?: IRemoteTrack;
        user: IAgoraRTCRemoteUser;
    }[]>;
    massUnsubscribe(unsubscribeList): Promise<void>;
    off(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    once(event, listener): void;
    presubscribe(uid, mediaType): Promise<IRemoteAudioTrack>;
    presubscribe(uid, mediaType): Promise<IRemoteVideoTrack>;
    presubscribe(uid, mediaType): Promise<IRemoteTrack>;
    publish(tracks): Promise<void>;
    removeAllListeners(event?): void;
    renewToken(token): Promise<void>;
    sendCustomReportMessage(reports): Promise<void>;
    setClientRole(role, options?): Promise<void>;
    setEncryptionConfig(encryptionMode, secret, salt?, encryptDataStream?): void;
    setImageModeration(enabled): Promise<void>;
    setImageModeration(enabled, config): Promise<void>;
    setLiveTranscoding(config): Promise<void>;
    setLowStreamParameter(streamParameter): void;
    setProxyServer(proxyServer): void;
    setRemoteDefaultVideoStreamType(streamType): Promise<void>;
    setRemoteVideoStreamType(uid, streamType): Promise<void>;
    setStreamFallbackOption(uid, fallbackType): Promise<void>;
    startChannelMediaRelay(config): Promise<void>;
    startLiveStreaming(url, transcodingEnabled?): Promise<void>;
    startProxyServer(mode?): void;
    stopChannelMediaRelay(): Promise<void>;
    stopLiveStreaming(url): Promise<void>;
    stopProxyServer(): void;
    subscribe(user, mediaType): Promise<IRemoteVideoTrack>;
    subscribe(user, mediaType): Promise<IRemoteAudioTrack>;
    subscribe(user, mediaType, channelId?): Promise<IRemoteTrack | IRemoteDataChannel>;
    unpublish(tracks?): Promise<void>;
    unsubscribe(user, mediaType?, channelId?): Promise<void>;
    updateChannelMediaRelay(config): Promise<void>;
}

Hierarchy

  • EventEmitter
    • IAgoraRTCClient

Agora Core

join leave publish subscribe unpublish unsubscribe

Channel Media Relay

startChannelMediaRelay stopChannelMediaRelay updateChannelMediaRelay

Dual Stream

disableDualStream enableDualStream setLowStreamParameter setRemoteDefaultVideoStreamType setRemoteVideoStreamType setStreamFallbackOption

Live Streaming

setLiveTranscoding startLiveStreaming stopLiveStreaming

Other

channelName? connectionState localTracks remoteUsers uid? enableAudioVolumeIndicator getListeners getLocalAudioStats getLocalVideoStats getRTCStats getRemoteAudioStats getRemoteNetworkQuality getRemoteVideoStats massSubscribe massUnsubscribe off on once presubscribe removeAllListeners renewToken sendCustomReportMessage setClientRole setEncryptionConfig setImageModeration

Proxy

setProxyServer startProxyServer stopProxyServer

Agora Core

join

  • join(appid, channel, token, uid?): Promise<UID>

  • Allows a user to join a channel.

    Users in the same channel can talk to each other.

    When joining a channel, the [AgoraRTCClient.on("connection-state-change")]event_connection_state_change callback is triggered on the local client.

    After joining a channel, if the user is in the communication profile, or is a host in the Live Broadcast profile, the [AgoraRTCClient.on("user-joined")]event_user_joined callback is triggered on the remote client.

    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: null | string

      The token generated at your server:

    • Optional uid: null | UID

      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.

      • If you use a number as the user ID, it should be a 32-bit unsigned integer with a value ranging from 0 to (232-1).
      • If you use a string as the user ID, the maximum length is 255 characters.
      To ensure a better end-user experience, Agora recommends using a number as the user ID.

      Note:

      • All users in the same channel should have the same type (number or string) of uid.
      • 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.
      • To ensure the data accuracy in Agora Analytics, Agora recommends that you specify uid for each user and ensure it is unique.

    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.

leave

  • leave(): Promise<void>

  • Leaves a channel.

    When leaving the channel, the [AgoraRTCClient.on("connection-state-change")]IAgoraRTCClient.event_connection_state_change callback is triggered on the local client.

    When a user (in the communication profile) or a host (in the live-broadcast profile) leaves the channel, the [AgoraRTCClient.on("user-left")]IAgoraRTCClient.event_user_left callback is triggered on each remote client in the channel.

    Returns Promise<void>

publish

  • publish(tracks): Promise<void>

  • Publishes local audio and/or video tracks to a channel.

    After publishing the local tracks, the [AgoraRTCClient.on("user-published")]event_user_published callback is triggered on the remote client.

    Note:

    • In an interactive live streaming, call setClientRole to set the user role as the host before calling this method.
    • You can call this method multiple times to add tracks for publishing.
    • An AgoraRTCClient object can publish multiple audio tracks. The SDK automatically mixes the audio tracks into one audio track. Exception: Safari does not support publishing multiple audio tracks on versions earlier than Safari 12.
    • An AgoraRTCClient object can publish only one video track. If you want to switch the published video track, for example, from a camera video track to a scree-sharing video track, you must unpublish the published video track.

    Parameters

    Returns Promise<void>

subscribe

  • subscribe(user, mediaType): Promise<IRemoteVideoTrack>

  • Subscribes to the audio and/or video tracks of a remote user.

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

    Parameters

    • user: IAgoraRTCRemoteUser | UID

      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]IAgoraRTCRemoteUser.audioTrack and [user.videoTrack]IAgoraRTCRemoteUser.videoTrack. You can go on to call [audioTrack.play]IRemoteAudioTrack.play or [videoTrack.play]IRemoteVideoTrack.play to play the tracks.

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

  • subscribe(user, mediaType): Promise<IRemoteAudioTrack>

  • Subscribes to the audio and/or video tracks of a remote user.

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

    Parameters

    • user: IAgoraRTCRemoteUser | UID

      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]IAgoraRTCRemoteUser.audioTrack and [user.videoTrack]IAgoraRTCRemoteUser.videoTrack. You can go on to call [audioTrack.play]IRemoteAudioTrack.play or [videoTrack.play]IRemoteVideoTrack.play to play the tracks.

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

  • subscribe(user, mediaType, channelId?): Promise<IRemoteTrack | IRemoteDataChannel>

  • Subscribes to the audio and/or video tracks of a remote user.

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

    Parameters

    • user: IAgoraRTCRemoteUser | UID

      The remote user.

    • mediaType: "audio" | "video" | "datachannel"

      The media type of the tracks to subscribe to.

      • "video": Subscribe to the video track only.
      • "audio": Subscribe to the audio track only.
      • "datachannel": Reserved for future use.
    • Optional channelId: number

    Returns Promise<IRemoteTrack | IRemoteDataChannel>

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

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

unpublish

  • unpublish(tracks?): Promise<void>

  • Unpublishes the local audio and/or video tracks.

    After the local client unpublishes, the [AgoraRTCClient.on("user-unpublished")]event_user_unpublished callback is triggered on each remote client in the channel.

    Note: In an interactive live streaming, after a host unpublishes the local tracks, the SDK does not automatically change the role of this host to the audience. To change the user role, you must call setClientRole.

    Parameters

    • Optional tracks: ILocalTrack | ILocalTrack[]

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

    Returns Promise<void>

unsubscribe

  • unsubscribe(user, mediaType?, channelId?): Promise<void>

  • Unsubscribes from the audio and/or video tracks of a remote user.

    Parameters

    • user: IAgoraRTCRemoteUser | UID

      The remote user.

    • Optional mediaType: "audio" | "video" | "datachannel"

      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.
      • "datachannel": Reserved for future use.
    • Optional channelId: number

      Reserved for future use.

    Returns Promise<void>

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

Channel Media Relay

startChannelMediaRelay

  • startChannelMediaRelay(config): Promise<void>

  • Starts relaying media streams across channels.

    After this method call, the SDK triggers the following callbacks:

    • [AgoraRTCClient.on("channel-media-relay-state")]event_channel_media_relay_state, which reports the state and error code of the media stream relay.
      • If the media stream relay fails, this callback returns state 3. Refer to code for the error code and call this method again.
    • [AgoraRTCClient.on("channel-media-relay-event")]event_channel_media_relay_event, which reports the events of the media stream relay.
      • If the media stream relay starts successfully, this callback returns code 4, reporting that the SDK starts relaying the media stream to the destination channel.

    Note:

    • Contact sales-us@agora.io to enable this function.
    • We do not support string user IDs in this API.
    • Call this method only after joining a channel.
    • In a live-broadcast channel, only a host can call this method.
    • To call this method again after it succeeds, you must call stopChannelMediaRelay to quit the current relay.
    client.startChannelMediaRelay(config).then(() => {
      console.log("startChannelMediaRelay success");
    }).catch(e => {
      console.log("startChannelMediaRelay failed", e);
    })

    Parameters

    Returns Promise<void>

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

stopChannelMediaRelay

  • stopChannelMediaRelay(): Promise<void>

  • Stops the media stream relay.

    Once the relay stops, the user leaves all the destination channels.

    Returns Promise<void>

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

updateChannelMediaRelay

  • updateChannelMediaRelay(config): Promise<void>

  • Updates the destination channels for media stream relay.

    After the channel media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call this method.

    Note:

    • Call this method after startChannelMediaRelay.
    • You can add a maximum of four destination channels to a relay.

    Parameters

    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.

Dual Stream

disableDualStream

  • disableDualStream(): Promise<void>

  • Disables dual-stream mode.

    Returns Promise<void>

enableDualStream

  • enableDualStream(): Promise<void>

  • Enables dual-stream mode.

    Enables dual-stream mode for the local stream. Dual streams are a hybrid of a high-quality video stream and a low-quality video stream:

    • High-quality video stream: High bitrate, high resolution.
    • Low-quality video stream: Low bitrate, low resolution. The default video profile of the low-quality stream is: A resolution (width × height) of 160 × 120 px, a bitrate of 50 Kbps, and a frame rate of 15 fps. Call setLowStreamParameter to customize the video profile of the low-quality stream.

    Note:

    • On some Android devices, the remote user may not be able to switch to the low-quality stream after you call enableDualStream.
    • On Android Chrome, the Web SDK cannot send high-quality and low-quality streams in H.264.
    • On Safari browsers of some Mac devices using Intel chips, calling enableDualStream to enable the dual-stream mode with H.264 encoding may cause system lag if the resolution ratio between the small and large streams is lower than 1/4.
    client.enableDualStream().then(() => {
      console.log("Enable Dual stream success!");
    }).catch(err => {
      console.log(err);
    })

    Returns Promise<void>

setLowStreamParameter

  • setLowStreamParameter(streamParameter): void

  • Sets the video profile of the low-quality video stream.

    If you have enabled the dual-stream mode by calling enableDualStream, use this method to set the low-quality video stream profile.

    If you do not set the low-quality video stream profile, the SDK assigns the default values based on your stream video profile.

    Note:

    • Due to different device and browser restrictions on video parameter settings, not all video parameters set with setLowStreamParameter will take effect:
      • On Firefox, frame rate settings do not take effect. The browser sets the frame rate at 30 fps. Additionally, on Mac Firefox 73+, the actual active frame rate value that take effects is smaller than the set value and there exist potential inaccuracies with the resolution.
      • On Safari 14 to 17.2, frame rate settings do not take effect. The browser sets the frame rate at around 15 fps, and the resolution of the low-quality stream must be proportional to the resolution of the high-quality stream. Additionally, setting LowStreamParameter.bitrate does not take effect on iOS Safari.
      • On some devices and browsers, the resolution you set may get adjusted by the browser. In this case, billings are calculated based on the actual resolution.

    Parameters

    Returns void

setRemoteDefaultVideoStreamType

  • setRemoteDefaultVideoStreamType(streamType): Promise<void>

  • Sets the video type of all of the remote stream.

    If a remote user enables dual-stream mode, after using this method, local client will subscribe the specified streamType by default. The local client subscribes to the high-quality video stream by default.

    • Agora suggests calling setRemoteDefaultVideoStreamType before joining the channel.
    • The method call of setRemoteVideoStreamType to set the video stream type of a specified remote user overrides this method.

    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>

setRemoteVideoStreamType

  • setRemoteVideoStreamType(uid, streamType): Promise<void>

  • Sets which video stream of a remote user to subscribe to.

    If a remote user enables dual-stream mode, the user sends a hybrid of a high-quality video stream and a low-quality video stream. Use this method to set which video stream to subscribe to. The local client subscribes to the high-quality video stream by default.

    • This method works only if the remote user has enabled the dual-stream mode (enableDualStream).
    • If both this method and setStreamFallbackOption are called, the actual video stream that the user subscribes to depends on your settings. The following are two cases:
      • If the parameter of setStreamFallbackOption is set to 0 (DISABLE), the video stream type that the user subscribes to is determined by the setting of setRemoteVideoStreamType.
      • If the parameter of setStreamFallbackOption is set to 1 (VIDEO_STREAM_LOW) or 2 (VIDEO_STREAM_HIGH), the video stream type that the user subscribes to is first set according to the setRemoteVideoStreamType setting, but is dynamically adjusted according to the network conditions. For example, if you set the setRemoteVideoStreamType parameter to 0 (subscribe to a high-quality video stream), but the network condition is poor, the SDK will perform a fallback operation according to the setStreamFallbackOption setting.

    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>

setStreamFallbackOption

  • setStreamFallbackOption(uid, fallbackType): Promise<void>

  • Sets the stream fallback option.

    Use this method to set the fallback option for the subscribed video stream. Under poor network conditions, the SDK can subscribe to the low-quality video stream or only to the audio stream.

    The SDK triggers the [AgoraRTCClient.on("stream-type-changed")]event_stream_type_changed callback when the remote stream changes from a high-quality video stream to a low-quality video stream or vice versa, and triggers the [AgoraRTCClient.on("stream-fallback")]event_stream_fallback callback when the remote stream changes from a video stream to an audio stream or vice versa.

    • This method works only if the remote user has enabled the dual-stream mode by enableDualStream.
    • When the remote user enables the dual-stream mode, if setStreamFallbackOption is not called at the local client, the default stream fallback option is to automatically subscribes to the low-video stream under poor network conditions (RemoteStreamFallbackType is 1).

    Parameters

    Returns Promise<void>

Live Streaming

setLiveTranscoding

startLiveStreaming

  • startLiveStreaming(url, transcodingEnabled?): Promise<void>

  • Publishes the local stream to the CDN.

    See Push Streams to the CDN for details.

    Note:

    • This method adds only one stream HTTP/HTTPS URL address each time it is called.

    Parameters

    • url: string

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

    • Optional transcodingEnabled: boolean

      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>

stopLiveStreaming

  • stopLiveStreaming(url): Promise<void>

  • Removes a URL from CDN live streaming.

    This method removes only one URL address each time it is called. To remove multiple URLs, call this method multiple times.

    Parameters

    • url: string

      The URL to be removed.

    Returns Promise<void>

Other

Optional Readonly channelName

channelName?: string

The current channel name.

The value is undefined if the local user has not joined a channel.

Readonly connectionState

connectionState: ConnectionState

Connection state between the SDK and the Agora server.

Readonly localTracks

localTracks: ILocalTrack[]

Since


   4.0.0

The list of the local tracks that the local user is publishing.

  • After a success method call of [[publish]], the published track object is added to this list automatically.
  • After a success method call of [[unpublish]], the unpublished track object is removed from this list automatically.

Readonly remoteUsers

remoteUsers: IAgoraRTCRemoteUser[]

A list of the remote users in the channel, each of which includes the user ID and the corresponding track information.

The list is empty if the local user has not joined a channel.

Optional Readonly uid

uid?: UID

The ID of the local user.

The value is undefined if the local user has not joined a channel.

enableAudioVolumeIndicator

  • enableAudioVolumeIndicator(): void

  • Enables the volume indicator.

    This method enables the SDK to regularly report the local and remote users who are speaking and their volumes.

    After the volume indicator is enabled, the SDK triggers the [AgoraRTCClient.on("volume-indicator")]event_volume_indicator callback to report the volumes every two seconds, regardless of whether there are active speakers in the channel.

    If the local user leaves the channel and rejoins the channel, you need to call enableAudioVolumeIndicator again.

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

    Returns void

getListeners

  • getListeners(event): Function[]

  • Gets all the listeners for a specified event.

    Parameters

    • event: string

      The event name.

    Returns Function[]

getLocalAudioStats

  • getLocalAudioStats(): LocalAudioTrackStats

  • Returns LocalAudioTrackStats

    Since


       4.1.0

    Gets the statistics of a local audio track.

getLocalVideoStats

  • getLocalVideoStats(): LocalVideoTrackStats

  • Returns LocalVideoTrackStats

    Since


       4.1.0

    Gets the statistics of a local video track.

    Note: You cannot get the encodeDelay property on iOS 14.4 and earlier.

getRTCStats

  • getRTCStats(): AgoraRTCStats

  • Gets the statistics of the call.

    Returns AgoraRTCStats

    The statistics of the call.

getRemoteAudioStats

  • getRemoteAudioStats(): {
        [uid: string]: RemoteAudioTrackStats;
    }

  • Returns {
        [uid: string]: RemoteAudioTrackStats;
    }

    Since


       4.1.0

    Gets the statistics of remote audio tracks.

    Note: The statistics are calculated after subscribing the remote stream, which may take at most 3 seconds. You can call this method periodically.

getRemoteNetworkQuality

  • getRemoteNetworkQuality(): {
        [uid: string]: NetworkQuality;
    }

  • Returns {
        [uid: string]: NetworkQuality;
    }

    Since


       4.2.0

    Gets the network quality of all the remote users to whom the local user subscribes.

getRemoteVideoStats

  • getRemoteVideoStats(): {
        [uid: string]: RemoteVideoTrackStats;
    }

  • Returns {
        [uid: string]: RemoteVideoTrackStats;
    }

    Since


       4.1.0

    Gets the statistics of remote video tracks.

    Note: The statistics are calculated after subscribing the remote stream, which may take at most 3 seconds. You can call this method periodically.

massSubscribe

  • massSubscribe(subscribeList): Promise<{
        error?: AgoraRTCError;
        mediaType: "audio" | "video";
        track?: IRemoteTrack;
        user: IAgoraRTCRemoteUser;
    }[]>

  • Parameters

    • subscribeList: {
          mediaType: "audio" | "video";
          user: IAgoraRTCRemoteUser;
      }[]

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

      • user: The remote user. See [AgoraRTCRemoteUser]IAgoraRTCRemoteUser.
      • 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<{
        error?: AgoraRTCError;
        mediaType: "audio" | "video";
        track?: IRemoteTrack;
        user: IAgoraRTCRemoteUser;
    }[]>

    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]IAgoraRTCRemoteUser.
    • 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]IRemoteTrack.
    • error: The error message. If subscription of a user's audio and/or video tracks fails, the error message is returned through this parameter.

    Since


       4.11.0

    Subscribes to the audio and/or video tracks of multiple remote users at one time.

    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'));
        }
      }
    }

massUnsubscribe

  • massUnsubscribe(unsubscribeList): Promise<void>

  • Parameters

    • unsubscribeList: {
          mediaType?: "audio" | "video";
          user: IAgoraRTCRemoteUser;
      }[]

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

      • user: The remote user. See [AgoraRTCRemoteUser]IAgoraRTCRemoteUser.
      • 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>

    Since


       4.11.0

    Unsubscribes from the audio and/or video tracks of multiple remote users at one time.

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

off

  • off(event, listener): void

  • Removes the listener for a specified event.

    Parameters

    • event: string

      The event name.

    • listener: Function

      The callback that corresponds to the event listener.

    Returns void

on

  • on(event, listener): void

  • Parameters

    • event: "connection-state-change"

      The event name.

    • listener: ((curState, revState, reason?) => void)

      See [connection-state-change]event_connection_state_change.

        • (curState, revState, reason?): void

        • Occurs when the state of the connection between the SDK and the server changes.

          Parameters

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "user-joined"

      The event name.

    • listener: ((user) => void)

      See [user-joined]event_user_joined.

        • (user): void

        • Occurs when a remote user or host joins the channel.

          • In a communication channel, this callback indicates that another user joins the channel and reports the ID of that user. The SDK also triggers this callback to report the existing users in the channel when a user joins the channel.
          • In a live-broadcast channel, this callback indicates that a host joins the channel. The SDK also triggers this callback to report the existing hosts in the channel when a user joins the channel. Ensure that you have no more than 17 hosts in a channel.

          The SDK triggers this callback when one of the following situations occurs:

          • A remote user or host joins the channel by calling join.
          • A remote audience switches the user role to host by calling setClientRole after joining the channel.
          • A remote user or host rejoins the channel after a network interruption.

          Parameters

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "user-left"

      The event name.

    • listener: ((user, reason) => void)

      See [user-left]event_user_left.

        • (user, reason): void

        • Occurs when a remote user becomes offline.

          The SDK triggers this callback when one of the following situations occurs:

          • A remote user calls leave and leaves the channel.
          • A remote user has dropped offline. If no data packet of the user or host is received for 20 seconds, the SDK assumes that the user has dropped offline. A poor network connection may cause a false positive.
          • A remote user switches the client role from host to audience.

          In live-broadcast channels, the SDK triggers this callback only when a host goes offline.

          Parameters

          • user: IAgoraRTCRemoteUser

            Information of the user who is offline.

          • reason: string

            Reason why the user has gone offline.

            • "Quit": The user calls leave and leaves the channel.
            • "ServerTimeOut": The user has dropped offline.
            • "BecomeAudience": The client role is switched from host to audience.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "user-published"

      The event name.

    • listener: ((user, mediaType, config?) => void)

      See [user-published]event_user_published.

        • (user, mediaType, config?): void

        • Occurs when a remote user publishes an audio or video track.

          You can subscribe to and play the audio or video track in this callback. See subscribe and [RemoteTrack.play]IRemoteTrack.play.

          The SDK also triggers this callback to report the existing tracks in the channel when a user joins the channel.

          client.on("user-published", async (user, mediaType) => {
            await client.subscribe(user, mediaType);
            if (mediaType === "video") {
              console.log("subscribe video success");
              user.videoTrack.play("xxx");
            }
            if (mediaType === "audio") {
              console.log("subscribe audio success");
              user.audioTrack.play();
            }
          })

          Parameters

          • user: IAgoraRTCRemoteUser

            Information of the remote user.

          • mediaType: "audio" | "video" | "datachannel"

            Type of the track.

            • "audio": The remote user publishes an audio track.
            • "video": The remote user publishes a video track.
            • "datachannel": Reserved for future use.
          • Optional config: IDataChannelConfig

            Reserved for future use.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "user-unpublished"

      The event name.

    • listener: ((user, mediaType, config?) => void)

      See [user-unpublished]event_user_unpublished.

        • (user, mediaType, config?): void

        • Occurs when a remote user unpublishes an audio or video track.

          Parameters

          • user: IAgoraRTCRemoteUser

            Information of the remote user.

          • mediaType: "audio" | "video" | "datachannel"

            Type of the track.

            • "audio": The remote user unpublishes an audio track.
            • "video": The remote user unpublishes a video track.
          • Optional config: IDataChannelConfig

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "user-info-updated"

      The event name.

    • listener: ((uid, msg) => void)

      See [user-info-updated]event_user_info_updated.

        • (uid, msg): void

        • Reports the state change of users.

          In most cases, you only need to listen for [user-published]IAgoraRTCClient.event_user_published and [user-unpublished]IAgoraRTCClient.event_user_unpublished events for operations including subscribing, unsubscribing, and displaying whether the remote user turns on the camera and microphone. You do not need to pay special attention to user states since the SDK automatically handles user states.

          This event indicating the media stream of a remote user is active does not necessarily mean that the local user can subscribe to this remote user. The local user can subscribe to a remote user only when receiving the [user-published]IAgoraRTCClient.event_user_published event.

          Parameters

          • uid: UID

            The ID of the remote user.

          • msg: "mute-audio" | "mute-video" | "unmute-audio" | "unmute-video" | "enable-local-video" | "disable-local-video"

            The current user state. Note that the "enable-local-video" and "disable-local-video" states are only for synchronizing states with the clients that integrate the RTC Native SDK.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "media-reconnect-start"

      The event name.

    • listener: ((uid) => void)

      See [media-reconnect-start]event_media_reconnect_start.

        • (uid): void

        • Occurs when the SDK starts to reestablish the media connection for publishing and subscribing.

          Parameters

          • uid: UID

            The ID of the user who reestablishes the connection. If it is the local uid, the connection is for publishing; if it is a remote uid, the connection is for subscribing.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "media-reconnect-end"

      The event name.

    • listener: ((uid) => void)

      See [media-reconnect-end]event_media_reconnect_end.

        • (uid): void

        • Occurs when the SDK ends reestablishing the media connection for publishing and subscribing.

          Parameters

          • uid: UID

            The ID of the user who reestablishes the connection. If it is the local uid, the connection is for publishing; if it is a remote uid, the connection is for subscribing.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "stream-type-changed"

      The event name.

    • listener: ((uid, streamType) => void)

      See [stream-type-changed]event_stream_type_changed.

        • (uid, streamType): void

        • Occurs when the type of a remote video stream changes.

          The SDK triggers this callback when a high-quality video stream changes to a low-quality video stream, or vice versa.

          Parameters

          • uid: UID

            The ID of the remote user.

          • streamType: RemoteStreamType

            The new stream type:

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

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "stream-fallback"

      The event name.

    • listener: ((uid, isFallbackOrRecover) => void)

      See [stream-fallback]event_stream_fallback.

        • (uid, isFallbackOrRecover): void

        • Occurs when a remote video stream falls back to an audio stream due to unreliable network conditions or switches back to video after the network conditions improve.

          Parameters

          • uid: UID

            The ID of the remote user.

          • isFallbackOrRecover: "fallback" | "recover"

            Whether the remote media stream falls back or recovers:

            • "fallback": The remote media stream falls back to audio-only due to unreliable network conditions.
            • "recover": The remote media stream switches back to the video stream after the network conditions improve.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "channel-media-relay-state"

      The event name.

    • listener: ((state, code) => void)

      See [channel-media-relay-state]event_channel_media_relay_state.

        • (state, code): void

        • Occurs when the state of the media stream relay changes.

          The SDK reports the state and error code of the current media relay with this callback.

          If the media relay is in an abnormal state, you can find the error code in ChannelMediaRelayError (for example if the token has expired, or repeated reconnection attempts fail.)

          Parameters

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "channel-media-relay-event"

      The event name.

    • listener: ((event) => void)

      See [channel-media-relay-event]event_channel_media_relay_event.

        • (event): void

        • Reports events during a media stream relay.

          Parameters

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "volume-indicator"

      The event name.

    • listener: ((result) => void)

      See [volume-indicator]event_volume_indicator.

        • (result): void

        • Reports all the speaking local and remote users and their volumes.

          It is disabled by default. You can enable this callback by calling enableAudioVolumeIndicator. If enabled, it reports the users' volumes every two seconds regardless of whether there are users speaking.

          The volume is an integer ranging from 0 to 100. Usually a user with volume above 60 is a speaking user.

          client.on("volume-indicator", function(result){
              result.forEach(function(volume, index){
              console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
            });
          });

          Parameters

          • result: {
                level: number;
                uid: UID;
            }[]

            An object consisting of the following properties:

            • level: The volume of the speaking user, ranging from 0 to 100.
            • uid: The ID of the speaking user.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "crypt-error"

      The event name.

    • listener: (() => void)

      See [crypt-error]event_crypt_error.

        • (): void

        • Occurs when decryption fails.

          The SDK triggers this callback when the decryption fails during the process of subscribing to a stream. The failure is usually caused by incorrect encryption settings. See setEncryptionConfig for details.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "token-privilege-will-expire"

      The event name.

    • listener: (() => void)

      See [token-privilege-will-expire]event_token_privilege_will_expire.

        • (): void

        • Occurs 30 seconds before a token expires.

          You must request a new token from your server and call renewToken to pass a new token as soon as possible.

          client.on("token-privilege-will-expire", async function(){
            // After requesting a new token
            await client.renewToken(token);
          });

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "token-privilege-did-expire"

      The event name.

    • listener: (() => void)

      See [token-privilege-did-expire]event_token_privilege_did_expire.

        • (): void

        • Occurs when the token expires.

          You must request a new token from your server and call join to use the new token to join the channel.

          client.on("token-privilege-did-expire", async () => {
            // After requesting a new token
            await client.join(<APPID>, <CHANNEL NAME>, <NEW TOKEN>);
          });

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "network-quality"

      The event name.

    • listener: ((stats) => void)

      See [network-quality]event_network_quality.

        • (stats): void

        • Reports the network quality of the local user.

          After the local user joins the channel, the SDK triggers this callback to report the uplink and downlink network conditions of the local user once every two second.

          Agora recommends listening for this event and displaying the network quality.

          Parameters

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "live-streaming-error"

      The event name.

    • listener: ((url, err) => void)

      See [live-streaming-error]event_live_streaming_error.

        • (url, err): void

        • Occurs when an error occurs in CDN live streaming.

          After the method call of startLiveStreaming succeeds, the SDK triggers this callback when errors occur during CDN live streaming.

          You can visit err.code to get the error code. The errors that you may encounter include:

          • LIVE_STREAMING_INVALID_ARGUMENT: Invalid argument.
          • LIVE_STREAMING_INTERNAL_SERVER_ERROR: An error occurs in Agora's streaming server.
          • LIVE_STREAMING_PUBLISH_STREAM_NOT_AUTHORIZED: The URL is occupied.
          • LIVE_STREAMING_TRANSCODING_NOT_SUPPORTED: Sets the transcoding parameters when the transcoding is not enabled.
          • LIVE_STREAMING_CDN_ERROR: An error occurs in the CDN.
          • LIVE_STREAMING_INVALID_RAW_STREAM: Timeout for the CDN live streaming. Please check your media stream.

          Parameters

          • url: string

            The URL of the CDN live streaming that has errors.

          • err: AgoraRTCError

            The error details.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "live-streaming-warning"

      The event name.

    • listener: ((url, warning) => void)

      See [live-streaming-warning]event_live_streaming_warning.

        • (url, warning): void

        • Occurs when a warning occurs in CDN live streaming.

          After the method call of startLiveStreaming succeeds, the SDK triggers this callback when warnings occur during CDN live streaming.

          You can visit err.code to get the warning code. The warnings that you may encounter include:

          • LIVE_STREAMING_WARN_STREAM_NUM_REACH_LIMIT: Pushes stremas to more than 10 URLs.
          • LIVE_STREAMING_WARN_FAILED_LOAD_IMAGE: Fails to load the background image or watermark image.
          • LIVE_STREAMING_WARN_FREQUENT_REQUEST: Pushes stremas to the CDN too frequently.

          Parameters

          • url: string

            The URL of the CDN live streaming that has warnings.

          • warning: AgoraRTCError

            The warning details.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "exception"

      The event name.

    • listener: ((event) => void)

      See [exception]event_exception.

        • (event): void

        • Reports exceptions in the channel.

          Exceptions are not errors, but usually reflect quality issues.

          This callback also reports recovery from an exception.

          Each exception corresponds to a recovery event.

          Exception

          Code Message Exception
          1001 FRAMERATE_INPUT_TOO_LOW Captured video frame rate is too low
          1002 FRAMERATE_SENT_TOO_LOW Sent video frame rate is too low
          1003 SEND_VIDEO_BITRATE_TOO_LOW Sent video bitrate is too low
          1005 RECV_VIDEO_DECODE_FAILED Decoding received video fails
          2001 AUDIO_INPUT_LEVEL_TOO_LOW Sent audio volume is too low
          2002 AUDIO_OUTPUT_LEVEL_TOO_LOW Received audio volume is too low
          2003 SEND_AUDIO_BITRATE_TOO_LOW Sent audio bitrate is too low
          2005 RECV_AUDIO_DECODE_FAILED Decoding received audio fails

          Recoveries

          Code Message Recovery
          3001 FRAMERATE_INPUT_TOO_LOW_RECOVER Captured video frame rate recovers
          3002 FRAMERATE_SENT_TOO_LOW_RECOVER Sent video frame rate recovers
          3003 SEND_VIDEO_BITRATE_TOO_LOW_RECOVER Sent video bitrate recovers
          3005 RECV_VIDEO_DECODE_FAILED_RECOVER Decoding received video recovers
          4001 AUDIO_INPUT_LEVEL_TOO_LOW_RECOVER Sent audio volume recovers
          4002 AUDIO_OUTPUT_LEVEL_TOO_LOW_RECOVER Received audio volume recovers
          4003 SEND_AUDIO_BITRATE_TOO_LOW_RECOVER Sent audio bitrate recovers
          4005 RECV_AUDIO_DECODE_FAILED_RECOVER Decoding received audio recovers

          Parameters

          • event: {
                code: number;
                msg: string;
                uid: UID;
            }
            • code: number

              The event code.

            • msg: string

              The event message.

            • uid: UID

              The ID of the user who has experienced the exception or recovery event.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "is-using-cloud-proxy"

      The event name.

    • listener: ((isUsingProxy) => void)

      See [is-using-cloud-proxy]event_is_using_cloud_proxy.

        • (isUsingProxy): void

        • Parameters

          • isUsingProxy: boolean

            Whether the media stream is forwarded by the Agora cloud proxy service.

            • true: Forwarded by the Agora cloud proxy service.
            • false: Not forwarded by the Agora cloud proxy service.

          Returns void

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "join-fallback-to-proxy"

      The event name.

    • listener: ((proxyServer) => void)

      See [join-fallback-to-proxy]event_join_fallback_to_proxy.

        • (proxyServer): void

        • Parameters

          • proxyServer: string

            The server address used after the switch.

          Returns void

    Returns void

    Deprecated

    from 4.19.0.

  • on(event, listener): void

  • Parameters

    • event: "published-user-list"

      The event name.

    • listener: ((users) => void)

      See [published-user-list]event_published_user_list.

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "content-inspect-connection-state-change"

      The event name.

    • listener: ((preState, newState) => void)

      See [content-inspect-connection-state-change]event_content_inspect_connection_state_change.

        • (preState, newState): void

        • Parameters

          • preState: InspectState
          • newState: InspectState

          Returns void

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "content-inspect-error"

      The event name.

    • listener: ((error?) => void)

      See [content-inspect-error]event_content_inspect_error.

        • (error?): void

        • Parameters

          • Optional error: AgoraRTCError

          Returns void

    Returns void

  • on(event, listener): void

  • When the specified event happens, the SDK triggers the callback that you pass.

    Parameters

    • event: "image-moderation-connection-state-change"

      The event name.

    • listener: ((newState, preState) => void)

      See [image-moderation-connection-state-change]event_image_moderation_connection_state_change.

        • (newState, preState): void

        • Parameters

          • newState: ImageModerationConnectionState
          • preState: ImageModerationConnectionState

          Returns void

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "stream-message"

      The event name.

    • listener: ((uid, payload) => void)

      See [stream-message]event_stream_message.

        • (uid, payload): void

        • Callback for receiving the DataStream message.

          client.on("stream-message", (uid, payload) => {
             console.info(`received data stream message from ${uid}: `, payload);
          });

          Parameters

          • uid: UID

            UID of the message sender.

          • payload: Uint8Array

            Message content.

          Returns void

          As Member Of

          IAgoraRTCClient

          Group

          Events

    Returns void

  • on(event, listener): void

  • When the specified event happens, the SDK triggers the callback that you pass.

    Parameters

    • event: string

      The event name.

    • listener: Function

      The callback function.

    Returns void

once

  • once(event, listener): void

  • Listens for a specified event once.

    When the specified event happens, the SDK triggers the callback that you pass and then removes the listener.

    Parameters

    • event: string

      The event name.

    • listener: Function

      The callback to trigger.

    Returns void

presubscribe

  • presubscribe(uid, mediaType): Promise<IRemoteAudioTrack>

  • Parameters

    • uid: UID
    • mediaType: "audio"

    Returns Promise<IRemoteAudioTrack>

  • presubscribe(uid, mediaType): Promise<IRemoteVideoTrack>

  • Parameters

    • uid: UID
    • mediaType: "video"

    Returns Promise<IRemoteVideoTrack>

  • presubscribe(uid, mediaType): Promise<IRemoteTrack>

  • Parameters

    • uid: UID
    • mediaType: "audio" | "video"

    Returns Promise<IRemoteTrack>

removeAllListeners

  • removeAllListeners(event?): void

  • Removes all listeners for a specified event.

    Parameters

    • Optional event: string

      The event name. If left empty, all listeners for all events are removed.

    Returns void

renewToken

  • renewToken(token): Promise<void>

  • Renews the token.

    The token expires after a set time once token is enabled. When the SDK triggers the [AgoraRTCClient.on("token-privilege-will-expire")]event_token_privilege_will_expire callback, call this method to pass a new token. Otherwise the SDK disconnects from the server.

    Parameters

    • token: string

      The new token.

    Returns Promise<void>

sendCustomReportMessage

  • sendCustomReportMessage(reports): Promise<void>

  • Reports customized messages to Agora's data center.

    Temporarily, Agora supports reporting a maximum of 20 message pieces within 5 seconds.

    Parameters

    • reports: EventCustomReportParams | EventCustomReportParams[]

      Messages. You can report multiple messages one time.

      client.sendCustomReportMessage({
        reportId: "id1", category: "category1", event: "custom", label: "label1", value: 0,
      }).then(() => {
        console.log("send custom report success");
      }).catch(e => {
        console.error("send custom report error");
      });

    Returns Promise<void>

setClientRole

  • setClientRole(role, options?): Promise<void>

  • Sets the user role and level in a live streaming (when [mode]ClientConfig.mode is "live").

    • The user role determines the permissions that the SDK grants to a user, such as permission to publish local streams, subscribe to remote streams, and push streams to a CDN address. You can set the user role as "host" or "audience". A host can publish and subscribe to streams, while an audience member can only subscribe to streams. The default role in a live streaming is "audience". Before publishing tracks, you must call this method to set the user role as "host".
    • The detailed options of a user, including the user level. The user level determines the level of services that a user can enjoy within the permissions of the user's role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels affect prices.

    Note:

    • When [mode]ClientConfig.mode is "rtc", this method does not take effect and all users are "host" by default.
    • If the local client switches the user role after joining a channel, the SDK triggers the [AgoraRTCClient.on("user-joined")]event_user_joined or [AgoraRTCClient.on("user-left")]event_user_left callback on the remote client.
    • To switch the user role to "audience" after calling publish, call unpublish first. Otherwise the method call fails and throws an exception.

    Parameters

    Returns Promise<void>

setEncryptionConfig

  • setEncryptionConfig(encryptionMode, secret, salt?, encryptDataStream?): void

  • Sets the encryption configurations.

    Use this method to enable the built-in encryption before joining a channel.

    If the encryption configurations are incorrect, the SDK triggers the [AgoraRTCClient.on("crypt-error")]event_crypt_error callback when publishing tracks or subscribing to tracks.

    Notes:

    • All users in a channel must use the same encryption mode, secret, and salt.
    • You must call this method before joining a channel, otherwise the method call does not take effect and encryption is not enabled.
    • As of v4.7.0, after a user leaves the channel, the SDK automatically disables the built-in encryption. To re-enable the built-in encryption, call this method before the user joins the channel again.
    • Do not use this method for CDN live streaming.

    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.

    • Optional encryptDataStream: boolean

      Whether to encrypt the data stream.The encryption mode for the data stream must be consistent with the media stream. Currently, data stream encryption only supports "aes-128-gcm2" and "aes-256-gcm2" modes. Using other encryption modes will result in an error.

      • true: Enable data stream encryption.
      • false: Disable data stream encryption.

    Returns void

setImageModeration

  • setImageModeration(enabled): Promise<void>

  • Disables the third-party video moderation service.

    Parameters

    • enabled: false

      Default is false and can only be set to false.

    Returns Promise<void>

  • setImageModeration(enabled, config): Promise<void>

  • Enables and configures the third-party video moderation service.

    After calling this method, the SDK triggers the [image-moderation-connection-state-change]event_image_moderation_connection_state_change callback, and captures the snapshots of the locally sent video to send to the third-party service provider for moderation.

    • Before calling this method, make sure the following requirements are met:
      • You have activated the third-party video moderation service.
      • The local user has joined the channel, and the local video track has been published and enabled.

    Parameters

    • enabled: true

      Default is true and can only be set to true.

    • config: ImageModerationConfiguration

      Configuration for the video moderation service. See ImageModerationConfiguration.

    Returns Promise<void>

Proxy

setProxyServer

  • setProxyServer(proxyServer): void

  • Deploys your proxy server.

    Do not use this method and startProxyServer together. They have the following differences:

    • setProxyServer: This method allows you to use a custom proxy server for purposes including signaling transmission, log uploading, and event reporting. But it cannot be used for media transmission.
    • startProxyServer: This method provides Agora's cloud proxy service, which handles media and signaling transmission with simple setup. For more information, refer to [Using Cloud Proxy Service](https://docs.agora.io/en/ video-call-4.x/cloud_proxy_web_ng?platform=Web).

    Note:

    • Call this method before join.
    • Proxy services by different service providers may result in slow performance if you are using the Firefox browser. Therefore, Agora recommends using the same service provider for the proxy services. If you use different service providers, Agora recommends not using the Firefox browser.

    Parameters

    • proxyServer: string

      Your proxy server domain name. ASCII characters only.

    Returns void

startProxyServer

  • startProxyServer(mode?): void

  • Enables cloud proxy.

    You must call this method before joining the channel or after leaving the channel.

    For the extra settings required for using the cloud proxy service, see Use Cloud Proxy.

    Parameters

    • Optional mode: 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.

      Note: As of v4.15.0, the default value of mode is 3.

    Returns void

stopProxyServer

  • stopProxyServer(): void

  • Disables cloud proxy.

    You must call this method before joining the channel or after leaving the channel.

    Returns void

Settings

Member Visibility

Theme

On This Page

joinleavepublishsubscribeunpublishunsubscribestartChannelMediaRelaystopChannelMediaRelayupdateChannelMediaRelaydisableDualStreamenableDualStreamsetLowStreamParametersetRemoteDefaultVideoStreamTypesetRemoteVideoStreamTypesetStreamFallbackOptionsetLiveTranscodingstartLiveStreamingstopLiveStreamingchannelNameconnectionStatelocalTracksremoteUsersuidenableAudioVolumeIndicatorgetListenersgetLocalAudioStatsgetLocalVideoStatsgetRTCStatsgetRemoteAudioStatsgetRemoteNetworkQualitygetRemoteVideoStatsmassSubscribemassUnsubscribeoffononcepresubscriberemoveAllListenersrenewTokensendCustomReportMessagesetClientRolesetEncryptionConfigsetImageModerationsetProxyServerstartProxyServerstopProxyServer