音频前处理

---

1 功能简介

ZegoLiveRoom SDK 为开发者提供了音频前处理的功能。

音频前处理技术一般用于去除语音中的干扰。但 SDK 已经针对采集的音频数据进行了回声消除、噪声抑制等的处理，因此通常情况下，开发者无需再重复处理。

如果开发者想在采集音频数据后或拉取远端音频数据渲染前，通过自定义处理实现特殊功能时（例如变声、美声等），可以参考本文档。

2 使用步骤

音频前处理的使用流程如下：

1. 初始化 SDK

2. App 设置音频前处理代理回调并传入预处理参数

3. 预览/推流

2.1 预处理参数

预处理参数为 AVE::ExtPrepSet 结构体类型，结构体中的变量的含义如下：

struct ExtAudioProcSet
{
    /**
     * 是否对前处理后的数据进行编码。
     * 如果为 true，需要业务 App 将前处理后的音频数据编码为 AAC，samples 变量需要设置为编码一帧所需要的采样数；
     * 如果为 false，则不需要业务 App 对前处理后的音频数据进行编码，直接输出 PCM 数据。
     */
    bool bEncode;

    /**
     * 采样率，App 中音频前处理模块期望的输入数据采样率。如果为 0，则默认为 SDK 内部采样率。
     */
    int nSampleRate;

    /**
     * 声道数，App 中音频前处理模块期望的输入数据声道数。如果为 0，则默认为 SDK 内部声道数
     */
    int nChannel;

    /**
     * 编码一帧所需要的采样数；encode = false 时，如果 samples = 0，则使用 SDK 内部采样数，SDK 将音频数据传递给外部前处理模块；如果 samples != 0（则samples 的有效取值在 [160, 2048] 间），SDK 会传递设定采样数长度的音频数据给外部预处理模块。encode = true 时，AAC 编码一帧可设的采样数为（480/512/1024/1960/2048）
     */
    int nSamples;
    ExtAudioProcSet()
    {
        bEncode = false;
        nSampleRate = 0;
        nChannel = 0;
        nSamples = 0;
    }

};

2.2 设置音频前处理回调并传入预处理参数

开发者要想实现音频前处理，必须设置音频前处理回调。

在回调中将 SDK 传给 App 的 AVE::AudioFrame 音频数据进行处理，并将处理后的音频数据封装成 AVE::AudioFrame 返回给 SDK。

设置音频前处理代理对象的 API 如下：

/**
 设置音频前处理函数(耳返前), 并开启/关闭音频前处理特性

 @param callback 音频前处理函数指针
 @param config 预处理的采样率等参数设置
 @attention 必须在 InitSDK 后且在推流前调用
 @attention 该接口设置的回调处理音频影响耳返效果
 */
ZEGO_API void SetAudioPrepCallback(AVE::OnPrepCallback callback, const AVE::ExtPrepSet& config);

3 示例代码

// 定义音频前处理回调，并在回调中处理 SDK 传入的音频数据
// outFrame.buffer已经分配内存，outFrame.bufLen不应大于48k采样率产生的数据长度
void OnAudioProcCB(const AudioFrame& inFrame, AudioFrame& outFrame)
{
    outFrame.frameType = inFrame.frameType;
    outFrame.samples = inFrame.samples;
    outFrame.bytesPerSample = inFrame.bytesPerSample;
    outFrame.channels = inFrame.channels;
    outFrame.sampleRate = inFrame.sampleRate;
    outFrame.timeStamp = inFrame.timeStamp;
    outFrame.configLen = inFrame.configLen;
    outFrame.bufLen = inFrame.bufLen;
    memcpy(outFrame.buffer, inFrame.buffer, inFrame.bufLen);
}

ExtPrepSet config;
config.bEncode = false;    // 不需要编码前处理后的数据，输出 PCM 数据
config.nSampleRate = 0; // 使用 SDK 默认采样率
config.nChannel = 0;    // 使用 SDK 默认声道数
config.nSamples = 0;    // 编码一帧所需要的采样数 

LIVEROOM::SetAudioPrepCallback(OnAudioProcCB, config);

// 关闭音频前处理
ExtPrepSet config;
LIVEROOM::SetAudioPrepCallback(nullptr, config);