Skip to main content
Version: 6.2

Volume control

In group calls, PlanetKit controls peer volume in a number of ways. Each control method affects each other. This page describes how to control peer volume appropriately.

Supported call typeMinimum SDK version
Group call (conference)PlanetKit 3.6

Overview​

There are four methods to control volume during a group call.

Volume control steps

The four methods are applied in sequential order, and the control applied at an earlier stage influences the control applied at subsequent stages.

1. Peer volume control​

Applications can control volume of a specific peer.

2. Subgroup silence setting​

Applications can silence all audio of a specific subgroup.

3. Auto volume control to listen to focused audio​

PlanetKit allows applications to create a focus list and listen to focused audio. PlanetKit decreases the audio volume of subgroups that are not on the focus list when a participant in the focused subgroup speaks. Volume reduction is not performed unless someone in the focused subgroup is speaking.

4. Mixed audio silence setting​

Applications can silence all audio.

How to use volume control APIs​

This sections describes how to use APIs for each volume control method with sample code.

Peer volume control​

To control the audio volume of a specific peer, use PeerControl::SetVolumeLevelSetting(), which accepts the following parameters:

ParameterDescription
ucVolumeAudio volume level in the range from 0 to 110.
0 is muted, 100 is original, and 110 is the loudest.
void SetPeerVolumeExample(PlanetKit::PeerControlPtr pPeerControl, unsigned char ucVolume)
{
    std::wcout << L"SetVolumeLevelSetting(volume=" << static_cast<int>(ucVolume) << L")" << std::endl;
    pPeerControl->SetVolumeLevelSetting(ucVolume, nullptr, [](void*, bool bSuccess) {
        std::wcout
            << L"SetVolumeLevelSetting result: " << (bSuccess ? L"true" : L"false")
            << std::endl;
    });
}

Subgroup silence setting​

To silence or unsilence all audio of a specific subgroup, use SubgroupManager::SilencePeersAudio(), which accepts the following parameters:

ParameterDescription
szSubgroupNameName of the target subgroup
bSilenceWhether to silence or unsilence the audio
// strSubgroupName: Name of the subgroup to silence, or NullOptional for main room
// bSilence: true to silence, false to unsilence
void SilenceSubgroupExample(PlanetKit::SubgroupManagerPtr pSubgroupManager, const PlanetKit::WStringOptional& strSubgroupName, bool bSilence)
{
    std::wcout << L"SilencePeersAudio(silence=" << (bSilence ? L"true" : L"false") << L")" << std::endl;
    pSubgroupManager->SilencePeersAudio(strSubgroupName, bSilence, nullptr, [](void*, bool bSuccess) {
        std::wcout
            << L"SilencePeersAudio result: " << (bSuccess ? L"true" : L"false")
            << std::endl;
    });
}

Auto volume control to listen to focused audio​

To enable auto volume control of focused subgroups, use SubgroupManager::SetPeersAudioAutoVolumeControl(), which accepts the following parameters:

ParameterDescription
arrSubgroupNamesArray of subgroup names to enable auto volume
// arrSubgroupNames: Array of subgroup names to prioritize
void EnableAutoVolumeControlExample(PlanetKit::SubgroupManagerPtr pSubgroupManager, const PlanetKit::WStringArray& arrSubgroupNames)
{
    pSubgroupManager->SetPeersAudioAutoVolumeControl(arrSubgroupNames, nullptr, [](void*, bool bSuccess) {
        std::wcout
            << L"SetPeersAudioAutoVolumeControl result: " << (bSuccess ? L"true" : L"false")
            << std::endl;
    });
}

To disable auto volume control of the focused subgroups, use SubgroupManager::ClearPeersAudioAutoVolumeControl().

void DisableAutoVolumeControlExample(PlanetKit::SubgroupManagerPtr pSubgroupManager)
{
    pSubgroupManager->ClearPeersAudioAutoVolumeControl(nullptr, [](void*, bool bSuccess) {
        std::wcout
            << L"ClearPeersAudioAutoVolumeControl result: " << (bSuccess ? L"true" : L"false")
            << std::endl;
    });
}

Mixed audio silence setting​

To silence all audio, use PlanetKitConference::SilencePeersAudio(), which takes the following parameters:

ParameterDescription
bSilenceWhether to silence or unsilence the audio
// bSilence: true to silence, false to unsilence
void SilenceAllPeersExample(PlanetKit::PlanetKitConferencePtr pConference, bool bSilence)
{
    std::wcout << L"SilencePeersAudio(silence=" << (bSilence ? L"true" : L"false") << L")" << std::endl;
    pConference->SilencePeersAudio(bSilence, nullptr, [](void*, bool bSuccess) {
        std::wcout
            << L"SilencePeersAudio result: " << (bSuccess ? L"true" : L"false")
            << std::endl;
    });
}

Subgroup tag and auto volume control​

The SetTagMyAudioOfMainRoom() method tags audio routed to the main room as a subgroup. The auto volume controller in PlanetKit assumes the tagged audio is from the subgroup.

The volume of the tagged audio can be decreased when someone in the focused subgroup is speaking and if the tagged subgroup is not on the focus list. On the other hand, the volume of the other audios can be decreased when someone in the focused subgroup is speaking and if the tagged audio belongs to the focus list.

Related sample code is as follows.

Setting an audio tag​

// strTagSubgroupName: Subgroup name to tag the audio with
void SetAudioTagExample(PlanetKit::SubgroupManagerPtr pSubgroupManager, const PlanetKit::WString& strTagSubgroupName)
{
    pSubgroupManager->SetTagMyAudioOfMainRoom(strTagSubgroupName, nullptr, [](void*, bool bSuccess) {
        std::wcout
            << L"SetTagMyAudioOfMainRoom result: " << (bSuccess ? L"true" : L"false")
            << std::endl;
    });
}

Clearing an audio tag​

void ClearAudioTagExample(PlanetKit::SubgroupManagerPtr pSubgroupManager)
{
    pSubgroupManager->ClearTagMyAudioOfMainRoom(nullptr, [](void*, bool bSuccess) {
        std::wcout
            << L"ClearTagMyAudioOfMainRoom result: " << (bSuccess ? L"true" : L"false")
            << std::endl;
    });
}

APIs related to volume control are as follows.