Interface IAgoraRTCClient

Users in the same channel can talk to each other.

When joining a channel, the AgoraRTCClient.on("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") callback is triggered on the remote client.

When leaving the channel, the AgoraRTCClient.on("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") callback is triggered on each remote client in the channel.

After publishing the local tracks, the AgoraRTCClient.on("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.

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

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

category

Agora Core

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

category

Agora Core

After the local client unpublishes, the AgoraRTCClient.on("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.

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

• AgoraRTCClient.on("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"), 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);
})

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

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.

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

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.

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.

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.

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

Ensure that you enable the RTMP Converter service before using this function.

See Push Streams to the CDN for details.

Note:

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

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

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") 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}`);
  });
})

since

   4.1.0

Gets the statistics of a local audio track.

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.

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.

since

   4.2.0

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

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.

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

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

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

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

• 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 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") or AgoraRTCClient.on("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.

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

After calling this method, the SDK triggers the 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.

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.

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.

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