VQE 제어

Voice Quality Enhancement(VQE)는 PlanetKit의 오디오 처리 모듈로, 통화 중 음성 품질을 향상시킵니다. VQE는 실시간 통신에서 흔히 발생하는 오디오 문제를 해결하여 더 선명하고 일관된 통화 경험을 제공합니다.

지원되는 통화 유형	최소 SDK 버전
1대1 통화, 그룹 통화(컨퍼런스)	PlanetKit 4.3

VQE 필터

VQE는 독립적으로 제어할 수 있는 세 가지 오디오 필터를 제공합니다.

• 에코 제거 필터
• 음량 조절 필터
• 잡음 제거 필터

Tip

VQE와 오디오 필터에 대한 더 자세한 정보는 블로그의 좋은 음질을 전달하기 위한 VQE를 참조하세요.

에코 제거 필터

에코(echo)란 직접적인 소리 이후에 뒤늦게 청취자에게 도달하는 반향음입니다. 음성 통화 도중에 에코가 마이크로 섞여 들어가면 화자가 자신의 음성을 다시 듣게 될 수 있습니다. 에코 제거 필터(acoustic echo canceller, AEC)​는 소리에서 에코를 제거합니다.

음량 조절 필터

마이크 감도(마이크 하드웨어의 특성)에 따라 마이크로 포착된 소리의 볼륨이 너무 낮거나 높아져 대화가 어려워질 수 있습니다. 음량 조절 필터(auto gain control, AGC)​는 볼륨을 적절한 수준으로 조정합니다.

AGC 모드

PlanetKit은 소프트웨어 모드와 하드웨어 모드, 두 가지 AGC 모드를 지원합니다.

소프트웨어 모드에서는 입력 음성이 일정한 음량으로 유지되도록 소프트웨어로 보정합니다. 그런데 소프트웨어를 이용해 너무 많이 보정하면 음질에 안 좋은 영향을 끼칠 수 있다는 한계가 있습니다. 그보다는 마이크로부터 적당한 음량이 유입되는 것이 더 좋은 음질을 보장할 수 있으며, 이를 위해 사용하는 것이 바로 하드웨어 모드입니다.

하드웨어 모드에서는 마이크로 유입된 신호에서 음성 구간 에너지를 계산해 다음과 같이 하드웨어로 음량을 조절합니다.

• 음성 구간의 에너지가 기준 레벨 범위보다 크면 마이크 감도를 줄입니다.
• 음성 구간의 에너지가 기준 레벨 범위보다 작으면 마이크 감도를 키웁니다.
• 음성 구간의 에너지가 기준 레벨 범위 내에 있으면 마이크 감도를 유지합니다.

하드웨어 모드는 마이크 장치를 직접 제어하므로 Windows 및 macOS와 같이 마이크를 제어할 수 있는 플랫폼에서만 사용할 수 있습니다. 또한 하드웨어 모드는 소프트웨어 모드보다 음량 증폭이 더 클 수 있으며, 소프트웨어 모드에서는 잘 들리지 않을 수 있는 음성도 적정 수준의 볼륨으로 조정할 수 있습니다.

플랫폼별 AGC 기본 모드

각 플랫폼의 AGC 기본 모드는 다음과 같습니다.

플랫폼	기본 모드	참고
Android	소프트웨어 모드	하드웨어 모드는 지원되지 않음
iOS	소프트웨어 모드	하드웨어 모드는 지원되지 않음
macOS	하드웨어 모드
Windows	하드웨어 모드

잡음 제거 필터

잡음은 화자의 음성 외에 마이크로 포착된 원치 않는 소리(키보드 타이핑, 컴퓨터 팬 소음 등)를 말합니다. 잡음 제거 필터(noise suppressor, NS)​는 이러한 잡음을 줄여 화자의 목소리 선명도를 향상시키고 전반적인 오디오 품질을 개선합니다.

API 개요

SendVoiceProcessor 클래스에서 VQE 기능을 제어하는 API를 제공합니다.

• SendVoiceProcessor가 활성화된 경우(기본값) 각 필터를 제어할 수 있습니다.
• SendVoiceProcessor가 비활성화된 경우 모든 필터가 비활성화됩니다.

Note

사용자가 VoIP 회의용으로 개발되고 내부 음성 처리를 제공하는 오디오 장치를 연결해 PlanetKit 통화 기능을 이용할 수도 있습니다. 이 경우 SendVoiceProcessor가 이미 처리된 오디오 스트림을 이중 처리하면서 음성 품질에 부정적인 영향을 미칠 수 있습니다. 이러한 환경에서는 더 나은 음성 품질을 제공하기 위해 SendVoiceProcessor를 비활성화하는 것이 좋습니다.

VQE 인스턴스 얻기

PlanetKitCall 또는 PlanetKitConference 인스턴스를 통해 SendVoiceProcessor 인스턴스를 얻을 수 있습니다.

// 1-to-1 call
PlanetKit::PlanetKitCallPtr m_pCall;
... // Obtain the PlanetKitCall instance from the result of MakeCall() or VerifyCall()

PlanetKit::SendVoiceProcessorPtr voiceProcessor = m_pCall->GetSendVoiceProcessor();

// Group call
PlanetKit::PlanetKitConferencePtr m_pConference;
... // Obtain the PlanetKitConference instance from the result of JoinConference()

PlanetKit::SendVoiceProcessorPtr voiceProcessor = m_pConference->GetSendVoiceProcessor();

VQE 활성화 또는 비활성화하기

VQE를 활성화하거나 비활성화하려면 SendVoiceProcessor의 Enable() 또는 Disable()을 사용하세요.

// Enable VQE
voiceProcessor->Enable(nullptr, [](void* pUserData, bool bSuccess) {
    if (bSuccess) {
        std::wcout << L"VQE enabled successfully" << std::endl;
    }
});

