SSTAR_BF100算法使用参考

REVISION HISTORY¶

Revision No.	Description	Date
1.0.0	Initial release	08/02/2021
1.1.0	Modify APIs	03/14/2022
2.0.0	New version	11/29/2022
2.0.1	Modify APIs	04/11/2023
2.1.0	add more bf mode	12/14/2023

1. 概述¶

1.1. 算法说明¶

波束成形(Beamforming, BF)算法是对麦克风阵列获取的数据进行处理，抑制非目标语音方向声音的算法。

1.2. 注意¶

使用本算法前，请务必确认硬件通道顺序与软件通道顺序一致，否则算法结果是错误的。确认方法为：每次录制音频时堵住一个麦克风，收集音频中没有声音的通道即为该麦克风对应的软件通道。重复上述测试，直到确定出每个麦克风对应的通道，如果硬件通道顺序与软件通道顺序不一致，请调整顺序后再送入算法运行。
算法输入与ALSA一致，即每个通道交替，以四通道为例，输入顺序为：

Chn0 Chn1 Chn2 Chn3 Chn0 Chn1 Chn2 Chn3 Chn0 Chn1 Chn2 Chn3
本算法目前最大支持6麦线形阵列和圆形阵列，其通道顺序与硬件排列如下图所示：

图1.1: 2麦线形阵列通道排列

图1.2: 4麦线形阵列通道排列

图1.3: 4麦圆型阵列通道排列

2. API 参考¶

2.1. 功能模块API¶

API名称	功能
IaaBf_GetBufferSize	获取BF算法运行需要的内存大小
IaaBf_Init	初始化BF算法
IaaBf_GetInputSamples	获取BF算法输入的采样点数
IaaBf_SetConfig	设置BF算法参数
IaaBf_GetConfig	打印BF算法参数
IaaBf_Run	BF算法处理
IaaBf_Free	释放BF算法资源
IaaSsl_setCallbackFunc	BF算法验证回调函数

2.2. IaaBf_GetBufferSize¶

功能

获取BF算法运行所需要的内存大小。
语法
```
int IaaBf_GetBufferSize(void);
```
形参

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

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

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

无。

2.3. IaaBf_Init¶

功能

初始化BF算法需要的内存。

语法

BF_HANDLE IaaBf_Init(char* workBufAddress, AudioBfInit_t *bfInit);

形参

参数名称描述输入/输出

workBufAddress BF算法使用的内存地址输入

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

返回值结果

handle 成功

NULL 失败
依赖
- 头文件: AudioBFProcess.h
- 库文件: libBF100_LINUX.so/ libBF100_LINUX.a
举例

无。

2.4. IaaBf_GetInputSamples¶

功能

初始化BF算法输入所需的总样本数。

语法

int IaaBf_GetInputSamples(BF_HANDLE handle, int *samples);

形参

参数名称描述输入/输出

handle BF算法handle 输入

samples BF算法输入样本数目输出
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioBFProcess.h
- 库文件: libBF100_LINUX.so/ libBF100_LINUX.a
注意
- 此函数非必须使用。

2.5. IaaBf_SetConfig¶

功能

初始化BF算法需要的参数。

语法

int IaaBf_SetConfig(BF_HANDLE handle, AudioBfConfig_t *bfConfig);

形参

参数名称描述输入/输出

handle BF算法handle 输入

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

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioBFProcess.h
- 库文件: libBF100_LINUX.so/ libBF100_LINUX.a
举例

无。

2.6. IaaBf_GetConfig¶

功能

打印BF算法运行时的参数。
语法
```
int IaaBf_GetConfig(BF_HANDLE handle);
```
形参

参数名称描述输入/输出

handle BF算法handle 输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioBFProcess.h
- 库文件: libBF100_LINUX.so/ libBF100_LINUX.a
举例

无。

2.7. IaaBf_Run¶

功能

BF算法处理

语法

