볼륨 제어

PlanetKit은 그룹 통화에서 다양한 방식으로 피어의 볼륨을 제어하며, 각 방식은 서로 영향을 줍니다. 이 페이지에서 정확한 사용법을 확인하세요.

지원 통화 유형	최소 SDK 버전
그룹 통화(컨퍼런스)	PlanetKit 3.6

PlanetKit 볼륨 제어

그룹 통화 도중에 볼륨을 제어하는 방식은 4가지입니다.

각 방식이 차례로 적용되며, 앞 단계 제어가 뒷 단계 제어에 영향을 줍니다.

1. 피어 볼륨 제어

애플리케이션은 특정 피어의 볼륨을 제어할 수 있습니다.

2. 서브그룹 무음 처리 설정

애플리케이션은 특정 서브그룹의 오디오 전체를 무음 처리(silence)할 수 있습니다.

3. 주요 오디오를 듣기 위한 자동 볼륨 제어

PlanetKit은 애플리케이션이 포커스 목록(focus list)을 만들고 그에 집중할 수 있게 해줍니다. PlanetKit은 포커스 목록에 있는 참여자가 발언할 때 포커스 목록에 없는 서브그룹의 오디오 볼륨을 낮춥니다. 포커스 목록에 있는 누구도 발언하지 않으면 볼륨을 낮추지 않습니다.

4. 믹스된 오디오 무음 처리 설정

애플리케이션은 모든 오디오를 무음 처리할 수 있습니다.

볼륨 제어 API 사용 방법

각 볼륨 제어 방식에 대해 API 사용 방법을 샘플 코드와 함께 설명합니다.

피어 볼륨 제어

특정 피어의 오디오 볼륨을 제어하려면 PeerControl::SetVolumeLevelSetting()을 사용하세요. 이 메서드는 다음과 같은 파라미터를 전달받습니다.

파라미터	설명
ucVolume	0에서 110까지 범위 내의 오디오 볼륨 레벨. 0은 음 소거, 100은 원래 볼륨, 110은 가장 큰 볼륨입니다.

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;
    });
}

서브그룹 무음 처리 설정

특정 서브그룹의 오디오 전체를 무음 처리하거나 무음 처리 해제하려면 SubgroupManager::SilencePeersAudio()를 사용하세요. 이 메서드는 다음과 같은 파라미터를 전달받습니다.

파라미터	설명
szSubgroupName	대상 서브그룹의 이름
bSilence	오디오의 무음 처리 또는 무음 처리 해제 여부

// 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;
    });
}

주요 오디오를 듣기 위한 자동 볼륨 제어

포커스 목록에 있는 서브그룹의 자동 볼륨 제어를 활성화하려면 SubgroupManager::SetPeersAudioAutoVolumeControl()을 사용하세요. 이 메서드는 다음과 같은 파라미터를 전달받습니다.

파라미터	설명
arrSubgroupNames	자동 볼륨 제어를 활성화할 서브그룹 이름의 배열

// 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;
    });
}

포커스 목록에 있는 서브그룹의 자동 볼륨 제어를 비활성화하려면 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;
    });
}

믹스된 오디오 무음 처리 설정

모든 오디오를 무음 처리하려면 PlanetKitConference::SilencePeersAudio()를 사용하세요. 이 메서드는 다음과 같은 파라미터를 전달받습니다.

파라미터	설명
bSilence	오디오의 무음 처리 또는 무음 처리 해제 여부

// 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;
    });
}

서브그룹 태그와 자동 볼륨 제어

SetTagMyAudioOfMainRoom() 메서드는 기본 방으로 전송하는 오디오를 서브그룹으로 태그하게 해줍니다. PlanetKit의 자동 볼륨 제어 모듈은 태그된 오디오가 서브그룹에서 오는 것으로 간주합니다.

서브그룹으로 태그된 오디오는 그 서브그룹이 포커스 목록에 없다면, 포커스된 서브그룹에 있는 사용자가 발언할 때 자동으로 볼륨이 감소됩니다. 반대로 서브그룹으로 태그된 오디오가 포커스 목록에 있다면, 포커스된 서브그룹에 있는 사용자가 발언할 때 다른 오디오의 볼륨이 자동으로 감소됩니다.

관련 샘플 코드는 아래와 같습니다.

오디오 태그 설정

// 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;
    });
}

오디오 태그 해제

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

관련 API

볼륨 제어와 관련된 API는 다음과 같습니다.

• PeerControl::SetVolumeLevelSetting()
• SubgroupManager::SilencePeersAudio()
• SubgroupManager::SetPeersAudioAutoVolumeControl()
• SubgroupManager::ClearPeersAudioAutoVolumeControl()
• PlanetKitConference::SilencePeersAudio()
• SubgroupManager::SetTagMyAudioOfMainRoom()