MI BF API

Version 1.1

1. 概述¶

1.1. 算法说明¶

BF（beamforming）波束形成或空间滤波是一种用于传感器数组的定向信号处理技术传输或接收。通过这样一种方式组合麦克风数组中的组件来实现特定角度的信号加强，而其他的则会衰减。波束形成可用于发射端和接收端，以实现空间选择性。

1.2. 关键词说明¶

噪音阀值

Noise Gate（dBFS）,低于此值将会把该帧作为噪声部分处理。若设置太高，容易造成语音失真。若设定置太低，会影响算法效果。应小心处理此值设定。此值范围[-80,0], 建议值为 -44，步长为1。
噪声抑制模式

Noise Suppression Mode，此值越大，噪声消除强度越强。如果此值设置得太高，容易导致语音失真。如果设置得太低，会影响算法效果。应小心处理此值设定。此值范围[0,30]，建议值为8，步长为1。

1.3. 注意¶

为方便调试和确认算法效果，需要用户应用自行实现替换算法参数和抓取音频数据的逻辑。

2. API 参考¶

2.1. 功能模块API¶

API名	功能
IaaBf_GetBufferSize	获取Bf算法运行需要的内存大小
IaaBf_Init	初始化Bf算法
IaaBf_Config	配置Bf算法
IaaBf_Get_Config	获取Bf算法当前的配置参数信息
IaaBf_Run	Bf算法处理
IaaBf_Reset	重新初始化Bf算法
IaaBf_Free	释放Bf算法资源

2.2. IaaBf_GetBufferSize¶

功能

获取Bf算法运行所需要的内存大小。

语法

unsigned int IaaBf_GetBufferSize(void);

形参

参数名称描述输入/输出
返回值

返回值为Bf算法运行所需要的内存大小
依赖
- 头文件: AudioBfProcess.h
- 库文件: libBF_LINUX.so/ libBF_LINUX.a
注意

该接口仅返回需要的内存大小，申请和释放内存的动作需应用来处理。
举例

请参考IaaBf_Run举例部分。

2.3. IaaBf_Init¶

功能

初始化Bf算法。

语法

BF_HANDLE IaaBf_Init(char* working_buffer,AudioBfInit* bf_init);

形参

参数名称描述输入/输出

working_buffer Bf算法所使用的内存地址输入

bf_init Bf算法的初始化结构体指针输入
返回值

返回值结果

非NULL 成功

NULL 失败
依赖
- 头文件: AudioBfProcess.h
- 库文件: libBF_LINUX.so/ libBF_LINUX.a
注意

无。
举例

请参考IaaBf_Run举例部分。

2.4. IaaBf_Config¶

功能

配置Bf算法。

语法

ALGO_BF_RET IaaBf_Config(BF_HANDLE handle,AudioBfConfig* bf_config);

形参

参数名称描述输入/输出

handle Bf算法handle 输入

bf_config Bf算法的配置结构体指针输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioBfProcess.h
- 库文件: libBF_LINUX.so/ libBF_LINUX.a
注意

无。
举例

请参考IaaBf_Run举例部分。

2.5. IaaBf_Get_Config¶

功能

获取Bf算法当前的配置参数。

语法

ALGO_BF_RET IaaBf_Get_Config(BF_HANDLE handle,AudioBfConfig *bf_config);

形参

参数名称描述输入/输出

handle Bf算法handle 输入

bf_config Bf算法的配置结构体指针输出
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioBfProcess.h
- 库文件: libBF_LINUX.so/ libBF_LINUX.a
注意

无。
举例

请参考IaaBf_Run举例部分。

2.6. IaaBf_Run¶

功能

BF算法处理。

语法

ALGO_BF_RET IaaBf_Run(BF_HANDLE handle,short* microphone_input,int * microphone_doa);

形参

参数名称	描述	输入/输出
handle	Bf算法handle	输入
microphone_input	待进行声源定位的数据指针	输入
microphone_doa	Beamforming处理的角度。此值由SSL计算，SSL会计算语音的方向。如声音来自正前方(固定方向)，则可输入0数组。此数组长度应为麦克风数-1。	输入

返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioBfProcess.h
- 库文件: libBF_LINUX.so/ libBF_LINUX.a
注意
- microphone_input指向的数据应以采样点为最小单位，按照L,R,L,R…的格式摆放。资料长度必须和IaaBf_Init 中设定的point_number（即多少个采样点进行一次beamforming处理）相对应。

举例

#include <stdio.h>  
#include <string.h>  
#include <sys/time.h>  
#include <stdlib.h>

#include "AudioBfProcess.h"

/*  0:Fixed input file  1:User input file   */  
#define IN_PARAMETER 1

