esp-sr/docs/audio_front_end/README_CN.md

Audio Front-end 框架[English]

乐鑫 Audio Front-end(AFE) 算法框架由乐鑫 AI 实验室自主开发。该框架基于 ESP32 系列芯片，能够向主机端提供高质量并且稳定的音频数据。

---

概述

乐鑫 AFE 框架以最便捷的方式基于乐鑫的 ESP32 系列芯片进行语音前端处理。使用乐鑫 AFE 框架，您可以获取高质量且稳定的音频数据，从而更加方便地构建唤醒或语音识别等应用。

乐鑫 AFE 的功能支持如下所示：

乐鑫 AFE 的工作流程如下：

乐鑫 AFE 工作流程可以分为 4 块：

• AFE 的创建和初始化
• AFE feed，输入音频数据，feed 内部会先进行 AEC 算法处理
• 内部：AFE BSS/NS 算法处理
• AFE fetch，返回处理过的音频数据和返回值， fetch 内部会进行 VAD 处理，如果用户设置 WakeNet 为 enable 状态，也会进行唤醒词的检测

其中 afe->feed() 和 afe->fetch() 对用户可见，Internal BSS/NS Task 对用户不可见。

AEC 在 afe->feed() 函数中运行；
BSS/NS 为 AFE 内部独立 Task 进行处理；
VAD 和 WakeNet 的结果通过 afe->fetch() 函数中获取。

选择 AFE handle

目前 AFE 支持单麦和双麦两种应用场景，单麦场景内部 Task 为 NS 处理，双麦场景内部 Task 为 BSS 处理。

• 单麦

    esp_afe_sr_iface_t *afe_handle = &esp_afe_sr_1mic;
  

• 双麦

    esp_afe_sr_iface_t *afe_handle = &esp_afe_sr_2mic;
  

输入音频

• AFE 单麦场景

  • 输入音频格式为 16KHz, 16bit, 双通道（1个通道为 mic 数据，另一个通道为参考回路）
  • 数据帧长为 32ms, 用户可以使用 afe->get_feed_chunksize 来获取需要的采样点数目（采样点数据类型为 int16）

数据排布如下：

• AFE 双麦场景

  • 输入音频格式为 16KHz, 16bit, 三通道
  • 数据帧长为 32ms, 用户可以使用 afe->get_feed_chunksize 来获取需要填充的数据量

数据排布如下：

注意：换算成数据量大小为：afe->get_feed_chunksize * 通道数 * sizeof(short)

AEC 简介

AEC (Acoustic Echo Cancellation) 算法最多支持双麦处理，能够有效的去除 mic 输入信号中的自身播放声音。从而可以在自身播放音乐的情况下进行很好的语音识别等应用。

NS 简介

NS (Noise Suppression) 算法支持单通道处理，能够对单通道音频中的非人声噪声进行抑制，尤其针对稳态噪声，具有很好的抑制效果。

BSS 简介

BSS (Blind Source Separation) 算法支持双通道处理，能够很好的将目标声源和其余干扰音进行盲源分离，从而提取出有用音频信号，保证了后级语音的质量。

VAD 简介

VAD (Voice Activity Detection) 算法支持实时输出当前帧的语音活动状态。

WakeNet or Bypass 简介

用户可以选择是否在 AFE 中进行唤醒词的识别。当用户调用 afe->disable_wakenet(afe_data) 后，则进入 Bypass 模式，AFE 模块不会进行唤醒词的识别。

输出音频

AFE 的输出音频为单通道数据，在 WakeNet 开启的情况下，AFE 会输出有目标人声的单通道数据。

---

快速开始

1. 定义 afe_handle

afe_handle 是用户后续调用 afe 接口的函数句柄。用户需要根据单麦和双麦场景选择对应的 afe_handle。

单麦场景：

esp_afe_sr_iface_t *afe_handle = &esp_afe_sr_1mic;

双麦场景：

esp_afe_sr_iface_t *afe_handle = &esp_afe_sr_2mic;

2. 配置 afe

获取 afe 的配置：

afe_config_t afe_config = AFE_CONFIG_DEFAULT();

可在宏AFE_CONFIG_DEFAULT()中调整各算法模块的使能及其相应参数:

#define AFE_CONFIG_DEFAULT() { \
    .aec_init = true, \
    .se_init = true, \
    .vad_init = true, \
    .wakenet_init = true, \
    .vad_mode = 3, \
    .wakenet_model = &WAKENET_MODEL, \
    .wakenet_coeff = &WAKENET_COEFF, \
    .wakenet_mode = DET_MODE_2CH_90, \
    .afe_mode = SR_MODE_HIGH_PERF, \
    .afe_perferred_core = 0, \
    .afe_perferred_priority = 5, \
    .afe_ringbuf_size = 50, \
    .alloc_from_psram = 1, \
    .agc_mode = 2, \
}

• aec_init: AEC 算法是否使能。

• se_init: BSS/NS 算法是否使能。

• vad_init: VAD 是否使能。

• wakenet_init: 唤醒是否使能。

• vad_mode: VAD 检测的操作模式，越大越激进。

