MI SSL API

Version 1.1

1. 概述¶

1.1. 算法说明¶

SSL（Sound Source Localization）声源定位，用于定位声音来源的方向。

1.2. 关键词说明¶

Direction

当两个麦克风距离(distance)为5cm时，下图描述音源方向(direction)来源的定义:

1.3. 注意¶

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

2. API 参考¶

2.1. 功能模块API¶

API名	功能
IaaSsl_GetBufferSize	获取Ssl算法运行需要的内存大小
IaaSsl_Init	初始化Ssl算法
IaaSsl_Config	配置Ssl算法
IaaSsl_Get_Config	获取Ssl算法当前的配置参数信息
IaaSsl_Run	Ssl算法处理
IaaSsl_Get_Direction	获取Ssl算法处理的结果
IaaSsl_Reset	重新初始化Ssl算法
IaaSsl_Free	释放Ssl算法资源

2.2. IaaSsl_GetBufferSize¶

功能

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

语法

unsigned int IaaSsl_GetBufferSize(void);

形参

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

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

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

请参考IaaSsl_Run举例部分。

2.3. IaaSsl_Init¶

功能

初始化Ssl算法。

语法

SSL_HANDLE IaaSsl_Init(char* working_buffer,AudioSslInit* ssl_init);

形参

参数名称描述输入/输出

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

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

返回值结果

非NULL 成功

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

无。
举例

请参考IaaSsl_Run举例部分。

2.4. IaaSsl_Config¶

功能

配置Ssl算法。

语法

ALGO_SSL_RET IaaSsl_Config(SSL_HANDLE handle,AudioSslConfig* ssl_config);

形参

参数名称描述输入/输出

handle Ssl算法handle 输入

ssl_config Ssl算法的配置结构体指针输入
返回值

返回值结果

0 成功

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

无。
举例

请参考IaaSsl_Run举例部分。

2.5. IaaSsl_Get_Config¶

功能

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

语法

ALGO_SSL_RET IaaSsl_Get_Config(SSL_HANDLE handle,AudioSslConfig *ssl_config);

形参

参数名称描述输入/输出

handle Ssl算法handle 输入

ssl_config Ssl算法的配置结构体指针输出
返回值

返回值结果

0 成功

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

无。
举例

请参考IaaSsl_Run举例部分。

2.6. IaaSsl_Run¶

功能

Ssl算法处理

语法

ALGO_SSL_RET IaaSsl_Run(SSL_HANDLE handle,short* microphone_input, int *delay_sample);

形参

参数名称	描述	输入/输出
handle	Ssl算法handle	输入
microphone_input	待进行声源定位的数据指针	输入
delay_sample	麦克风双声道的延迟样本数。此值建议当bf_mode开启时再拿作使用。	输出

返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioSslProcess.h
- 库文件: libSSL_LINUX.so/ libSSL_LINUX.a
注意
- microphone_input指向的数据应以采样点为最小单位，按照L,R,L,R…的格式摆放。数据长度必须和IaaSsl_Init中设定的point_number（即多少个采样点进行一个声源定位处理）相对应。假设point number设定为128，则每个frame需读取128*2的点样本数，因为SSL的microphone_input必定为双声道。

举例

#include <stdio.h>  
#include <stdlib.h>

#include "AudioSslProcess.h"

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

