Set the Subscribing State

In real-time engagement, you may need to set the subscribing state of audio and video streams according to your business scenarios. For example, after joining a channel, a user needs to unsubscribe from a remote user.

This article describes how to set the subscribing state in common scenarios.

This article applies to the SDK v3.3.0 and later.

If you have upgraded the SDK from an earlier version to v3.3.0 or later, Agora recommends that you adjust your subscribing settings by referring to API changes in order to avoid any impact on your business functions.

Subscribing to audio and video streams results in all associated usage costs.

By default, users subscribe to all remote users' audio and video streams when joining a channel or switching to a channel. You can call the following APIs to set the subscribing state:

API	Target	Requirements for calling the API
autoSubscribeAudio or autoSubscribeVideo of channelMediaOptions	All remote users	Set this API when calling joinChannel[2/2] or switchChannel[2/2]
muteAllRemoteAudioStreams or muteAllRemoteVideoStreams	All remote users	Call at any time in the channel
muteRemoteAudioStream or muteRemoteVideoStream	A specified remote user	Call at any time in the channel

In the channel, the methods with prefixes muteAll or muteRemote can override the subscribing settings when joining a channel or switching to a channel.

The methods with prefixes muteAll and muteRemote are independent of each other. When the two methods are called together, the method that is called later takes effect.

If the user subscribes to all remote users when joining a channel or switching to a channel, the user may need to unsubscribe from one or more remote users in the channel. Agora recommends the following steps:

1. Use the default settings of the SDK when joining a channel or switching to a channel.
2. In the channel, call muteRemoteAudioStream (uid, true) or muteRemoteVideoStream (uid, true) to unsubscribe from specified remote users.

Scenario two: Subscribe to specified users when joining a channel​

The user may need to subscribe to one or more remote users when joining a channel or switching to a channel. Agora recommends the following steps:

1. Call joinChannel[2/2] or switchChannel[2/2] and set autoSubscribeAudio(false) or autoSubscribeVideo(false) to unsubscribe from all remote users.
2. In the channel, call muteRemoteAudioStream (uid, false) or muteRemoteVideoStream (uid, false) to subscribe to specified remote users.

The user may need to subscribe to one or more remote users when joining a channel or switching to a channel, and then subsequently change the subscribed remote users. Agora recommends the following steps:

1. Refer to Scenario Two to subscribe to specified remote users when joining a channel or switching to a channel.
2. When the user needs to change the subscribed remote users, you can first call muteRemoteAudioStream(uid, true) or muteRemoteVideoStream(uid, true) to unsubscribe the remote users you no longer need, and then call muteRemoteAudioStream(uid, false) or muteRemoteVideoStream(uid, false) to subscribe to the remote users you need.

If all the subscribed remote users are different before and after the change, to simplify the code logic, you can call muteAllRemoteAudioStreams(true) and muteAllRemoteVideoStreams(true) to unsubscribe all remote users first, and then call muteRemoteAudioStream (uid, false) or muteRemoteVideoStream(uid, false) to subscribe to the remote users you need.

Using the mute method to unsubscribe a remote user and then immediately subscribe to that user can cause a momentary lag in that user's audio and video, so Agora recommends that you use muteRemote instead of muteAllRemote to unsubscribe if you have subscribed to a remote user both before and after changing.

In real-time engagement, the user may be interrupted by a system or third-party application event, such as receiving a system phone call. You typically need to set the subscribing state in two circumstances:

1. When the user starts using a system or third-party application and this application occupies the audio or video modules of the device, Agora recommends unsubscribing from all users.
2. When the user stops using a system or third-party application, Agora recommends resuming the original subscribing state.

The logic of subscribing settings varies according to the original subscribing state.

• If the user subscribes to all remote users in real-time engagement, Agora recommends setting the subscribing state as follows:

  • When the user starts using a system or third-party application, call muteAllRemoteAudioStreams(true) or muteAllRemoteVideoStreams(true) to unsubscribe from all remote users.
  • When the user stops using a system or third-party application, call muteAllRemoteAudioStreams(false) or muteAllRemoteVideoStreams(false) to resume subscribing to all remote users.

• If the user subscribes to some remote users in real-time engagement, Agora recommends setting the subscribing state as follows:

  • Record the original subscribing state. For example, the user only subscribes to remote users A and B.

  • When the user starts using a system or third-party application, call muteAllRemoteAudioStreams(true) or muteAllRemoteVideoStreams(true) to unsubscribe from all remote users.

  • When the user stops using system or third-party applications, resume the original subscribing state according to the records in step one. For example, call the following methods to resume subscribing to remote users A and B:

    • Call muteRemoteAudioStream(A, false) and muteRemoteVideoStream(A, false) to resume subscribing to remote user A.
    • Call muteRemoteAudioStream(B, false) and muteRemoteVideoStream(B, false) to resume subscribing to remote user B.

API changes​

As of v3.3.0, Agora adds joinChannel[2/2] and switchChannel[2/2], and modifies the logic for using mute-related methods. If you need to upgrade to v3.3.0 or later, Agora recommends that you adjust your subscribing settings as follows to avoid any impact on your business functions:

Earlier than v3.3.0:

• You cannot set the subscribing state when you join a channel or switch channels. By default, you subscribe to the audio or video streams in the current channel.

• mute-related methods can be called both before and after joining a channel or switching to a channel.

• The methods with the prefix muteAll (hereinafter referred to as muteAll) serve as a master switch, and the methods with the prefix muteRemote or setDefaultMute (hereinafter referred to asmuteRemote and setDefaultMute) serve as sub-switches.

• Call muteAll(true) to disconnect the master switch, and the user unsubscribes from all audio and video streams. muteRemote or setDefaultMute does not take effect.

• Call muteAll(false) to connect the master switch. muteRemote or setDefaultMute controls the user subscribing state.

  • Set true to disconnect the sub-switches, and the user unsubscribes from streams.
  • Set false to connect the sub-switches, and the user subscribes to streams.

• muteAll(false)does not resume subscribing to all audio or video streams, but only the original subscribing state.

As of v3.3.0:

• Deprecate setDefaultMuteAllRemoteAudioStreams and setDefaultMuteAllRemoteVideoStreams.
• When joining a channel or switching to a channel, call joinChannel[2/2] or switchChannel[2/2] to set the subscribing state.
• mute-related methods must be called after joining a channel or switching to a channel; otherwise these methods do not take effect.
• muteAll methods do not serve as a master switch. Each mute-related method can independently control the user's subscribing state.
  • When muteAll and muteRemote methods are called together, the method that is called later takes effect.
  • muteAll contains the function of setDefaultMute. Agora does not recommend calling muteAll and setDefaultMute together; otherwise the settings may not take effect.
• muteAll(false) resumes subscribing to all audio or video streams.

Java/C++	Objective-C	C#	Typescript/Dart
joinChannel[2/2]	joinChannelByToken[2/2]	JoinChannel[2/2]	joinChannel
switchChannel[2/2]	switchChannelByToken[2/2]	SwitchChannel[2/2]	switchChannel
muteAllRemoteAudioStreams	muteAllRemoteAudioStreams	MuteAllRemoteAudioStreams	muteAllRemoteAudioStreams
muteAllRemoteVideoStreams	muteAllRemoteVideoStreams	MuteAllRemoteVideoStreams	muteAllRemoteVideoStreams
muteRemoteAudioStream	muteRemoteAudioStream	MuteRemoteAudioStream	muteRemoteAudioStream
muteRemoteVideoStream	muteRemoteVideoStream	MuteRemoteVideoStream	muteRemoteVideoStream