Skip to main content

You are looking at Video Calling v3.x Docs. The newest version is  Video Calling v4.x

Set the Subscribing State

Overview

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.
  • API introduction

    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:

    APITargetRequirements for calling the API
    autoSubscribeAudio or autoSubscribeVideo of channelMediaOptionsAll remote usersSet this API when calling joinChannel[2/2] or switchChannel[2/2]
    muteAllRemoteAudioStreams or muteAllRemoteVideoStreamsAll remote usersCall at any time in the channel
    muteRemoteAudioStream or muteRemoteVideoStreamA specified remote userCall 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.
  • Scenario one: Unsubscribe from specified users in a channel

    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.

    Scenario three: Subscribe to different remote users in a channel

    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.
  • Scenario four: Set the subscribing state when interrupted by a system or third-party application event

    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.

    1611154569739

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

    Corresponding methods in different programming languages

    Java/C++Objective-CC#Typescript/Dart
    joinChannel[2/2]joinChannelByToken[2/2]JoinChannel[2/2]joinChannel
    switchChannel[2/2]switchChannelByToken[2/2]SwitchChannel[2/2]switchChannel
    muteAllRemoteAudioStreamsmuteAllRemoteAudioStreamsMuteAllRemoteAudioStreamsmuteAllRemoteAudioStreams
    muteAllRemoteVideoStreamsmuteAllRemoteVideoStreamsMuteAllRemoteVideoStreamsmuteAllRemoteVideoStreams
    muteRemoteAudioStreammuteRemoteAudioStreamMuteRemoteAudioStreammuteRemoteAudioStream
    muteRemoteVideoStreammuteRemoteVideoStreamMuteRemoteVideoStreammuteRemoteVideoStream

    Video Calling