• wakenet_model/wakenet_coeff/wakenet_mode: 使用 make menuconfig 来选择相应的唤醒模型，详见：WakeNet

• afe_mode: 乐鑫 AFE 目前支持 2 种工作模式，分别为：SR_MODE_LOW_COST, SR_MODE_HIGH_PERF。详细可见 afe_sr_mode_t 枚举。

  • SR_MODE_LOW_COST: 量化版本，占用资源较少。

  • SR_MODE_HIGH_PERF: 非量化版本，占用资源较多。

    **ESP32 芯片，只支持模式 SR_MODE_HIGH_PERF;
    ESP32S3 芯片，两种模式均支持 **

• afe_perferred_core: AFE 内部 BSS/NS 算法，运行在哪个 CPU 核。

• afe_ringbuf_size: 内部 ringbuf 大小的配置。

• alloc_from_psram: 是否优先从外部 psram 分配内存。可配置三个值：

  • 0: 从内部ram分配。

  • 1: 部分从外部psram分配。

  • 2: 绝大部分从外部psram分配

• agc_mode: 将音频线性放大的 level 配置（[0,3]）,0 表示无放大

3. 创建 afe_data

用户使用 afe_handle->create_from_config(&afe_config) 函数来获得数据句柄，这将会在afe内部使用，传入的参数即为上面第2步中获得的配置。

/**
 * @brief Function to initialze a AFE_SR instance
 * 
 * @param afe_config        The config of AFE_SR
 * @returns Handle to the AFE_SR data
 */
typedef esp_afe_sr_data_t* (*esp_afe_sr_iface_op_create_from_config_t)(afe_config_t *afe_config);

4. feed 音频数据

在初始化 AFE 和 WakeNet 完成后，用户需要将音频数据使用 afe_handle->feed() 函数输入到 AFE 中进行处理。

输入的音频大小和排布格式可以参考 输入音频 这一步骤。

/**
 * @brief Feed samples of an audio stream to the AFE_SR
 *
 *
 * @param afe   The AFE_SR data handle
 * 
 * @param in    The input microphone signal, only support signed 16-bit @ 16 KHZ. The frame size can be queried by the 
 *              `get_samp_chunksize`. The channel number can be queried `get_channel_num`.
 * @return      The size of input
 */
typedef int (*esp_afe_sr_iface_op_feed_t)(esp_afe_sr_data_t *afe, const int16_t* in);

获取音频通道数：

使用 afe_handle->get_channel_num() 函数可以获取需要传入 afe_handle->feed() 函数的 mic 数据通道数。（不含参考回路通道）

/**
 * @brief Get the channel number of samples that need to be passed to the fetch function
 * 
 * @param afe The AFE_SR object to query
 * @return The amount of channel number
 */
typedef int (*esp_afe_sr_iface_op_get_channel_num_t)(esp_afe_sr_data_t *afe);

5. fetch 音频数据

用户调用 afe_handle->fetch() 函数可以获取处理完成的单通道音频。

fetch 的数据采样点数目（采样点数据类型为 int16）可以通过 afe_handle->get_fetch_chunksize 获取。

/**
 * @brief Get the amount of each channel samples per frame that need to be passed to the function
 *
 * Every speech enhancement AFE_SR processes a certain number of samples at the same time. This function
 * can be used to query that amount. Note that the returned amount is in 16-bit samples, not in bytes.
 *
 * @param afe The AFE_SR object to query
 * @return The amount of samples to feed the fetch function
 */
typedef int (*esp_afe_sr_iface_op_get_samp_chunksize_t)(esp_afe_sr_data_t *afe);

用户需要注意 afe_handle->fetch() 的返回值：

• AFE_FETCH_CHANNEL_VERIFIED: 音频通道确认 (单麦唤醒，不返回该值)
• AFE_FETCH_NOISE: 侦测到噪声
• AFE_FETCH_SPEECH: 侦测到语音
• AFE_FETCH_WWE_DETECTED: 侦测到唤醒词
• ...

/**
 * @brief fetch enhanced samples of an audio stream from the AFE_SR
 *
 * @Warning  The output is single channel data, no matter how many channels the input is.
 *
 * @param afe   The AFE_SR object to query
 * @param out   The output enhanced signal. The frame size can be queried by the `get_samp_chunksize`.
 * @return      The state of output, please refer to the definition of `afe_fetch_mode_t`
 */
typedef afe_fetch_mode_t (*esp_afe_sr_iface_op_fetch_t)(esp_afe_sr_data_t *afe, int16_t* out);

6. WakeNet 使用

当用户在唤醒后需要进行其他操作，比如离线或在线语音识别，这时候可以暂停 WakeNet 的运行，从而减轻 CPU 的资源消耗。

用户可以调用 afe_handle->disable_wakenet(afe_data) 来停止 WakeNet。 当后续应用结束后又可以调用 afe_handle->enable_wakenet(afe_data) 来开启 WakeNet。

7. AEC 使用

AEC 的使用和 WakeNet 相似，用户可以根据自己的需求来停止或开启 AEC。

• 停止 AEC

  afe->disable_aec(afe_data);

• 开启 AEC

  afe->enable_aec(afe_data);