Skip to main content
Version: 5.5

Audio hooking

PlanetKit provides the audio hooking function, which allows you to get the audio data before Planet Cloud transmits audio to a peer. This function can be used to modify the local user's voice or use the audio data for speech recognition.

Supported call typeMinimum SDK version
1-to-1 call5.5

Overview​

The PlanetKitCall class provides methods to use the audio hooking function.

Enable audio hooking​

To enable audio hooking, call EnableHookMyAudio() with the implementation of IPlanetKitAudioHook.

When audio hooking is enabled, you can receive a PlanetKitHookedAudio object through the OnHooked event.

Modify audio data (Optional)​

To modify the hooked audio data, take the following steps:

  1. Call PlanetKitHookedAudio::GetAudioData() to get the audio data.
  2. Modify the audio data as necessary.
  3. Call PlanetKitHookedAudio::SetAudioData() to set the modified audio data.
Note

In the PlanetKitHookedAudio class, only the raw audio data can be modified, and metadata such as channel, sample count, sample rate, sample type, and sequence number cannot be changed. When you modify the raw audio data, make sure that the format represented by the metadata is maintained.

Put back the audio data​

To put the hooked audio back for transmission, call PutHookedMyAudioBack() with a PlanetKitHookedAudio object.

Warning

After enabling audio hooking, you must put back the audio regardless of whether the audio data has been modified. Otherwise, audio is not transmitted to the peer.

Disable audio hooking​

To disable audio hooking, call DisableHookMyAudio().

Sample code​

The following sample code shows how to use the audio hooking function for voice modification.

// Implement audio modifier with IPlanetKitAudioHook
class MyAudioHook : public PlanetKit::IPlanetKitAudioHook {
public:
    void OnHooked(PlanetKit::PlanetKitHookedAudioPtr pHookedAudio) {
        const AudioData audioData = pHookedAudio->GetAudioData();

        if(m_pAudioBuffer == nullptr) {
            m_pAudioBuffer = new unsigned char[audioData.unBufferSize];
        }

        // Dump audio data
        memcpy(m_pAudioBuffer, audioData.pBuffer, audioData.unBufferSize);

        // Process `m_pAudioBuffer` as necessary
        ...

        // Set modified data to pHookedAudio
        pHookedAudio->SetAudioData(m_pAudioBuffer, audioData.unBufferSize);

        // Put audio data back to PlanetKit
        m_pCall->PutHookedMyAudioBack(pHookedAudio);
    }

private:
    unsigned char* m_pAudioBuffer = nullptr;
    unsigned int m_unBufferSize = 0;

    // Prepare instance of `PlanetKitCall`
    PlanetKit::PlanetKitCallPtr m_pCall;
}

class MyApplication {
public :
    // Method to enable audio hook
    void EnableAudioHook() {
        m_pCall->EnableHookMyAudio(&m_audioHook, this, [](void* pUserData, bool bSuccess){
            if(bSuccess == true) {
                OutputDebugStringW(L"Audio hook enabled successfully\n");
            }
            else {
                OutputDebugStringW(L"Failed to enable audio hook\n");
            }
        });
    }

    // Method to disable the audio hook
    void DisableAudioHook() {
        m_pCall->DisableHookMyAudio(this, [](void* pUserData, bool bSuccess) {
            if(bSuccess == true) {
                // Successfully disabled audio hooking
                OutputDebugStringW(L"Audio hook disabled successfully\n");
            }
            else {
                OutputDebugStringW(L"Failed to disable audio hook\n");
            }
        });
    }

private :
    // Prepare instance of PlanetKitCall
    PlanetKit::PlanetKitCallPtr m_pCall;

    // Prepare instance of MyAudioHook
    MyAudioHook m_audioHook;
};

APIs related to audio hooking are as follows.

Classes/interfaces​

Methods​

Events​