SSTAR_SSL100算法使用参考

REVISION HISTORY¶

Revision No.	Description	Date
1.0.0	Initial release	07/12/2021
1.1.0	Modify some APIs	04/06/2022
2.0.0	New version	11/29/2022
2.0.1	Modify APIs	04/11/2023

1. 概述¶

1.1. 算法说明¶

声源定位(Sound Source Localization, SSL)算法是对麦克风阵列获取的数据进行处理，从而获得声源方向的算法。

1.2. 注意¶

本算法工作推荐采样率至少为16kHz，每一帧长度为4096个采样点。
使用本算法前，请务必确认硬件通道顺序与软件通道顺序一致，否则算法结果是错误的。确认方法为：每次录制音频时堵住一个麦克风，收集音频中没有声音的通道即为该麦克风对应的软件通道。重复上述测试，直到确定出每个麦克风对应的通道，如果硬件通道顺序与软件通道顺序不一致，请调整顺序后再送入算法运行。
算法输入与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名称	功能
IaaSsl_GetBufferSize	获取SSL算法运行需要的内存大小
IaaSsl_Init	初始化SSL算法
IaaSsl_SetConfig	设置SSL算法参数
IaaSsl_GetConfig	打印SSL算法参数
IaaSsl_GetInputSamples	获取SSL算法输入的采样点数
IaaSsl_Run	SSL算法处理
IaaSsl_Free	释放SSL算法资源
IaaSsl_setCallbackFunc	SSL算法验证回调函数

2.2. IaaSsl_GetBufferSize¶

功能

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

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

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

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

无。

2.3. IaaSsl_Init¶

功能

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

语法

SSL_HANDLE IaaSsl_Init(char* workBufAddress, AudioSslInit_t *sslInit);

形参

参数名称描述输入/输出

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

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

返回值结果

handle 成功

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

无。

2.4. IaaSsl_SetConfig¶

功能

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

语法

int IaaSsl_SetConfig(SSL_HANDLE handle, AudioSslConfig_t *sslConfig);

形参

参数名称描述输入/输出

handle SSL算法handle 输入

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

返回值结果

0 成功

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

无。

2.5. IaaSsl_GetConfig¶

功能

打印SSL算法需要的参数。

语法

int IaaSsl_GetConfig(SSL_HANDLE handle);

形参

参数名称描述输入/输出

handle SSL算法handle 输入
返回值

返回值结果

0 成功

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

无。

2.6. IaaSsl_GetInputSamples¶

功能

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

语法

int IaaSsl_GetInputSamples(SSL_HANDLE handle, int *samples);

形参

参数名称描述输入/输出

0 成功

非0 失败，参照错误码
返回值

返回值结果

输入长度成功

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

2.7. IaaSsl_Run¶

功能

SSL算法处理。

语法

int IaaSsl_Run(SSL_HANDLE handle, const short *data, int *doa);

形参

参数名称描述输入/输出

handle 算法handle 输入

data 输入数据输入

doa 声源角度值输出
返回值

返回值结果

0 成功

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

参考Demo code。

2.8. IaaSsl_Free¶

功能

释放SSL算法的资源
语法
```
int IaaSsl_Free(SSL_HANDLE handle);
```
形参

参数名称描述输入/输出

handle SSL算法handle 输入
返回值

返回值结果

0 成功

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

无。

2.9. IaaSsl_setCallbackFunc¶

功能

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

语法

int IaaSsl_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));

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

3. SSL 数据类型¶

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

数据类型	定义
MAX_MIC_CHANNEL_NUM	SSL算法最大麦克风通道数目
COORDINATE_DIM	SSL算法麦克风坐标维度
AudioSslInit_t	SSL算法初始化数据结构体类型
AudioSslConfig_t	SSL算法配置参数数据结构体类型
SslSampleRate_e	SSL算法支持的采样率类型
SslMicGeometry_e	SSL算法支持的阵列物理结构
SslTrackSpeed_e	SSL算法支持的跟踪速度
SSL_HANDLE	SSL算法句柄类型

3.2. MAX_MIC_CHANNEL_NUM¶

说明

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

3.3. COORDINATE_DIM¶

说明

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

3.4. AudioSslInit_t¶

说明

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

定义

typedef struct{
    int sampleRate;
    int bitWidth;
    int micNum;
    float soundSpeed;
    float micCoordinate[SSL_MAX_MIC_CHANNEL_NUM][SSL_COORDINATE_DIM];
    SslMicGeometry_e micGeometry;
}AudioSslInit_t;

成员

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

注意事项
- 采样位宽只支持16bit
- 采样率推荐值大于8kHz
相关数据类型及接口

IaaSsl_Init

3.5. AudioSslConfig_t¶

说明

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

定义

typedef struct{
    int vadThreshold;
    int lowFreq;
    int highFreq;
    int sslResolution;
    int interval;
    int trackSpeed;
}AudioSslConfig_t;

成员