// Disable VQE
voiceProcessor->Disable(nullptr, [](void* pUserData, bool bSuccess) {
    if (bSuccess) {
        std::wcout << L"VQE disabled successfully" << std::endl;
    }
});

// Check if VQE is enabled
bool isEnabled = voiceProcessor->IsEnabled();

개별 필터 제어하기

VQE가 활성화된 상태에서는 API로 각각의 오디오 필터를 제어할 수 있습니다.

Note

아래와 같은 경우 개별 필터를 제어하는 것이 음질을 개선하는 데 도움이 될 수 있습니다.

• 빌트인 AEC가 작동하는 오디오 장치를 사용할 때
• 악기를 연주하거나 음악을 재생할 때
• 커스텀 오디오 디바이스를 이용해 실제 장치가 아닌 오디오 입력/출력을 사용할 때

자세한 내용은 VQE 필터 제어와 VQE 제어의 AEC 설정이 필요한 경우를 참조하세요.

AEC 설정하기

AEC를 제어하려면 EPlanetKitAcousticEchoCanceller를 인자로 받는 SetAcousticEchoCanceller() 메서드를 사용하세요. EPlanetKitAcousticEchoCanceller 열거형은 다음과 같은 모드를 제공합니다.

모드	설명
PLNK_ACOUSTIC_ECHO_CANCELLER_DISABLED	AEC를 비활성화합니다.
PLNK_ACOUSTIC_ECHO_CANCELLER_INTENSITY_RECOMMENDED	오디오 장치 및 OS 종류를 고려한 품질 테스트를 통해 미리 정한 프리셋을 적용합니다. 어떤 모드를 설정해야 할지 확실하지 않은 경우 이 모드를 사용하세요.
PLNK_ACOUSTIC_ECHO_CANCELLER_INTENSITY_MIN	에코 제거를 최소화합니다.
PLNK_ACOUSTIC_ECHO_CANCELLER_INTENSITY_MAX	에코를 최대한 제거합니다.
PLNK_ACOUSTIC_ECHO_CANCELLER_INTENSITY_ADAPTIVE	에코 제거 강도를 적절히 조정합니다.

// Set AEC mode
voiceProcessor->SetAcousticEchoCanceller(PLNK_ACOUSTIC_ECHO_CANCELLER_INTENSITY_RECOMMENDED, nullptr, [](void* pUserData, bool bSuccess) {
    std::wcout << L"AEC configured with result: " << bSuccess << std::endl;
});

// Get current AEC mode
EPlanetKitAcousticEchoCanceller currentMode = voiceProcessor->GetAcousticEchoCancellerMode();

AGC 설정하기

AGC를 제어하려면 EPlanetKitAutoGainControl를 인자로 받는 SetAutoGainControl() 메서드를 사용하세요. EPlanetKitAutoGainControl 열거형은 다음과 같은 모드를 제공합니다.

모드	설명
PLNK_AUTO_GAIN_CONTROL_TYPE_DISABLED	AGC를 비활성화합니다.
PLNK_AUTO_GAIN_CONTROL_TYPE_SOFTWARE	소프트웨어로 음량 조절을 제어합니다.
PLNK_AUTO_GAIN_CONTROL_TYPE_HARDWARE	하드웨어로 음량 조절을 제어합니다. (iOS, Android에서는 사용 불가)
PLNK_AUTO_GAIN_CONTROL_TYPE_HARDWARE_ECHO_TOLERANCE	에코 허용 범위에 따라 하드웨어로 음량 조절을 제어합니다. 통화 환경에 에코가 있는 경우에도 화자의 음성 레벨을 기반으로 입력 음량을 조정합니다. (iOS, Android에서는 사용 불가) 참고: 이 모드는 PlanetKit 6.2.2부터 사용할 수 있습니다.

참고

플랫폼별로 제공하는 음량 조절 제어 기능에 차이가 있습니다. 플랫폼별 기본 모드 및 지원되는 모드는 플랫폼별 AGC 기본 모드를 참조하세요.

// Set AGC mode
voiceProcessor->SetAutoGainControl(PLNK_AUTO_GAIN_CONTROL_TYPE_SOFTWARE, nullptr, [](void* pUserData, bool bSuccess) {
    std::wcout << L"AGC configured with result: " << bSuccess << std::endl;
});

// Get current AGC mode
EPlanetKitAutoGainControl currentMode = voiceProcessor->GetAutoGainControlMode();

NS 설정하기

NS를 제어하려면 EPlanetKitNoiseSuppressorMode를 인자로 받는 SetNoiseSuppressor() 메서드를 사용하세요. EPlanetKitNoiseSuppressorMode 열거형은 다음과 같은 모드를 제공합니다.

모드	설명
PLNK_NOISE_SUPPRESSOR_MODE_DISABLED	NS를 비활성화합니다.
PLNK_NOISE_SUPPRESSOR_MODE_ENABLE	NS를 활성화합니다. (기본값)

// Set NS mode
voiceProcessor->SetNoiseSuppressor(PLNK_NOISE_SUPPRESSOR_MODE_ENABLE, nullptr, [](void* pUserData, bool bSuccess) {
    std::wcout << L"NS configured with result: " << bSuccess << std::endl;
});

// Get current NS mode
EPlanetKitNoiseSuppressorMode currentMode = voiceProcessor->GetNoiseSuppressorMode();

관련 API

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

클래스

• SendVoiceProcessor

메서드

• Enable()
• Disable()
• SetAcousticEchoCanceller()
• SetAutoGainControl()
• SetNoiseSuppressor()

열거형

• EPlanetKitAcousticEchoCanceller
• EPlanetKitAutoGainControl
• EPlanetKitNoiseSuppressorMode