int IaaBf_Run(BF_HANDLE handle, const short *input,  short *output, int angle);

形参

参数名称描述输入/输出

handle 算法handle 输入

input 输入数据输入

output BF算法输出输出

angle 声源位置角度输入
返回值

返回值结果

0 成功

其他值失败，参照错误码
依赖
- 头文件: AudioBFProcess.h
- 库文件: libBF100_LINUX.so/ libBF100_LINUX.a
注意
- 所有通道采样率和采样位宽应该一致

2.8. IaaBf_Free¶

功能

释放BF算法的资源
语法
```
int IaaBf_Free(BF_HANDLE handle);
```
形参

参数名称描述输入/输出

handle BF算法handle 输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioBFProcess.h
- 库文件: libBF100_LINUX.so/ libBF100_LINUX.a
注意
- 必须先调用IaaBf_Free，再释放供BF算法所使用的内存。
举例

无。

2.9. IaaBf_setCallbackFunc¶

功能

BF算法验证回调函数（暂不支持）。

语法

int IaaBf_setCallbackFunc(int(*log)(const char *szFmt, ...),
                    int(*envSet)(char *key, char *par),
                    int(*envGetString)(char *var, char *buf, unsigned int size),
                    int(*envSave)(void),
                    int(*readUuid)(unsigned long long *u64Uuid));

依赖
- 头文件: AudioBFProcess.h
- 库文件: libSSL100_LINUX.so/ libSSL100_LINUX.a

3. BF 数据类型¶

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

数据类型	定义
MAX_MIC_CHANNEL_NUM	BF算法最大麦克风通道数目
COORDINATE_DIM	BF算法麦克风坐标维度
AudioBfInit_t	BF算法初始化数据结构体类型
AudioBfConfig_t	BF算法配置参数数据结构体类型
BfSampleRate_e	BF算法支持的采样率类型
BfMicGeometry_e	BF算法支持的阵列物理结构
BfAlgorithm_e	BF算法支持的算法
BF_HANDLE	BF算法句柄类型

3.2. MAX_MIC_CHANNEL_NUM¶

说明

定义BF算法最大麦克风通道数目。
定义
```
#define MAX_MIC_CHANNEL_NUM    (6)
```

3.3. COORDINATE_DIM¶

说明

定义BF算法麦克风坐标维度。
定义
```
#define COORDINATE_DIM        (2)
```

3.4. AudioBfInit_t¶

说明

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

定义

typedef struct{
    int sampleRate;
    int bitWidth;
    int micNum;
    int soundSpeed;

    BfAlgorithm_e bfAlgorithm;
    BfMicGeometry_e micGeometry;
    float micCoordinate[MAX_MIC_CHANNEL_NUM][COORDINATE_DIM];
}AudioBfInit_t;

成员

成员名称	描述
sampleRate	语音采样率
bitWidth	语音采样位宽
micNum	麦克风数目
soundSpeed	环境声速
bfAlgorithm	BF使用的算法
micGeometry	麦克风阵列物理结构
micCoordinate	麦克风阵列中麦克风的二维坐标，参考图1.1/1.2/1.3

注意事项
- 采样位宽只支持16bit。
相关数据类型及接口

IaaBf_Init

3.5. AudioBfConfig_t¶

说明

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

定义

typedef struct{
    float vadThreshold;
    float gain;
    int intensity;
}AudioBfConfig_t;

成员

成员名称	描述
vadThreshold	语音活动检测阈值。范围[0~1]，推荐值0.9。
gain	后置增益补偿范围[0~1]
intensity	BF强度，值越大，抑制程度越强取值范围：0~10，步长：1，推荐值 5

相关数据类型及接口

IaaBf_SetConfig

3.6. BfSampleRate_e¶

说明

BF算法支持的采样率类型。

定义