int main(int argc, char *argv[])  
{  
    short in_output[1024];  
    char *workingBuffer = NULL;  
    unsigned int workingBufferSize;  
    ALGO_BF_RET ret = ALGO_BF_RET_SUCCESS;  
    int tempSize;  
    int delay_sample = 0;  
    AudioBfInit bf_init;  
    AudioBfConfig bf_config, bf_get_config;  
    BF_HANDLE handle;  
    FILE* fpIn;  
    FILE* fpOut;  
    char src_file[128] = {0};  
    char dst_file[128] = {0};

#if IN_PARAMETER  
    if(argc < 3)  
    {  
        printf("Please enter the correct parameters!\n");  
        return -1;  
    }  
    sscanf(argv[1], "%s", src_file);  
    sscanf(argv[2], "%s", dst_file);  
#else  
    sprintf(src_file, "%s", "./12cm_2mic_8k_0degree.wav");  
    if(argc < 2)  
    {  
        printf("Please enter the correct parameters!\n");  
        return -1;  
    }  
    sscanf(argv[1], "%s", dst_file);  
#endif

    /****User change section start****/  
    bf_init.mic_distance = 12;  
    bf_init.point_number = 128;  
    bf_init.sample_rate = 8000;  
    bf_init.channel = 2;

    bf_config.noise_gate_dbfs = -40;  
    bf_config.temperature = 25;  
    bf_config.noise_supression_mode = 8;  
    bf_config.noise_estimation = 1;  
    bf_config.output_gain = 0.7;  
    bf_config.vad_enable = 0;

    /****User change section end ****/  
    //(1)IaaBf_GetBufferSize  
    workingBufferSize = IaaBf_GetBufferSize();  
    workingBuffer = (char*)malloc(workingBufferSize);  
    if(NULL == workingBuffer)  
    {  
        printf("workingBuffer malloc failed !\n");  
        return -1;  
    }  
    //(2)IaaBf_Init  
    handle = IaaBf_Init(workingBuffer, &bf_init);  
    if (NULL == handle)  
    {  
        printf("IaaBf_Init failed !\n");  
        return -1;  
    }  
    printf("IaaBf_Init succeed !\n");  
    //(3)IaaBf_Config  
    ret = IaaBf_Config(handle, &bf_config);  
    if (ALGO_BF_RET_SUCCESS != ret)  
    {  
        printf("IaaBf_Config failed !, ret = %d\n", ret);  
        return -1;  
    }  
    printf("IaaBf_Config succeed !\n");  
    //(4)IaaBf_Get_Config  
    ret = IaaBf_Get_Config(handle, &bf_get_config);  
    if(ALGO_BF_RET_SUCCESS != ret)  
    {  
        printf("IaaBf_Get_Config dailed !, ret = %d\n", ret);  
        return -1;  
    }  
    printf("IaaBf_Get_Config succeed !\n");  
    printf("bf_get_config.noise_gate_dbfs = %d\n", bf_get_config.noise_gate_dbfs);  
    printf("bf_get_config.temperature = %u\n", bf_get_config.temperature);  
    printf("bf_get_config.noise_supression_mode = %d\n", bf_get_config.noise_supression_mode);  
    printf("bf_get_config.noise_estimation = %d\n", bf_get_config.noise_estimation);  
    printf("bf_get_config.output_gain = %f\n", bf_get_config.output_gain);  
    fpIn = fopen(src_file, "rb");  
    if(NULL == fpIn)  
    {  
        printf("fopen in_file failed !\n");  
        return -1;  
    }  
    printf("fopen in_file success !\n");  
    fpOut = fopen(dst_file, "wb");  
    if(NULL == fpOut)  
    {  
        printf("fopen out_file failed !\n");  
        return -1;  
    }  
    printf("fopen out_file success !\n");  
#if 1  
    fread(in_output, sizeof(char), 44, fpIn);  
    fwrite(in_output, sizeof(char), 44, fpOut);  
#endif  
    tempSize = bf_init.point_number * bf_init.channel;  
    while(tempSize == fread(in_output, sizeof(short), tempSize, fpIn))  
    {  
        //(5)IaaBf_Run  
        ret = IaaBf_Run(handle, in_output, &delay_sample);  
        if(ALGO_BF_RET_SUCCESS != ret)  
        {  
            printf("IaaBf_Run failed !\n");  
            return -1;  
        }  
        fwrite(in_output, sizeof(short), tempSize, fpOut);  
    }  
    //(6)IaaBf_Free  
    ret = IaaBf_Free(handle);  
    if(ALGO_BF_RET_SUCCESS != ret)  
    {  
        printf("IaaBf_Free failed !, ret = %d\n", ret);  
        return -1;  
    }  
    printf("IaaBf_Free succeed !\n");  
    fclose(fpIn);  
    fclose(fpOut);  
    free(workingBuffer);  
    printf("BF end !\n");

    return 0;  
}

2.7. IaaBf_Reset¶

功能

重新初始化Bf算法。

语法

BF_HANDLE IaaBf_Reset(BF_HANDLE working_buffer,AudioBfInit* bf_init);

形参

参数名称描述输入/输出

working_buffer Bf算法运行的内存地址输入

bf_init Bf算法的初始化参数结构体指针输入
返回值

返回值结果

非NULL 成功

NULL 失败
依赖
- 头文件: AudioBfProcess.h
- 库文件: libBF_LINUX.so/ libBF_LINUX.a
注意

无。
举例

无。

2.8. IaaBf_Free¶

功能

释放Bf算法资源。

语法

