Setting peer video resolutions in a group call
In a video group call, applications call startVideo() of PlanetKitPeerControl 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) | 0.9 |
For more information on how to use PlanetKitPeerControl, 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 recommended, which makes PlanetKit automatically adjust the resolution according to the situation. In addition, you can use thumbnail, qvga, vga, or hd 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
recommended. - Focus view: Set one specific peer to HD and set the rest to
recommended.
The following sections show the resolution values defined by PlanetKit when 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 recommended. In this case, PlanetKit internally determines the resolution as follows:
| iOS and Android | |
|---|---|
All recommended setting | VideoPeer1 count 1-3: VGA VideoPeer count 4-8: QVGA VideoPeer count 9+: THUMB2 |
| Screen share3 | 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 recommended, and PlanetKit internally determines the resolution as follows:
| iOS and Android | |
|---|---|
HD settings with recommended settings | All THUMBs except peers set to HD |
Specific resolution settings (except HD) with recommended settings | Peers set to recommended:VideoPeer count 1-3: VGA VideoPeer count 4-8: QVGA VideoPeer count 9+: THUMB Peers set to specific resolutions follow the manual settings. |
| Screen share | 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 onPeerListUpdated event. In addition, the onVideoUpdate event occurs for participants who enabled video.
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.