Subgroup flow

This page describes the flow of using a subgroup in a group call (conference).

To become a member of a subgroup, participants must subscribe to the subgroup. When leaving a subgroup, participants must stop sending media to the subgroup and then unsubscribe from the subgroup.

Members who subscribed to a subgroup can control the destination subgroup for audio and video. If the member does nothing, the flow of audio and video is not changed.

Subscribe

To subscribe to a subgroup, you must call SubscribeSubgroup().

The following figure shows a sequence diagram for subscribing to a subgroup. Suppose there are two participants, Client 01 and Client 02. The two are communicating through the main room ("Main Room").

After the two participants subscribe to Subgroup K as in the procedure above, they can still communicate with each other through the main room. However, the media may be exposed to other participants in the main room.

The following table shows the available events for each ESubGroupPeerUpdateType.

	PUBLIC	PRIVATE	NONE
Subgroup member (self-subscribed or added member)	OnPeerListUpdate OnPublicSubgroupUpdated	OnPeerListUpdate	N/A
Non subgroup member (unsubscribed member)	OnPublicSubgroupUpdated	N/A	N/A

Audio

After completing the subscription, subgroup members automatically receive audio streams from the subgroup. However, the app client must call ChangeMyAudioDestination() to change the destination of the member's audio stream to a subgroup.

The following diagram shows how the flow of audio streams and the received audio information are changed when ChangeMyAudioDestination() is called. The colored rectangular boxes indicate audio information received by each user.

Suppose there are three participants in a group call: Client 01, Client 02, and Client 03. Client 01 and Client 02 are members of Subgroup K. Client 01 and Client 02 subscribed to Subgroup K, but there is no audio to receive because no one is sending audio to Subgroup K.

Changes in audio destinations and audio received from the main room and subgroup are as follows:

1. Client 01 calls ChangeMyAudioDestination().
   • Client 01
     • Audio destination: Main Room → Subgroup K
     • Audio received from Main Room: Client 02 and Client 03
     • Audio received from Subgroup K: None
   • Client 02
     • Audio destination: Main Room
     • Audio received from Main Room: Client 03
     • Audio received from Subgroup K: Client 01
   • Client 03
     • Audio destination: Main Room
     • Audio received from Main Room: Client 02
2. Client 02 calls ChangeMyAudioDestination().
   • Client 01
     • Audio destination: Subgroup K
     • Audio received from Main Room: Client 03
     • Audio received from Subgroup K: Client 02
   • Client 02
     • Audio destination: Main Room → Subgroup K
     • Audio received from Main Room: Client 03
     • Audio received from Subgroup K: Client 01
   • Client 03
     • Audio destination: Main Room
     • Audio received from Main Room: None

Video

After completing the subscription, you can control which subgroup's video to receive using PeerControl::StartVideo().

Note

For more information on how to use PeerControl, refer to the group video call code example.

For more information on how to use StartVideo(), refer to Group call flow - Request peer video.

The ChangeMyVideoDestination() method lets an application change the destination subgroup for video.

Screen share

Presentation - Screen share describes how to start a presentation. The method is the same when starting a presentation for a subgroup.

Note

• Screen share within a subgroup scope is supported since PlanetKit 4.1.
• You can use the methods of PeerControl to control screen share video on a peer's screen share view. For more information on how to use PeerControl, refer to the group call screen share code example.

After completing the subscription, a presenter should call StartMyScreenShare() with a proper subgroup name. Participants can receive the presenter's screen share video by calling PeerControl::StartScreenShare(). The ChangeMyScreenShareDestination() method lets an application change the destination subgroup for screen share video. Check the following flow:

Tip

Like other media such as audio and video, the screen share must be stopped before the presenter unsubscribes from the subgroup.

Unsubscribe

To unsubscribe from a subgroup, you must call UnsubscribeSubgroup(). Note that the media transmission to the subgroup must be stopped before unsubscribing.

Let's look at how Client 01 unsubscribes from Subgroup K. It is assumed that there is no presentation going on in the flow below, but the screen share must be handled in the same way as audio and video.

To unsubscribe from a subgroup, the application goes through two steps: changing the media destination and calling UnsubscribeSubgroup().

1. Client 01 changes the media destination.
   • Calls ChangeMyAudioDestinationToMainRoom() to send audio to the main room
   • Calls ChangeMyVideoDestinationToMainRoom() to send video to the main room
2. Client 01 calls UnsubscribeSubgroup().

Related API

APIs related to subgroups are as follows.

Enums

• ESubGroupPeerUpdateType

Methods

• SubscribeSubgroup()
• UnsubscribeSubgroup()
• ChangeMyAudioDestination()
• ChangeMyAudioDestinationToMainRoom()
• StartVideo()
• ChangeMyVideoDestination()
• ChangeMyVideoDestinationToMainRoom()
• StartMyScreenShare()
• StartScreenShare()
• ChangeMyScreenShareDestination()

Events

• OnPeerListUpdate
• OnPublicSubgroupUpdated
• OnPeersVideoUpdated
• OnVideoUpdated
• IConferenceEvent::OnPeerScreenShareUpdated
• IPeerControlEvent::OnScreenShareUpdated

Related documents

You can find more information in Subgroup basic concepts.