SSTAR_KWS算法使用参考

REVISION HISTORY¶

Revision No.	Description	Date
1.0.0	Initial release	05/01/2021
2.0.0	2.0 version	11/29/2022
2.0.1	remove c++ code in header	04/11/2023
2.0.2	modify parameters for multi-keywords and ipu model	07/14/2023
2.1.0	add new vad mode; support to set keywords in IaaKws_Init	08/08/2023
2.1.1	add break duration parameter	12/14/2023

1. 概述¶

1.1. 算法说明¶

语音唤醒（Keywords Spotting, KWS）是检测语音流中是否有指定唤醒词的算法。

1.2. 注意¶

唤醒词支持定制，有需要请联系FAE。

2. API 参考¶

2.1. 功能模块API¶

API名称	功能
IaaKws_GetBufferSize	获取KWS算法运行需要的内存大小
IaaKws_Init	初始化KWS算法
IaaKws_SetConfig	设置KWS算法参数
IaaKws_ResetConfig	重置KWS算法参数
IaaKws_GetConfig	打印KWS算法参数
IaaKws_GetInputSamples	获取KWS算法输入的采样点数
IaaKws_Run	KWS算法处理
IaaKws_Free	释放KWS算法资源
IaaKws_setCallbackFunc	KWS算法验证回调函数

2.2. IaaKws_GetBufferSize¶

功能

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

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

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

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

无。

2.3. IaaKws_Init¶

功能

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

语法

KWS_HANDLE IaaKws_Init(AudioKwsInit_t *kwsInit);

形参

参数名称描述输入/输出

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

返回值结果

handle 成功

NULL 失败
依赖
- 头文件: AudioKwsProcess.h
- 库文件: libKWS_LINUX.so/ libKWS_LINUX.a
注意
- KWS算法仅支持16kHz采样率，16bit采样位宽。
举例

无。

2.4. IaaKws_SetConfig¶

功能

设置KWS算法参数。

语法

int IaaKws_SetConfig(KWS_HANDLE handle, AudioKwsConfig_t kwsConfig);

形参

参数名称描述输入/输出

handle KWS算法handle 输入

kwsConfig KWS算法参数设置结构体输入
返回值

返回值结果

0 成功

其他值失败, 参照错误码
依赖
- 头文件: AudioKwsProcess.h
- 库文件: libKWS_LINUX.so/ libKWS_LINUX.a

2.5. IaaKws_ResetConfig¶

功能

重置KWS算法参数。

语法

int IaaKws_ResetConfig(KWS_HANDLE handle, AudioKwsConfig_t kwsConfig);

形参

参数名称描述输入/输出

handle KWS算法handle 输入

kwsConfig KWS算法参数设置结构体输入
返回值

返回值结果

0 成功

其他值失败, 参照错误码
依赖
- 头文件: AudioKwsProcess.h
- 库文件: libKWS_LINUX.so/ libKWS_LINUX.a

2.6. IaaKws_GetConfig¶

功能

打印KWS算法运行时的参数。

语法

int IaaKws_GetConfig(KWS_HANDLE handle);

形参

参数名称描述输入/输出

handle KWS算法handle 输入
返回值

返回值结果

0 成功

其他值失败, 参照错误码
依赖
- 头文件: AudioKwsProcess.h
- 库文件: libKWS_LINUX.so/ libKWS_LINUX.a

2.7. IaaKws_GetInputSamples¶

功能

获取KWS算法输入样本点数目。

语法

int IaaKws_GetInputSamples(KWS_HANDLE handle, int *samples);

形参

参数名称描述输入/输出

handle KWS算法handle 输入

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

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

依赖
- 头文件: AudioKwsProcess.h
- 库文件: libKWS_LINUX.so/ libKWS_LINUX.a

2.8. IaaKws_Run¶

功能

KWS算法处理函数。

语法

int IaaKws_Run(KWS_HANDLE handle, short *input, int *kwsIndex);

形参

参数名称描述输入/输出

handle 算法handle 输入

input 输入数据指针输入

kwsIndex 命令词索引输出
返回值

返回值结果

0 成功

其他值失败，参照错误码
依赖
- 头文件: AudioKwsProcess.h
- 库文件: libKWS_LINUX.so/ libKWS_LINUX.a
举例

参考Demo code

2.9. IaaKws_Free¶

功能

释放KWS算法的资源。
语法
```
int IaaKws_Free(KWS_HANDLE handle);
```
形参

参数名称描述输入/输出

handle KWS算法handle 输入
返回值

返回值结果

0 成功

其他值失败，参照错误码
依赖
- 头文件: AudioKwsProcess.h
- 库文件: libKWS_LINUX.so/ libKWS_LINUX.a
注意
- 必须先调用IaaKws_Free，再释放供KWS算法所使用的内存。

