Setting peer video resolutions in a group call
In a video group call, applications call PeerControl::StartVideo() to request a video stream from a specific peer. This page describes how to set a video resolution when requesting a video stream.
| Supported call type | Supported SDK version |
|---|---|
| Group call (conference) | All versions |
For more information on how to use PeerControl, refer to the group video call code example.
Overview
When calling StartVideo(), you can set the resolution type. One of the available resolution types is PLNK_VIDEO_RESOLUTION_RECOMMENDED, which makes PlanetKit automatically adjust the resolution according to the situation. In addition, you can use PLNK_VIDEO_RESOLUTION_THUMBNAIL, PLNK_VIDEO_RESOLUTION_QVGA, PLNK_VIDEO_RESOLUTION_VGA, or PLNK_VIDEO_RESOLUTION_HD_FHD as a resolution type to set the resolution manually.
LINE Planet supports adaptive bitrate functionality. Since video resolution is subject to bitrate control, even if you set it to the recommended resolution (RECOMMENDED) or a specific resolution (such as HD or VGA), it may be adjusted to a lower resolution or recovered based on network conditions.
Using a recommended resolution
In general, a higher number of video streams leads to more CPU and memory consumption. Also, higher video resolutions require more network bandwidth. Excessive use of CPU, memory, or network bandwidth results in poor call quality for users. In other words, calling StartVideo() with an inappropriate video resolution can degrade audio quality as well as video quality.
To maintain the optimized quality, PlanetKit internally defines a set of appropriate resolutions according to the number of peers. The recommended settings by view style are as follows:
- Grid view: Set all peers to
PLNK_VIDEO_RESOLUTION_RECOMMENDED. - Focus view: Set one specific peer to HD and set the rest to
PLNK_VIDEO_RESOLUTION_RECOMMENDED.
The following sections show the resolution values defined by PlanetKit when PLNK_VIDEO_RESOLUTION_RECOMMENDED is set as the resolution for one or more peers. Note that the resolution may become temporarily lower than the resolution set initially, depending on the network condition.
Setting all to the recommended resolution
For a view style such as grid view, it is recommended to set the resolutions of all peers to PLNK_VIDEO_RESOLUTION_RECOMMENDED. In this case, PlanetKit internally determines the resolution as follows:
| iOS and Android | macOS and Windows | |
|---|---|---|
All PLNK_VIDEO_RESOLUTION_RECOMMENDED setting | VideoPeer1 count 1-3: VGA VideoPeer count 4-8: QVGA VideoPeer count 9+: THUMB2 | VideoPeer count 1-8: VGA VideoPeer count 9-24: QVGA VideoPeer count 25+: THUMB |
| Screen share3 | All THUMBs | All THUMBs |
1 VideoPeer means a peer for whom video was requested. Therefore, a VideoPeer count can be different from the total number of participants.
2 THUMB means the thumbnail size.
3 During screen share, the resolution of the remaining peers are changed to a thumbnail size.
Setting a specific resolution with the recommended resolution
For a view style such as focus view, you must set a high resolution for a specific user. In such a case, there is a combination of resolutions with a high resolution and PLNK_VIDEO_RESOLUTION_RECOMMENDED, and PlanetKit internally determines the resolution as follows:
| iOS and Android | macOS and Windows | |
|---|---|---|
HD settings with PLNK_VIDEO_RESOLUTION_RECOMMENDED settings | All THUMBs except peers set to HD | All THUMBs except peers set to HD |
Specific resolution settings (except HD) with PLNK_VIDEO_RESOLUTION_RECOMMENDED settings | Peers set to PLNK_VIDEO_RESOLUTION_RECOMMENDED:VideoPeer count 1-3: VGA VideoPeer count 4-8: QVGA VideoPeer count 9+: THUMB Peers set to specific resolutions follow the manual settings. | Peers set to PLNK_VIDEO_RESOLUTION_RECOMMENDED:VideoPeer count 1-8: VGA VideoPeer count 9-24: QVGA VideoPeer count 25+: THUMB Peers set to specific resolutions follow the manual settings. |
| Screen share | All THUMBs | All THUMBs |
Using a specific resolution
Alternatively, you can set a specific resolution when calling StartVideo().
Here is an example of how to use StartVideo() with a proper video resolution. In this example, let's assume that you decided to display videos in VGA for up to 3 participants and in QVGA for 4-8 participants as recommended in the tables above.
User-01 and User-02 join the group call first with their video on. For the basic join flow of a group call, see Group call flow.
User-03 joins the group call with video on. When User-03 joins, all existing participants are informed of the new participant by the OnPeerListUpdate event. In addition, the list of participants who enabled video is updated by the OnPeersVideoUpdated event.
With the events, User-03 recognizes that the group call currently has three participants and three video streams including oneself. By the design of the application, User-03 should request two video streams in VGA resolution, and this happens when User-03 calls StartVideo() for User-01 and User-02.
Likewise, User-01 and User-2 recognize that User-03 has joined with video on. As shown in the figure above, User-01 and User-02 call StartVideo() for User-03 to display User-03's video in VGA.
After a while, User-04 joins the group call with video on. User-03 recognizes that the number of participants in the group call has increased, and should trigger the presentation of video in QVGA. Therefore, User-03 calls StartVideo() for User-01 and User-02 to change the resolution of their video to QVGA. After that, User-03 calls StartVideo() for User-04 to request video in QVGA.
Related API
APIs related to peer video resolution setting in group calls are as follows.