成员名称	描述
sslResolution	声源定位搜索步长，值越大，搜索步长越大，运行时间越短线形阵列取值范围: 1~180, 步长：1, 推荐值：5 圆形阵列取值范围: 1~360, 步长：1, 推荐值：5
vadThreshold	语音活动检测阈值，值越小，激活算法的声音要求能量越高取值范围：[-80, 0], 根据实际使用情况设置
lowFreq	算法使用声音频率下限取值范围：0~采样率/2, 且必须小于highFreq
highFreq	算法使用声音频率上限取值范围：0~采样率/2, 且必须大于lowFreq
interval	算法检测间隔
trackSpeed	声源跟踪速度

相关数据类型及接口

IaaSsl_SetConfig

3.6. SslSampleRate_e¶

说明

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

定义

typedef enum{
    IAA_SSL_SAMPLE_RATE_8000 = 8000,
    IAA_SSL_SAMPLE_RATE_16000 = 16000,
    IAA_SSL_SAMPLE_RATE_24000 = 24000,
    IAA_SSL_SAMPLE_RATE_32000 = 32000,
    IAA_SSL_SAMPLE_RATE_48000 = 48000,
}SslSampleRate_e;

成员

成员名称	描述
IAA_SSL_SAMPLE_RATE_8000	8K采样率
IAA_SSL_SAMPLE_RATE_16000	16K采样率
IAA_SSL_SAMPLE_RATE_24000	24K采样率
IAA_SSL_SAMPLE_RATE_32000	32K采样率
IAA_SSL_SAMPLE_RATE_48000	48K采样率

注意事项
- 推荐使用大于8kHz采样率。
相关数据类型及接口

AudioSslInit_t

3.7. SslMicGeometry_e¶

说明

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

定义

typedef enum{
    IAA_SSL_LINEAR_ARRAY = 0,
    IAA_SSL_CIRCULAR_ARRAY,
}SslMicGeometry_e;

成员

成员名称描述

IAA_SSL_LINEAR_ARRAY 线形阵列

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

AudioSslInit_t

3.8. SslTrackSpeed_e¶

说明

SSL算法支持的跟踪速度

定义

typedef enum
{
    IAA_SSL_TRACK_SPEED_SLOW = 0,
    IAA_SSL_TRACK_SPEED_NORM,
    IAA_SSL_TRACK_SPEED_FAST,
}SslTrackSpeed_e;

成员

成员名称描述

IAA_SSL_TRACK_SPEED_SLOW 声源跟踪速度慢

IAA_SSL_TRACK_SPEED_NORM 声源跟踪速度中

IAA_SSL_TRACK_SPEED_FAST 声源跟踪速度快
相关数据类型及接口

AudioSslConfig_t

3.9. SSL_HANDLE¶

说明

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

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

IaaSsl_Init

IaaSsl_SetConfig

IaaSsl_GetConfig

IaaSsl_Free

IaaSsl_Run

4. 错误码¶

SSL API 错误码如表下所示：

错误码	宏定义	描述
0x00000000	ALGO_SSL_RET_SUCCESS	SSL运行成功
0x20000401	ALGO_SSL_RET_INVALID_LICENSE	LICENSE无效
0x20000402	ALGO_SSL_RET_INVALID_HANDLE	HANDLE无效
0x20000403	ALGO_SSL_RET_INVALID_SAMPLERATE	采样率不支持
0x20000404	ALGO_SSL_RET_INVALID_BITWIDTH	采样位数不支持
0x20000405	ALGO_SSL_RET_INVALID_MIC_COORDINATE	麦克风阵列坐标不支持
0x20000406	ALGO_SSL_RET_INVALID_VAD_LEVEL	语音活动检测等级不支持
0x20000407	ALGO_SSL_RET_INVALID_FREQRANGE	频率范围不支持
0x20000408	ALGO_SSL_RET_INVALID_SSL_RESOLUTION	声源定位搜索步长不支持
0x20000409	ALGO_SSL_RET_INVALID_INTERVAL	声源定位计算间隔不支持
0x2000040A	ALGO_SSL_RET_INVALID_TRACK_SPEED	声源定位跟踪速度不支持

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

参数名称	描述	输入/输出
handle	SSL算法handle	输入
sslConfig	SSL算法的初始化结构体指针	输入

参数名称	描述	输入/输出
handle	算法handle	输入
data	输入数据	输入
doa	声源角度值	输出

成员名称	描述
IAA_SSL_LINEAR_ARRAY	线形阵列
IAA_SSL_CIRCULAR_ARRAY	圆形阵列

成员名称	描述
IAA_SSL_TRACK_SPEED_SLOW	声源跟踪速度慢
IAA_SSL_TRACK_SPEED_NORM	声源跟踪速度中
IAA_SSL_TRACK_SPEED_FAST	声源跟踪速度快

返回值	结果
handle	成功
NULL	失败

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

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

参数名称	描述	输入/输出
0	成功
非0	失败，参照错误码