2.10. IaaKws_setCallbackFunc¶

功能

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

语法

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

依赖
- 头文件: AudioKwsProcess.h
- 库文件: libKWS_LINUX.so/ libKWS_LINUX.a

3. KWS 数据类型¶

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

数据类型	定义
KWS_MAX_FILE_NAME_LEN	KWS算法文件名称最大长度
KWS_MAX_NUM	KWS算法最大命令词数目
KWS_MAX_LEN	KWS算法最大命令词长度
AudioKwsInit_t	KWS算法初始化数据结构体类型
AudioKwsConfig_t	KWS算法参数设置结构体类型
KWS_HANDLE	KWS算法句柄类型

3.2. KWS_MAX_FILE_NAME_LEN¶

说明

定义KWS算法文件名称最大长度。
定义
```
#define KWS_MAX_FILE_NAME_LEN    (256)
```

3.3. KWS_MAX_NUM¶

说明

KWS算法最大命令词数目。
定义
```
#define KWS_MAX_NUM    (100)
```

3.4. KWS_MAX_LEN¶

说明

KWS算法最大命令词长度。
定义
```
#define KWS_MAX_LEN    (20)
```

3.5. AudioKwsInit_t¶

说明

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

定义

typedef struct{
    int sampleRate;
    int bitWidth;
    int channel;
    int ipuMaxSize;
    int keywordNum;
    char keywords[KWS_MAX_NUM][KWS_MAX_LEN];
    char modelPath[KWS_MAX_FILE_NAME_LEN];
    char graphPath[KWS_MAX_FILE_NAME_LEN];
    char dictPath[KWS_MAX_FILE_NAME_LEN];
}AudioKwsInit_t;

成员

成员名称	描述
sampleRate	语音采样率
bitWidth	语音采样位宽
channel	语音通道数
ipuMaxSize	IPU模型最大size
keywordNum	命令词数目
keywords	命令词列表
modelPath	模型路径
graphPath	解码图路径
dictPath	字典路径

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

IaaKws_Init

3.6. AudioKwsConfig_t¶

说明

定义KWS算法参数结构体。

定义

typedef struct{
    int vadMode;
    int breakDuration;
    float skipDuration;
    float vadThreshold;
    float kwsThreshold[KWS_MAX_NUM];
}AudioKwsConfig_t;

成员

成员名称	描述
vadMode	VAD模式, 0为能量检测模式，1为概率检测模式
breakDuration	语音间隔时间, 当语音之间间隔小于此值时，视为一句话
skipDuration	跳过检测时间
vadThreshold	声音活动检测阈值，VAD模式为0时，取值范围[-80,0]；VAD模式为1时，取值范围为[0,1]
kwsThreshold	关键词检测阈值，取值范围[-50,0]

相关数据类型及接口

IaaKws_SetConfig

IaaKws_ResetConfig

3.7. KWS_HANDLE¶

说明

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

成员名称描述
注意事项

无。
相关数据类型及接口

IaaKws_Init

IaaKws_SetConfig

IaaKws_ResetConfig

IaaKws_GetConfig

IaaKws_Free

IaaKws_Run

4. 错误码¶

KWS API 错误码如表下所示：

错误码	宏定义	描述
0x00000000	ALGO_KWS_RET_SUCCESS	KWS运行成功
0x90000401	ALGO_KWS_RET_INVALID_LICENSE	LICENSE无效
0x90000402	ALGO_KWS_RET_INVALID_HANDLE	HANDLE无效
0x90000403	ALGO_KWS_RET_INVALID_SAMPLERATE	采样率不支持
0x90000404	ALGO_KWS_RET_INVALID_BITWIDTH	采样位数不支持
0x90000405	ALGO_KWS_RET_INVALID_CHANNEL	模型不支持
0x90000406	ALGO_KWS_RET_INVALID_VAD_MODE	VAD模式不支持
0x90000407	ALGO_KWS_RET_INVALID_SKIP_DURATION	跳过时长不支持
0x90000408	ALGO_KWS_RET_INVALID_KWSTHRESHOLD	KWS阈值不支持
0x90000409	ALGO_KWS_RET_INVALID_VADTHRESHOLD	VAD阈值不支持
0x9000040A	ALGO_KWS_RET_INVALID_BREAK_DURATION	中断时长不支持

参数名称	描述	输入/输出
handle	KWS算法handle	输入
kwsConfig	KWS算法参数设置结构体	输入

参数名称	描述	输入/输出
handle	算法handle	输入
input	输入数据指针	输入
kwsIndex	命令词索引	输出

返回值	结果
0	成功
其他值	失败, 参照错误码

返回值	结果
0	成功
其他值	失败, 参照错误码

返回值	结果
0	成功
其他值	失败, 参照错误码