VQE control

Voice Quality Enhancement (VQE) is an audio processing module of PlanetKit, which improves voice quality during calls. It helps create a clearer, more consistent call experience by addressing common audio issues in real-time communication.

Supported call type	Minimum SDK version
1-to-1 call, group call (conference)	PlanetKit 4.3

VQE filters

VQE provides three audio filters that can be controlled independently:

• Acoustic echo canceller
• Auto gain control
• Noise suppressor

Tip

For more information on VQE and its audio filters, read the blog article VQE for delivering good audio quality.

Acoustic echo canceller

An echo is a reflection of sound that reaches the listener with a delay after the direct sound. During an audio call, the echo can be picked up by the microphone, causing talkers to hear their own voices. An acoustic echo canceller (AEC) removes these echoes.

Auto gain control

Depending on microphone sensitivity (a characteristic of microphone hardware), the volume of sound captured by the microphone may become either too low or too high, making conversation difficult. An auto gain control (AGC) adjusts the volume to an appropriate level.

AGC modes

PlanetKit supports two types of AGC modes, software mode and hardware mode.

In software mode, software compensates the volume of input voice to keep the volume constant. However, the mode has limitations because excessive compensation can negatively impact sound quality. In other words, better sound quality can be guaranteed when an appropriate volume is input from the microphone. The hardware mode is used for this purpose.

In hardware mode, hardware controls the volume by calculating the energy of the speech section in the signal coming from the microphone.

• If the energy exceeds the reference level range, the microphone sensitivity is reduced.
• If the energy is below the reference level range, the microphone sensitivity is increased.
• When the energy is within the reference level range, the microphone sensitivity is maintained so that the voice comes in at a constant level.

The hardware mode directly controls the microphone device, so it is only available on platforms that can control the microphone, such as Windows and macOS. In addition, the hardware mode can provide greater volume amplification than software mode, achieving a reasonable level of volume for the voice that may not be heard well in the software mode.

Default AGC mode by platform

The default mode of AGC for each platform is as follows:

Platform	Default mode	Note
Android	Software mode	Hardware mode is not supported
iOS	Software mode	Hardware mode is not supported
macOS	Hardware mode
Windows	- PlanetKit 4.3 and 4.4: Software mode - PlanetKit 5.0 or higher: Hardware mode

Noise suppressor

Noise refers to any unwanted sound captured by the microphone that isn't the speaker's voice, such as keyboard typing or computer fan sound. A noise suppressor (NS) reduces these noises, enhancing the clarity of the speaker's voice and improving overall audio quality.

API overview

The SendVoiceProcessor class provides APIs to control VQE functionality.

• When SendVoiceProcessor is enabled (default), you can control each filter.
• When SendVoiceProcessor is disabled, all filters are disabled.

Note

Users may connect audio devices developed for VoIP conferencing that provide internal voice processing to use PlanetKit call features. In this case, SendVoiceProcessor might process already processed audio streams redundantly, negatively affecting voice quality. In such environments, it's recommended to disable SendVoiceProcessor to provide better voice quality.

Accessing the VQE instance

You can get a SendVoiceProcessor instance through a PlanetKitCall or PlanetKitConference instance.

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

Enabling or disabling VQE

To enable or disable VQE, use Enable() or Disable() of SendVoiceProcessor.

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

Controlling individual filters

When VQE is enabled, you can control each audio filter with APIs.

Note

In the following cases, controlling individual filters can help improve audio quality:

• When using an audio device with built-in AEC
• When playing an instrument or music
• When using audio input/output that are not actual devices through custom audio devices

For more information, refer to VQE filter control and When VQE control's AEC settings are required.

Configuring AEC

To control AEC, use the SetAcousticEchoCanceller() method, which takes EPlanetKitAcousticEchoCanceller as an argument. The EPlanetKitAcousticEchoCanceller enum provides the following modes:

Mode	Description
PLNK_ACOUSTIC_ECHO_CANCELLER_DISABLED	Disables AEC.
PLNK_ACOUSTIC_ECHO_CANCELLER_INTENSITY_RECOMMENDED	Applies a preset mode considering audio device type and OS type, which is determined through quality testing. Use this mode if you are not sure which mode to set.
PLNK_ACOUSTIC_ECHO_CANCELLER_INTENSITY_MIN	Applies minimum echo cancellation.
PLNK_ACOUSTIC_ECHO_CANCELLER_INTENSITY_MAX	Applies maximum echo cancellation.
PLNK_ACOUSTIC_ECHO_CANCELLER_INTENSITY_ADAPTIVE	Adaptively adjusts the intensity of echo cancellation.

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

Configuring AGC

To control AGC, use the SetAutoGainControl() method, which takes EPlanetKitAutoGainControl as an argument. The EPlanetKitAutoGainControl enum provides the following modes:

Mode	Description
PLNK_AUTO_GAIN_CONTROL_TYPE_DISABLED	Disables AGC.
PLNK_AUTO_GAIN_CONTROL_TYPE_SOFTWARE	Performs auto gain control by software.
PLNK_AUTO_GAIN_CONTROL_TYPE_HARDWARE	Performs auto gain control by hardware. (Not available on iOS or Android)

Note

Each platform has different capabilities for auto gain control. For the default mode and supported modes by platform, see Default AGC mode by platform.

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

Configuring NS

To control NS, use the SetNoiseSuppressor() method, which takes EPlanetkitNoiseSuppressorMode as an argument. The EPlanetkitNoiseSuppressorMode enum provides the following modes:

Mode	Description
PLNK_NOISE_SUPPRESSOR_MODE_DISABLED	Disables NS.
PLNK_NOISE_SUPPRESSOR_MODE_ENABLE	Enables NS. (Default value)

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

Related APIs

APIs related to VQE control are as follows.

Class

• SendVoiceProcessor

Methods

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

Enums

• EPlanetKitAcousticEchoCanceller
• EPlanetKitAutoGainControl
• EPlanetkitNoiseSuppressorMode