SSU_BF100算法使用参考
REVISION HISTORY¶
Revision No. | Description |
Date |
---|---|---|
1.0.0 | 08/02/2021 | |
1.1.0 | 03/14/2022 | |
2.0.0 | 11/29/2022 |
1. 概述¶
1.1. 算法说明¶
波束成形(Beamforming, BF)算法是对麦克风阵列获取的数据进行处理,抑制非目标语音方向声音的算法。
1.2. 注意¶
-
使用本算法前,请务必确认硬件通道顺序与软件通道顺序一致,否则算法结果是错误的。确认方法为:每次录制音频时堵住一个麦克风,收集音频中没有声音的通道即为该麦克风对应的软件通道。重复上述测试,直到确定出每个麦克风对应的通道,如果硬件通道顺序与软件通道顺序不一致,请调整顺序后再送入算法运行。
-
算法输入与ALSA一致,即每个通道交替,以四通道为例,输入顺序为:
Chn0 Chn1 Chn2 Chn3 Chn0 Chn1 Chn2 Chn3 Chn0 Chn1 Chn2 Chn3
-
本算法目前最大支持2/4麦线形阵列和4麦圆形阵列,其通道顺序与硬件排列如下图所示:
图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);
-
形参
参数名称 描述 输入/输出 handle BF算法handle 输入 -
返回值
返回值 结果 其他值 成功 -1 失败 -
依赖
-
头文件: 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模块相关数据类型定义¶
数据类型 | 定义 |
---|---|
AudioBfInit_t | BF算法初始化数据结构体类型 |
AudioBfConfig_t | BF算法配置参数数据结构体类型 |
BfSampleRate_e | BF算法支持的采样率类型 |
BfMicGeometry_e | BF算法支持的阵列物理结构 |
BfAlgorithm_e | BF算法支持的算法 |
BF_HANDLE | BF算法句柄类型 |
3.2. AudioBfInit_t¶
-
说明
定义BF算法的配置参数结构体。
-
定义
typedef struct{ int sampleRate; int bitWidth; int micNum; int soundSpeed; BfAlgorithm_e bfAlgorithm; BfMicGeometry_e micGeometry; float micCoordinate[4][2]; }AudioBfInit_t;
-
成员
成员名称 描述 sampleRate 语音采样率 bitWidth 语音采样位宽 micNum 麦克风数目 soundSpeed 环境声速 bfAlgorithm BF使用的算法 micGeometry 麦克风阵列物理结构 micCoordinate 麦克风阵列中麦克风二的维坐标,参考图1.1/1.2/1.3 -
注意事项
- 采样位宽只支持16bit。
-
相关数据类型及接口
3.3. AudioBfConfig_t¶
-
说明
定义BF算法的参数配置参数结构体。
-
定义
typedef struct { float vadThreshold; int intensity; }AudioBfConfig_t;
-
成员
成员名称 描述 vadThreshold 语音活动检测阈值。 范围[0~1],推荐值0.9。 intensity BF强度,值越大,抑制程度越强 取值范围:0~10,步长:1,推荐值 5 -
相关数据类型及接口
3.4. 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采样率 -
相关数据类型及接口
3.5. BfMicGeometry_e¶
-
说明
BF算法支持麦克风阵列的物理结构。
-
定义
typedef enum{ IAA_BF_UNIFORM_LINEAR_ARRAY = 0, IAA_BF_UNIFORM_CIRCULAR_ARRAY, }BfMicGeometry_e;
-
成员
成员名称 描述 IAA_BF_UNIFORM_LINEAR_ARRAY 均匀线形阵列 IAA_BF_UNIFORM_CIRCULAR_ARRAY 均匀圆形阵列 -
相关数据类型及接口
3.6. BfMicGeometry_e¶
-
说明
BF算法支持的算法类型。
-
定义
typedef enum{ IAA_FIXED_BF = 0, IAA_ADAPTIVE_BF = 1, }BfAlgorithm_e;
-
成员
成员名称 描述 IAA_FIXED_BF 固定波束成形 IAA_ADAPTIVE_BF 自适应波束成形 -
相关数据类型及接口
3.7. BF_HANDLE¶
-
说明
定义BF算法的句柄类型。
-
定义
typedef void* BF_HANDLE;
-
成员
成员名称 描述 -
相关数据类型及接口
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 | 强度不支持 |