typedef enum{
    IAA_BF_SAMPLE_RATE_8000 = 8000,
    IAA_BF_SAMPLE_RATE_16000 = 16000,
    IAA_BF_SAMPLE_RATE_24000 = 24000,
    IAA_BF_SAMPLE_RATE_32000 = 32000,
    IAA_BF_SAMPLE_RATE_48000 = 48000,
}BfSampleRate_e;

成员

成员名称	描述
IAA_BF_SAMPLE_RATE_8000	8K采样率
IAA_BF_SAMPLE_RATE_16000	16K采样率
IAA_BF_SAMPLE_RATE_24000	24K采样率
IAA_BF_SAMPLE_RATE_32000	32K采样率
IAA_BF_SAMPLE_RATE_48000	48K采样率

相关数据类型及接口

AudioBfInit_t

3.7. BfMicGeometry_e¶

说明

BF算法支持麦克风阵列的物理结构。

定义

typedef enum{
    IAA_BF_LINEAR_ARRAY = 0,
    IAA_BF_CIRCULAR_ARRAY,
}BfMicGeometry_e;

成员

成员名称描述

IAA_BF_LINEAR_ARRAY 线形阵列

IAA_BF_CIRCULAR_ARRAY 圆形阵列
相关数据类型及接口

AudioBfInit_t

3.8. BfAlgorithm_e¶

说明

BF算法支持的算法类型。

定义

typedef enum{
    IAA_FIXED_BF = 0,
    IAA_ADAPTIVE_BF = 1,
    IAA_ADAPTIVE_NORMAL_BF = 2,
    IAA_ADAPTIVE_FAST_BF = 3,
}BfAlgorithm_e;

成员

成员名称	描述
IAA_FIXED_BF	固定波束成形
IAA_ADAPTIVE_BF	自适应波束成形
IAA_ADAPTIVE_NORMAL_BF	标准自适应波束成形
IAA_ADAPTIVE_FAST_BF	快速自适应波束成形

相关数据类型及接口

AudioBfInit_t

3.9. BF_HANDLE¶

说明

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

成员名称描述
相关数据类型及接口

IaaBf_Init IaaBf_SetConfig IaaBf_GetConfig IaaBf_Run IaaBf_Free

4. 错误码¶

BF API 错误码如表下所示：

错误码	宏定义	描述
0x00000000	ALGO_BF_RET_SUCCESS	BF运行成功
0x30000401	ALGO_BF_RET_INVALID_LICENSE	授权无效
0x30000402	ALGO_BF_RET_INVALID_HANDLE	HANDLE无效
0x30000403	ALGO_BF_RET_INVALID_SAMPLERATE	采样率不支持
0x30000404	ALGO_BF_RET_INVALID_BITWIDTH	采样位数不支持
0x30000405	ALGO_BF_RET_INVALID_MIC_SOUNDSPEED	声速不支持
0x30000406	ALGO_BF_RET_INVALID_MIC_NUM	麦克风数目不支持
0x30000407	ALGO_BF_RET_INVALID_MIC_GEOMETRY	麦克风几何结构不支持
0x30000408	ALGO_BF_RET_INVALID_BF_ALGORITHM	BF算法不支持
0x30000409	ALGO_BF_RET_INVALID_VAD_THRESHOLD	VAD阈值不支持
0x30000410	ALGO_BF_RET_INVALID_INTENSITY	强度不支持
0x30000411	ALGO_BF_RET_INVALID_GAIN	增益补偿不支持

参数名称	描述	输入/输出
workBufAddress	BF算法使用的内存地址	输入
bfInit	BF算法的初始化结构体指针	输入

参数名称	描述	输入/输出
handle	BF算法handle	输入
samples	BF算法输入样本数目	输出

参数名称	描述	输入/输出
handle	算法handle	输入
input	输入数据	输入
output	BF算法输出	输出
angle	声源位置角度	输入

成员名称	描述
IAA_BF_LINEAR_ARRAY	线形阵列
IAA_BF_CIRCULAR_ARRAY	圆形阵列

返回值	结果
handle	成功
NULL	失败

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

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

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