int main(int argc, char *argv[])  
{  
    AudioSslInit ssl_init;  
    AudioSslConfig ssl_config;  
    /**************User change section start**********************/  
    /* The user modifies as needed,for example:5, 6(Unit: cm) */  
    ssl_init.mic_distance = 5;  
    /* The user modifies as needed,for example:128, ... */  
    ssl_init.point_number = 128;  
    /* The user modifies as needed */  
    ssl_init.sample_rate = 48000;  
    /* The user modifies as needed */  
    ssl_init.bf_mode = 0;  
    /* The user modifies as needed */  
    ssl_config.temperature = 25;  
    /* The user modifies as needed */  
    ssl_config.noise_gate_dbfs = -40;  
    /* The user modifies as needed */  
    ssl_config.direction_frame_num = 100;  
    /**************User change section end**********************/  
    unsigned int workingBufferSize;  
    SSL_HANDLE handle;  
    ALGO_SSL_RET ret = ALGO_SSL_RET_SUCCESS;  
    int delay_sample = 0;  
    int direction;  
    int counter = 0;  
    int frame_number = ssl_config.direction_frame_num;  
    short input[1024];  
    char *workingBufferAddress = NULL;  
    FILE* fpIn;  //input file  
    char src_file[128] = {0};

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

    fpIn = fopen(src_file, "rb");  
    if(NULL == fpIn)  
    {  
        printf("fopen in_file failed !\n");  
        return -1;  
    }  
    printf("\nfopen in_file success !\n");  
    //(1)IaaSsl_GetBufferSize  
    workingBufferSize = IaaSsl_GetBufferSize();  
    workingBufferAddress = (char *)malloc(sizeof(char) * workingBufferSize);  
    if(NULL == workingBufferAddress)  
    {  
        printf("malloc SSL workingBuffer failed !\n");  
        return -1;  
    }  
    printf("malloc SSL workingBuffer success !\n");  
    //(2)IaaSsl_Init  
    handle = IaaSsl_Init(workingBufferAddress, &ssl_init);  
    if(NULL == handle)  
    {  
        printf("SSL:IaaSsl_Init  failed !\n");  
        return -1;  
    }  
    printf("SSL:IaaSsl_Init  success !\n");  
    //(3)IaaSsl_Config  
    ret = IaaSsl_Config(handle, &ssl_config);  
    if(ALGO_SSL_RET_SUCCESS != ret)  
    {  
        printf("SSL:IaaSsl_Config  failed !, ret = %d\n", ret);  
        return -1;  
    }  
    printf("SSL:IaaSsl_Config  success !\n");  
    ret = IaaSsl_Get_Config(handle, &ssl_config);  
    if(ALGO_SSL_RET_SUCCESS != ret)  
    {  
        printf("IaaSsl_Get_Config failed !, ret = %d\n", ret);  
    }  
    printf("IaaSsl_Get_Config succeed !\n");  
    printf("ssl_config.temperature = %u\n", ssl_config.temperature);  
    printf("ssl_config.noise_gate_dbfs = %d\n", ssl_config.noise_gate_dbfs);  
    printf("ssl_config.direction_frame_num = %d\n", ssl_config.direction_frame_num);  
#if 1  
    /*Consider whether the input file has a header*/  
    fread(input, sizeof(char), 44, fpIn); // Remove the 44 bytes header  
#endif  
    while(1)  
    {  
        /*2 is the number of channels*/  
        ret = fread(input, sizeof(short), ssl_init.point_number * 2, fpIn);  
        if(ret != ssl_init.point_number * 2)  
        {  
            printf("break:endReadSize = The remaining size = %d.\n", ret);  
            break;  
        }  
        //(4)IaaSsl_Run  
        ret = IaaSsl_Run(handle, input, &delay_sample);  
        if(ALGO_SSL_RET_SUCCESS != ret)  
        {  
            printf("SSL:IaaSsl_Run  failed !, ret = %d\n", ret);  
        }  
        counter ++;  
        if(counter == frame_number && ssl_init.bf_mode == 0)  
        {  
            //(5)IaaSsl_Get_Direction  
            ret = IaaSsl_Get_Direction(handle, &direction);  
            if(ALGO_SSL_RET_SUCCESS != ret)  
            {  
                printf("SSL:IaaSsl_Get_Direction  failed !, ret = %d\n", ret);  
            }  
            printf("The current direction:%d \n", direction);  
            handle = IaaSsl_Reset(handle, &ssl_init);  
            if(NULL == handle)  
            {  
                printf("SSL:IaaSsl_Reset failed !\n");  
                return -1;  
            }  
            ret = IaaSsl_Config(handle, &ssl_config);  
            if(ALGO_SSL_RET_SUCCESS != ret)  
            {  
                printf("SSL:IaaSsl_Config failed !, ret = %d\n", ret);  
                return -1;  
            }  
            counter = 0;  
        }  
    }  
    printf("Explain:If the current direction is not \  
    in the -90~90 range, consult the API documentation.\n");  
    //(6)IaaSsl_Free  
    ret = IaaSsl_Free(handle);  
    if(ALGO_SSL_RET_SUCCESS != ret)  
    {  
        printf("IaaSsl_Free failed !, ret = %d\n", ret);  
    }  
    free(workingBufferAddress);  
    fclose(fpIn);  
    printf("SSL end !\n");  
    return 0;  
}

2.7. IaaSsl_Get_Direction¶

功能

获取Ssl算法的处理结果

语法

ALGO_SSL_RET IaaSsl_Get_Direction(SSL_HANDLE handle, int* direction);

形参

参数名称	描述	输入/输出
handle	Ssl算法handle	输入
direction	此数值介于-90~90之间。当数值为-112时，若返回值为成功，则有两种可能，其一为音量低于noise_gate_dbfs，另一则为数据量不够，无法计算出可信的方向。若返回值不为0，则依错误码修正。	输出

返回值

返回值结果

0 成功

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

无。
举例

请参考IaaSsl_Run举例部分。

2.8. IaaSsl_Reset¶

功能

重新初始化Ssl算法。

语法

SSL_HANDLE IaaSsl_Reset(SSL_HANDLE working_buffer,AudioSslInit* ssl_init);

形参

参数名称描述输入/输出

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

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

返回值结果

0 成功

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

无。
举例

请参考IaaSsl_Run举例部分。

2.9. IaaSsl_Free¶

功能

释放Ssl算法资源

语法

ALGO_SSL_RET IaaSsl_Free(SSL_HANDLE handle);

形参

参数名称描述输入/输出

handle Src算法handle 输入
返回值

返回值结果

0 成功

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

无。
举例

请参考IaaSsl_Run举例部分。

3. SSL 数据类型¶

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

数据类型	定义
AudioSslInit	Ssl算法初始化参数结构体类型
AudioSslConfig	Ssl算法配置参数结构体类型
SSL_HANDLE	Ssl算法句柄类型

3.2. AudioSslInit¶

说明

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

定义

typedef struct

{

    unsigned int point_number;

    unsigned int sample_rate;

    unsigned int mic_distance;

    unsigned int bf_mode;

}AudioSslInit;

成员

成员名称	描述
point_number	Ssl算法处理一次的采样点数
sample_rate	取样率，目前支持8k/16k/32k/48k
mic_distance	两个mic的距离，单位为cm
bf_mode	是否为beamforming模式

注意事项
- 若需delay_sample 则建议将bf_mode开启。
相关数据类型及接口

IaaSsl_Init

IaaSsl_Reset

3.3. AudioSslConfig¶

说明

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

定义

typedef struct

{

    unsigned int temperature;

    int noise_gate_dbfs;

    int direction_frame_num;

}AudioSslConfig;

成员

成员名称	描述
temperature	环境温度（摄氏度）摄氏度＝(5/9)*(华氏度－32) 步长为1
noise_gate_dbfs	噪音增益门限值（dBfs）注意：低于此值将会把该帧作为噪声部分处理，则不会进入方向的计算。步长为1
direction_frame_num	声源定位功能检测的帧数步长为50 注意：进行声源定位检测的帧数，数值必须为50的倍数，声源定位处理的一帧数据为128个采样点。检测一次的时间 = s32DirectionFrameNum * 128 / 采样率。如：当前采样率为48K，s32DirectionFrameNum设置成300，则检测时间=300 * 128 / 48000 = 0.8(s)

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

IaaSsl_Config

IaaSsl_Get_Config

3.4. SSL_HANDLE¶

说明

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

成员名称描述
注意事项

无
相关数据类型及接口

IaaSsl_Init

IaaSsl_Config

IaaSsl_Get_Config

IaaSsl_Run

IaaSsl_Get_Direction

IaaSsl_Reset

IaaSsl_Free

4. 错误码¶

SSL API 错误码如下表所示：

表 4‑1 SSL API错误码

错误码	宏定义	描述
0x00000000	ALGO_ SSL _RET_SUCCESS	SSL执行成功
0x10000101	ALGO_ SSL _RET_INIT_ERROR	SSL初始化错误
0x10000102	ALGO_ SSL _RET_INVALID_CONFIG	SSL Config无效
0x10000103	ALGO_ SSL _RET_INVALID_HANDLE	SSL Handle无效
0x10000104	ALGO_ SSL _RET_INVALID_SAMPLERATE	SSL采样率无效
0x10000105	ALGO_ SSL _RET_INVALID_POINTNUMBER	SSL采样点数无效
0x10000106	ALGO_SSL_RET_INVALID_BFMODE	SSL init 的bf_mode设置无效
0x10000107	ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE	延迟样本过大，请检查设定的距离和取样率
0x10000108	ALGO_ SSL _RET_INVALID_CALLING	SSL呼叫API顺序错误
0x10000109	ALGO_ SSL _RET_API_CONFLICT	有其他API正在运行

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

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

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

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

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

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