ALGO_BF_RET IaaBf_Free(BF_HANDLE handle);

形参

参数名称描述输入/输出

handle Bf算法handle 输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioBfProcess.h
- 库文件: libBF_LINUX.so/ libBF_LINUX.a
注意

无。
举例

请参考IaaBf_Run举例部分。

3. BF 数据类型¶

3.1. BF模块相关数据类型定义¶

数据类型	定义
AudioBfInit	Bf算法初始化参数结构体类型
AudioBfConfig	Bf算法配置参数结构体类型
BF_HANDLE	Bf算法句柄类型

3.2. AudioBfInit¶

说明

定义Bf算法的初始化参数类型。

定义

typedef struct

{

    unsigned int point_number;

    unsigned int sample_rate;

    unsigned int mic_distance;

    unsigned int channel;

}AudioBfInit;

成员

成员名称	描述
point_number	Bf算法处理一次的采样点数
sample_rate	采样率，目前支持8k/16k/32k/48k
mic_distance	两个mic的距离，单位为cm,建议为5cm 或6cm
channel	通道数

注意

无。
相关数据类型及接口

IaaBf_Init

IaaBf_Reset

3.3. AudioBfConfig¶

说明

定义BF算法的配置参数结构体类型。

定义

typedef struct

{

    unsigned int temperature;

    int noise_gate_dbfs;

    int noise_supression_mode;

    int noise_estimation;

    float output_gain;

    int vad_enable;

}AudioBfConfig;

成员

成员名称	描述
temperature	环境温度（摄氏度）摄氏度＝(5/9)*(华氏度－32) 步长为1
noise_gate_dbfs	噪音阀值（dB）低于此值将会把该帧作为噪声部分处理。应小心处理此值。若设置太高，容易造成语音失真。若设定置太低，会影响BF的效果。建议值为 -44，步长为1。
noise_supression_mode	噪声抑制模式，此值越大，噪声消除强度越强。应小心处理此值。如果此值设置得太高，容易导致语音失真。如果设置得太低，会影响BF的效果。范围[0,30]，建议值为8，步长为1
noise_estimation	噪声的估计模式，输入值为0或1。 0为自适应模式 1为平均模式关键词定位预处理推荐使用0 语音通讯推荐使用1
output_gain	输出增益，范围[0,1] 设定为0.7为正常情况，设定为1，会增加4dB 建议值为0.7，不增加任何增益
vad_enable	语音活检测(VAD)模式是否开启，输入值为0或1。若开启此设定，则利用VAD来计算每帧是否进入噪音估计处理。若关闭此设定，则利用上述所设定的noise_gate_dbfs来决定是否视为噪音处理。

注意事项
- 无。
相关数据类型及接口

IaaBf_Config

IaaBf_Get_Config

3.4. BF_HANDLE¶

说明

定义Bf算法的句柄类型。
定义
```
typedef void* BF_HANDLE;
```
成员

成员名称描述
注意事项

无
相关数据类型及接口

IaaBf_Init

IaaBf_Config

IaaBf_Get_Config

IaaBf_Run

IaaBf_Reset

IaaBf_Free

4. 错误码¶

BF API 错误码如下表所示：

表 4‑1 BF API错误码

错误码	宏定义	描述
0x00000000	ALGO_BF_RET_SUCCESS	BF执行成功
0x10000301	ALGO_BF_RET_INIT_ERROR	BF初始化错误
0x10000302	ALGO_BF_RET_INVALID_CONFIG	BF Config无效
0x10000303	ALGO_BF_RET_INVALID_HANDLE	BF Handle无效
0x10000304	ALGO_BF_RET_INVALID_NOISE_ESTIMATION	BF噪音估计模式设置无效
0x10000305	ALGO_BF_RET_INVALID_VAD_ENABLE	BF VAD模式设置无效
0x10000306	ALGO_BF_RET_INVALID_OUTPUT_GAIN	BF 输出增益设置无效
0x10000307	ALGO_BF_RET_INVALID_NOISE_SUPMODE	BF噪音压抑设置无效
0x10000308	ALGO_BF_RET_INVALID_INPUT_POINTER	BF输入指标无效
0x10000309	ALGO_BF_RET_INVALID_SAMPLERATE	BF采样率无效
0x10000310	ALGO_BF_RET_INVALID_POINTNUMBER	BF采样点数无效
0x10000311	ALGO_BF_RET_INVALID_CHANNEL	BF通道数无效
0x10000312	ALGO_BF_RET_INVALID_CALLING	BF呼叫API顺序错误
0x10000313	ALGO_BF_RET_API_CONFLICT	有其他API正在运行

参数名称	描述	输入/输出
working_buffer	Bf算法所使用的内存地址	输入
bf_init	Bf算法的初始化结构体指针	输入

参数名称	描述	输入/输出
working_buffer	Bf算法运行的内存地址	输入
bf_init	Bf算法的初始化参数结构体指针	输入

返回值	结果
非NULL	成功
NULL	失败

返回值	结果
0	成功
非0	失败，参照错误码

返回值	结果
0	成功
非0	失败，参照错误码

返回值	结果
0	成功
非0	失败，参照错误码