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 PlanetKitSendVoiceProcessor class provides APIs to control VQE functionality.

• When PlanetKitSendVoiceProcessor is enabled (default), you can control each filter.
• When PlanetKitSendVoiceProcessor 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, PlanetKitSendVoiceProcessor might process already processed audio streams redundantly, negatively affecting voice quality. In such environments, it's recommended to disable PlanetKitSendVoiceProcessor to provide better voice quality.

Accessing the VQE instance

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

// 1-to-1 call
let call: PlanetKitCall
... // Obtain the PlanetKitCall instance from the result of makeCall() or verifyCall()

let voiceProcessor = call.sendVoiceProcessor

// Group call
let conference: PlanetKitConference
... // Obtain the PlanetKitConference instance from the result of joinConference()

let voiceProcessor = conference.sendVoiceProcessor

Enabling or disabling VQE

To enable or disable VQE, use enable() or disable() of PlanetKitSendVoiceProcessor.

// Enable VQE
voiceProcessor.enable { success in
    if success {
        print("VQE enabled successfully")
    }
}

// Disable VQE
voiceProcessor.disable { success in
    if success {
        print("VQE disabled successfully")
    }
}

// Check if VQE is enabled
let 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 PlanetKitAcousticEchoCancellerMode as an argument. The PlanetKitAcousticEchoCancellerMode enum provides the following modes:

Mode	Description
disabled	Disables AEC.
intensityRecommended	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.
intensityMin	Applies minimum echo cancellation.
intensityMax	Applies maximum echo cancellation.
intensityAdaptive	Adaptively adjusts the intensity of echo cancellation.

// Set AEC mode
voiceProcessor.setAcousticEchoCanceller(mode: .intensityRecommended) { success in
    print("AEC configured with result: \(success)")
}

// Get current AEC mode
let currentMode = voiceProcessor.acousticEchoCancellerMode

Configuring AGC

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

Mode	Description
disabled	Disables AGC.
software	Performs auto gain control by software.

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(mode: .software) { success in
    print("AGC configured with result: \(success)")
}

// Get current AGC mode
let currentMode = voiceProcessor.autoGainControlMode

Configuring NS

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

Mode	Description
disabled	Disables NS.
enabled	Enables NS. (Default value)

// Set NS mode
voiceProcessor.setNoiseSuppressor(mode: .enabled) { success in
    print("NS configured with result: \(success)")
}

// Get current NS mode
let currentMode = voiceProcessor.noiseSuppressorMode

Related APIs

APIs related to VQE control are as follows.

Class

• PlanetKitSendVoiceProcessor

Methods

• enable()
• disable()
• setAcousticEchoCanceller()
• setAutoGainControl()
• setNoiseSuppressor()

Enums

• PlanetKitAcousticEchoCancellerMode
• PlanetKitAutoGainControlMode
• PlanetKitNoiseSuppressorMode