MI SSL API

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	09/12/2020
1.1	Modified API	10/15/2020
1.2	4MIC Sound Source Localization and Modified API	11/03/2021
1.3	4MIC_AI Mode, License CallBack, Digital Gain	12/05/2022
1.4	Add function IaaSsl_GetAPIVersion	04/10/2023

1. 概述¶

1.1. 算法说明¶

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

1.2. 关键词说明¶

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

当麦克风个数多于两颗以上，一般来说会有两种可能的阵列形状，分别是均匀线性阵列以及均匀圆形阵列。

1.3. 注意¶

1.3.1. 使用¶

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

1.3.2. 区分¶

不同通道数会对应到不同参考库。用户需要自行确认是否使用正确的通道数及对应参考库。

2. 阵列系统及坐标系¶

2.1. 多麦克风阵列¶

常见的多麦克风阵列主要有两类，分别是均匀线性阵列及均匀圆型阵列。以下皆为二维示意图(无高度差的影响)。

2.1.1. 均匀线性阵列及坐标系¶

均匀线性阵列为一直线排列，且相邻麦克风之间距(distance)皆相同，并且由于具有对称性，定位角度仅考虑上半平面(-90度至90度)。图2-1为均匀线性阵列于空间坐标系的示意图。声音方向的角度(microphone_doa)定义为与阵列中心及x轴的夹角。逆时钟方向为正。间距单位为公分，建议至少大于5 或 6公分。

图2-1 均匀线性阵列及其坐标系

2.1.2. 均匀圆型阵列及坐标系¶

均匀圆型阵列为一圆形排列，且相邻麦克风与阵列中心的夹角皆相同，麦克风间距即为圆型的直径，由于不具对称性，定位角度可以为整个平面(-90度至270度)，图2-2为均匀圆型阵列于空间坐标系的示意图。声音方向的角度(microphone_doa)定义为与阵列中心及x轴的夹角。逆时钟方向为正。distance 为圆型的直径。单位为公分。建议至少大于6cm

图2-2 均匀圆型阵列及坐标系

3. API参考¶

3.1. 功能模块API¶

API名	功能
IaaSsl_GetBufferSize	获取SSL算法运行需要的内存大小
IaaSsl_Init	初始化SSL算法
IaaSsl_Config	配置SSL算法
IaaSsl_Get_Config	获取SSL算法当前的配置参数信息
IaaSsl_Set_Shape	SSL指派麦克风阵列形状
IaaSsl_Cal_Params	SSL根据阵列形状计算参数
IaaSsl_Run	SSL算法处理
IaaSsl_Get_Direction	获取SSL算法处理的结果
IaaSsl_Reset_Mapping	当IaaSsl_Get_Direction完成后重新初始化定位缓冲区
IaaSsl_Reset	重新初始化SSL算法
IaaSsl_Free	释放SSL算法资源
IaaSsl_SetMode	选择SSL算法模式
IaaSsl_SetCallbackFunction	SSL 算法对Ikayaki芯片的授权管控
IaaSsl_ApplyDigitalGain	对输入数据做增益或衰减
IaaSsl_GetAPIVersion	返回当前SSL算法版号

3.2. IaaSsl_GetBufferSize¶

功能

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

语法

unsigned int IaaSsl_GetBufferSize(void);

返回值

返回值为SSL算法运行所需要的内存大小，此内存大小与使用的麦克风数有关。
依赖
- 头文件: AudioSslProcess.h
- 库文件: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a
注意

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

请参考IaaSsl_Run举例部分。

3.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_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a
举例

请参考IaaSsl_Run举例部分。

3.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_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a
举例

请参考IaaSsl_Run举例部分。

3.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_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a
举例

请参考IaaSsl_Run举例部分。

3.6. IaaSsl_Set_Shape¶

功能

SSL 指派阵列形状。

语法

ALGO_SSL_RET IaaSsl_Set_Shape(SSL_HANDLE handle,int shape);

形参

参数名称描述输入/输出

handle SSL算法handle 输入

shape 指派阵列形状。0:均匀线性阵列，1:均匀圆形阵列输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioSslProcess.h
- 库文件: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a
注意
- 仅提供均匀线性阵列及均匀圆型阵列(示意图请看图2-1及图2-2)，客户有特殊阵列需求，需告知修改
- 麦克风个数为2个时，只存在线性阵列，其间距即为所设定麦克风间距
- 阵列位置设定会强烈影响SSL效果，因此设定的阵列位置必须与真实阵列位置相同
举例

请参考IaaSsl_Run举例部分。

3.7. IaaSsl_Cal_Params¶

功能

SSL根据阵列形状计算其定位用的参数。

语法

ALGO_SSL_RET IaaSsl_Cal_Params(SSL_HANDLE handle);

形参

参数名称描述输入/输出

handle SSL算法handle 输入
返回值

返回值结果

0 成功

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

请参考IaaSsl_Run举例部分。

3.8. 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_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a
注意
- 对于两颗麦克风阵列(双声道音频可以负荷)，microphone_input指向的数据应以采样点为最小单位，按照L,R,L,R的格式摆放，数据长度必须和IaaSsl_Init中设定的point_number(即多少个采样点进行一次beamforming处理)相对应。→范例一
- 对于多颗麦克风阵列(麦克风数多于两颗，双声道音频无法负荷)的情况，各个麦克风音频须为单声道，microphone_input指向的数据仍应已采样点为最小单位，并按照麦克风于阵列的相对位置，由左至右的格式摆放，例如4颗线性麦克风阵列，摆放的方式为 [左一→左二→右二→右一]，数据长度必须和IaaBf_Init中设定的point_number(即多少个采样点进行一次SSL处理)相对应。→范例二
- 以图2-1及图2-2的麦克风阵列为例，microphone_input摆放的格式为[MIC1→MIC2→MIC3→MIC4]。

举例

范例一：两颗麦克风阵列(麦克风输入为双声道音频)

#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>
#include <string.h>
#include <sys/time.h>
#include <sys/ioctl.h>
#include <stdlib.h>
#include "AudioSslProcess.h"
#define MIC_NUM (2)
#define USE_MALLOC   (1)
typedef unsigned char               uint8;
typedef unsigned short              uint16;
typedef unsigned long               uint32;
unsigned int _OsCounterGetMs(void)
{
    struct  timeval t1;
    gettimeofday(&t1,NULL);
    unsigned int T = ( (1000000 * t1.tv_sec)+ t1.tv_usec ) / 1000;
    return T;
}

int main(int argc, char *argv[])
{
    /*******Input file init*********/
    short input[256];
    char infileName[512];
    char outfileName[512];
    FILE * fin;
    FILE * fout;
    ALGO_SSL_RET ret;
    int counter2 = 0;
    unsigned int T0,T1,T2,T3;
    float avg = 0.0;
    float avg2 = 0.0;
    /**********common setting SSL***************/
    int point_number = 128;
    float microphone_distance = 12.0;
    int temperature = 20;
    int sample_rate = 16000;
    int delay_sample[1] = {0};
    int shape = 0;
    int direction = 0;
    int frame_number = 32;
    /**************SSL data init***********/
    int counter = 0;
#if USE_MALLOC
    char *WorkingBuffer2;
    WorkingBuffer2 = (char*)malloc(IaaSsl_GetBufferSize());
#endif
    AudioSslInit ssl_init;
    AudioSslConfig ssl_config;
    SSL_HANDLE handle;
    ssl_init.mic_distance = microphone_distance; //cm
    ssl_init.point_number = point_number;
    ssl_init.sample_rate = sample_rate;
    ssl_init.bf_mode = 0;
    ssl_init.channel = MIC_NUM;
    ssl_config.temperature = temperature; //c
    ssl_config.noise_gate_dbfs = -80;
    ssl_config.direction_frame_num = frame_number;
    /******init algorithm********/
    handle = IaaSsl_Init((char*)WorkingBuffer2, &ssl_init);
    if (handle==NULL)
    {
        printf("SSL init error\n\r");
        return -1;
    }
    else
    {
        printf("SSL init succeed\n\r");
    }
    ret = IaaSsl_Config(handle ,&(ssl_config));
    if (ret)
    {
        printf("Error occured in SSL Config\n\r");
        return -1;
    }
    ret = IaaSsl_Set_Shape(handle,shape);
    if (ret)
    {
        printf("Error occured in Array shape\n\r");
        return -1;
    }
    ret = IaaSsl_Cal_Params(handle);
    if (ret)
    {
        printf("Error occured in Array matrix calculation\n\r");
        return -1;
    }
    sprintf(infileName,"%s","./../sample/data/Chn_Left_right_12_0.wav");
    sprintf(outfileName,"%s","./SSL_result.txt");

    fin = fopen(infileName, "rb");
    if(!fin)
    {
        printf("the input file 0 could not be open\n\r");
        return -1;
    }
    fout = fopen(outfileName, "w");
    if(!fout)
    {
        printf("the output file could not be open\n\r");
        return -1;
    }
    fread(input, sizeof(char), 44, fin); // read header 44 bytes
    fprintf(fout,"%s\t%s\t%s\n\r","time","direction","case");
    while(fread(input, sizeof(short), ssl_init.point_number*2, fin))
    {
        counter++;
        T0  = (long)_OsCounterGetMs();
        ret = IaaSsl_Run(handle,input,delay_sample);
        if(ret != 0)
        {
            printf("The Run fail\n");
            return -1;
        }
        // low resolution
        //      if (ssl_init.bf_mode == 1)
        //      {
        //          printf("delay_sample: %d\n",delay_sample[0]);
        //      }
        T1  = (long)_OsCounterGetMs();
        avg += (T1-T0);
        if(counter == ssl_config.direction_frame_num && ssl_init.bf_mode == 0)
        {
            counter2++;
            counter= 0;
            T2  = (long)_OsCounterGetMs();
            ret = IaaSsl_Get_Direction(handle, &direction);
            T3  = (long)_OsCounterGetMs();
            avg2 += (T3-T2);
            if(ret != 0 && ret!=ALGO_SSL_RET_RESULT_UNRELIABLE && ret!=ALGO_SSL_RET_BELOW_NOISE_GATE&&ret!=ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE)
            {
                printf("The Get_Direction fail\n");
                return -1;
            }
            // write txt file
            fprintf(fout,"%f\t%d",(float)(counter2*ssl_config.direction_frame_num*0.008),direction);
            if (ret==0)
            {
                fprintf(fout,"\t%s\n\r","current time is reliable!");
            }
            else if (ret==ALGO_SSL_RET_BELOW_NOISE_GATE)
            {
                fprintf(fout,"\t%s\n\r","current time volume is too small!");
            }
            else if(ret==ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE)
            {
                fprintf(fout,"\t%s\n\r","current time delay_sample is out of range!");
            }
            else
            {
                fprintf(fout,"\t%s\n\r","current time is not reliable!");
            }
            // reset voting
            ret = IaaSsl_Reset_Mapping(handle);
            if(ret != 0)
            {
                printf("The ResetVoting fail\n");
                return -1;
            }
        }
    }
    avg  = avg / (float)(ssl_config.direction_frame_num*counter2);
    avg2 = avg2 / (float)(counter2);
    printf("AVG for IaaSSL_RUN is %.3f ms\n",avg);
    printf("AVG for IaaSSL_GetDirection is %.3f ms\n",avg2);
    IaaSsl_Free(handle);
    fclose(fin);
    fclose(fout);
    free(WorkingBuffer2);
    printf("Done\n");
    return 0;
}

范例二: 多颗麦克风阵列(麦克风输入为4个单声道音讯)

#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>
#include <string.h>
#include <sys/time.h>
#include <sys/ioctl.h>
#include <stdlib.h>
#include "AudioSslProcess.h"

#define MIC_NUM (4)
#define USE_MALLOC   (1)
typedef unsigned char               uint8;
typedef unsigned short              uint16;
typedef unsigned long               uint32;

unsigned int _OsCounterGetMs(void)
{
    struct  timeval t1;
    gettimeofday(&t1,NULL);
    unsigned int T = ( (1000000 * t1.tv_sec)+ t1.tv_usec ) / 1000;
    return T;
}

int main(int argc, char *argv[])
{
    /*********Input file init*******/
    short input[512];
    short input_tmp1[128],input_tmp2[128],input_tmp3[128],input_tmp4[128];
    char infileName[MIC_NUM][512];
    char outfileName[512];
    FILE * fin0,* fin1,* fin2,* fin3;
    FILE * fout;
    int k;
    ALGO_SSL_RET ret;
    int counter2 = 0;
    unsigned int T0,T1,T2,T3;
    float avg = 0.0;
    float avg2 = 0.0;
    /********common setting  SSL ********/
    int point_number = 128;
    float microphone_distance = 4.0;
    int temperature = 20;
    int sample_rate = 16000;
    int delay_sample[MIC_NUM-1] = {0,0,0}; //channel-1
    int shape  = 0;
    int direction = 0;
    int frame_number = 32;
    /********SSL data init********/
    int counter = 0;
#if USE_MALLOC
    char *WorkingBuffer_SSL;
    WorkingBuffer_SSL = (char*)malloc(IaaSsl_GetBufferSize());
#endif
    AudioSslInit ssl_init;
    AudioSslConfig ssl_config;
    SSL_HANDLE ssl_handle;

    ssl_init.mic_distance = microphone_distance;
    ssl_init.point_number = point_number;
    ssl_init.sample_rate = sample_rate;
    ssl_init.bf_mode = 0;
    ssl_init.channel  = MIC_NUM;
    ssl_config.temperature = temperature;
    ssl_config.noise_gate_dbfs = -80;
    ssl_config.direction_frame_num = frame_number;

    /*******init algorithm *****/
    ssl_handle = IaaSsl_Init((char*)WorkingBuffer_SSL, &ssl_init);
    if (ssl_handle == NULL)
    {
        printf("Init fail\n\r");
        return -1;
    }
    else
    {
        printf("SSL init succeed\n\r");
    }

    ret = IaaSsl_Config(ssl_handle ,&(ssl_config));
    if (ret)
    {
        printf("Error occured in SSL Config\n\r");
        return -1;
    }

    ret = IaaSsl_Set_Shape(ssl_handle,shape);
    if (ret)
    {
        printf("Error occured in Array shape\n\r");
        return -1;
    }

    ret = IaaSsl_Cal_Params(ssl_handle);
    if (ret)
    {
        printf("Error occured in Array matrix calculation\n\r");
        return -1;
    }

    /********open input file and input file*****/

    sprintf(infileName[0],"%s","./../sample/data/Chn-01.wav");
    sprintf(infileName[1],"%s","./../sample/data/Chn-02.wav");
    sprintf(infileName[2],"%s","./../sample/data/Chn-03.wav");
    sprintf(infileName[3],"%s","./../sample/data/Chn-04.wav");
    sprintf(outfileName,"%s","./SSL_result.txt");
    fin0 = fopen(infileName[0], "rb");
    if(!fin0)
    {
        printf("the input file0 could not be open\n\r");
        return -1;
    }
    fin1 = fopen(infileName[1], "rb");
    if(!fin1)
    {
        printf("the input file 1 could not be open\n\r");
        return -1;
    }
    fin2 = fopen(infileName[2], "rb");
    if(!fin2)
    {
        printf("the input file 2 could not be open\n\r");
        return -1;
    }
    fin3 = fopen(infileName[3], "rb");
    if(!fin3)
    {
        printf("the input file 3 could not be open\n\r");
        return -1;
    }
    fout = fopen(outfileName, "w");
    if(!fout)
    {
        printf("the output file could not be open\n\r");
        return -1;
    }

    fread(input, sizeof(char), 44, fin0); // read header 44 bytes
    fread(input, sizeof(char), 44, fin1); // read header 44 bytes
    fread(input, sizeof(char), 44, fin2); // read header 44 bytes
    fread(input, sizeof(char), 44, fin3); // read header 44 bytes

    short * input_ptr;
    fprintf(fout,"%s\t%s\t%s\n\r","time","direction","case");
    while(fread(input_tmp1, sizeof(short), point_number, fin0))
    {
        fread(input_tmp2, sizeof(short), point_number, fin1);
        fread(input_tmp3, sizeof(short), point_number, fin2);
        fread(input_tmp4, sizeof(short), point_number, fin3);
        input_ptr = input;
        for(k=0;k<point_number;k++)
        {
            *input_ptr =  input_tmp1[k];
            input_ptr++;
            *input_ptr =  input_tmp2[k];
            input_ptr++;
            *input_ptr =  input_tmp3[k];
            input_ptr++;
            *input_ptr =  input_tmp4[k];
            input_ptr++;
        }
        counter++;
        T0  = (long)_OsCounterGetMs();
        ret = IaaSsl_Run(ssl_handle,input,delay_sample);
        if(ret != 0)
        {
            printf("The Run fail\n");
            return -1;
        }
        // low resolution
//      if (ssl_init.bf_mode == 1)
//      {
//          printf("delay_sample: %d,%d,%d\n",delay_sample[0],delay_sample[1],delay_sample[2]);
//      }
        T1  = (long)_OsCounterGetMs();
        avg += (T1-T0);

        if(counter == ssl_config.direction_frame_num && ssl_init.bf_mode == 0)
        {
            counter2++;
            counter= 0;
            T2  = (long)_OsCounterGetMs();
            ret = IaaSsl_Get_Direction(ssl_handle, &direction);
            T3  = (long)_OsCounterGetMs();
            avg2 += (T3-T2);
            if(ret != 0 && ret!=ALGO_SSL_RET_RESULT_UNRELIABLE && ret!=ALGO_SSL_RET_BELOW_NOISE_GATE&&ret!=ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE)
            {
                printf("The Get_Direction fail\n");
                return -1;
            }
            // write txt file
            fprintf(fout,"%f\t%d",(float)(counter2*ssl_config.direction_frame_num*0.008),direction);
            if (ret==0)
            {
                fprintf(fout,"\t%s\n\r","current time is reliable!");
            }
            else if (ret==ALGO_SSL_RET_BELOW_NOISE_GATE)
            {
                fprintf(fout,"\t%s\n\r","current time volume is too small!");
            }
            else if(ret==ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE)
            {
                fprintf(fout,"\t%s\n\r","current time delay_sample is out of range!");
            }
            else
            {
                fprintf(fout,"\t%s\n\r","current time is not reliable!");
            }
            // reset voting
            ret = IaaSsl_Reset_Mapping(ssl_handle);
            if(ret != 0)
            {
                printf("The ResetVoting fail\n");
                return -1;
            }
        }
    }
    avg  = avg / (float)(ssl_config.direction_frame_num*counter2);
    avg2 = avg2 / (float)(counter2);
    printf("AVG for IaaSSL_RUN is %.3f ms\n",avg);
    printf("AVG for IaaSSL_GetDirection is %.3f ms\n",avg2);
    IaaSsl_Free(ssl_handle);
    fclose(fin0);
    fclose(fin1);
    fclose(fin2);
    fclose(fin3);
    fclose(fout);
    free(WorkingBuffer_SSL);
    printf("Done\n");

    return 0;
}

3.9. IaaSsl_Get_Direction¶

功能

获取SSL算法的处理结果

语法

ALGO_SSL_RET IaaSsl_Get_Direction(SSL_HANDLE handle, int* direction);

形参

参数名称	描述	输入/输出
handle	SSL算法handle	输入
direction	若是均匀线性阵列，数值介于-90_{90之间，若是均匀圆形阵列，则数值介于-90}270之间，当回传数值为-10000，代表可能发生下面三种状况其中之一。第一种状况为音量低于noise_gate_dbfs；第二种情况为数据量不够，无法计算出可信的方向;第三种状况为估测状况超出范围	输出

返回值

返回值	结果
0	成功
0x10000107	成功。警告: 估测状况超出范围
0x10000113	成功。警告: 音量低于噪音阀值
0100000114	成功。警告: 数据量不足以计算出可信的方向
其他	失败，参照错误码

依赖
- 头文件: AudioSslProcess.h
- 库文件: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a
注意

当呼叫IaaSsl_Get_Direction后务必呼叫IaaSsl_Reset_Mapping。
举例

请参考IaaSsl_Run举例部分。

3.10. IaaSsl_Reset_Mapping¶

功能

当IaaSsl_Get_Direction完成后重新初始化定位缓冲区。

语法

ALGO_SSL_RET IaaSsl_Reset_Mapping(SSL_HANDLE handle);

形参

参数名称描述输入/输出

handle SSL算法handle 输入
返回值

返回值结果

0 成功

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

当呼叫IaaSsl_Get_Direction后务必呼叫IaaSsl_Reset_Mapping
举例

请参考IaaSsl_Run举例部分。

3.11. 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_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a
举例

请参考IaaSsl_Run举例部分。

3.12. IaaSsl_Free¶

功能

释放Ssl算法资源。

语法

ALGO_SSL_RET IaaSsl_Free(SSL_HANDLE handle);

形参

参数名称描述输入/输出

handle SSL算法handle 输入
返回值

返回值结果

0 成功

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

请参考IaaSsl_Run举例部分。

3.13. IaaSsl_SetMode¶

功能

选择SSL算法模式。

语法

ALGO_SSL_RET IaaSsl_SetMode(SSL_HANDLE handle, int mode,unsigned int angular_distance,unsigned int convidence);

形参

参数名称	描述	输入/输出
handle	SSL算法handle	输入
mode	使用的定位模式，范围: [0,1]，0: 传统模式, 1: AI模式	输入
angular_distance	AI模式下多声源定位相邻结果的最小角度差，范围: [1,180]	输入
convidence	AI模式下多声源定位的信心阀值, 范围: [1,90]	输入

返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioSslProcess.h
- 库文件: libSSL_4MIC_LINUX.a
注意
- 若为传统模式，仅会有一个有效定位输出，若为AI模式，最多到三个有效定位输出。
- AI模式仅支持LINUX静态库，间距5公分的四麦克风线性阵列。
- 参数 angular_distance，convidence仅会影响AI模式下的结果，建议值 angular_distance 为 8，convidence 为 60。
- 可调整SSL_Config 中的noise_gate_dbfs 作为音量的阀值以进行进一步判断。
- 若为AI 模式，取样频率必须为16000 赫兹并且SSL_Config的direction_frame_num必须为 32。

3.14. IaaSsl_SetCallbackFunction¶

功能

SSL 算法对Ikayaki芯片的授权管控

语法

ALGO_SSL_RET IaaSsl_SetCallbackFunction(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));

形参

参数名称	描述	输入/输出
log	打印debug 讯息的函式指针	输入
envSet	设置环境变量的函式指针(目前还没有实际作用)	输入
envGetString	获取环境变量中的授权信息的函式指针	输入
envsave	保存计算出来的授权码讯息至环境变量的函式指针(目前没有实际作用)	输入
readUuid	读取等待授权板子的Uuid 的函式指针	输入

返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioSslProcess.h
- 库文件: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a
注意
- 此为SSL对Ikayaki芯片的授权管控，其余芯片不受影响
- 若使用Ikayaki芯片，根据授权成功与否会有其对应的使用时间

3.15. IaaSsl_ApplyDigitalGain¶

功能

对输入数据做增益或衰减

语法

ALGO_SSL_RET IaaSsl_ApplyDigitalGain(SSL_HANDLE handle,short* microphone_input,int gain);

形参

参数名称描述输入/输出

handle SSL算法handle 输入

microphone_input 待进行声源定位的数据指针输入/输出

gain 增益/衰减值范围: [-120,120] 输入
返回值

返回值结果

0 成功

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

3.16. IaaSsl_GetAPIVersion¶

功能

返回当前SSL算法版号

语法

ALGO_SSL_RET IaaSsl_GetAPIVersion(unsigned short* major, unsigned short* minor);

形参

参数名称描述输入/输出

major 主版号输入/输出

minor 副版号输入/输出
返回值

返回值结果

0 成功

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

4. SSL数据类型¶

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

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

4.2. AudioSslInit¶

说明

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

定义

typedef struct

{

    unsigned int point_number;

    unsigned int sample_rate;

    float mic_distance;

    unsigned int bf_mode;

    int channel;

}AudioSslInit;

成员

成员名称	描述
point_number	SSL算法处理一次的采样点数
sample_rate	取样率，目前支持8k/16k/32k/48k
mic_distance	两个mic的距离，单位为cm
bf_mode	是否为beamforming模式若想使用定位角度，设定为0并由 IaaSsl_Get_Direction得到定位结果。若想使用估测的延迟的样本数，设定为1
channel	麦克风个数

注意事项
- 若需delay_sample 则建议将bf_mode开启。
- 若将bf_mode 设为 1，则无法呼叫 IaaSsl_Get_Direction 以及 IaaSsl_Reset_Mapping。
- 若阵列为均匀线性阵列，则mic_distance 需设定为相邻麦克风之间的距离，若为均匀圆形阵列，mic_distance 需设定为圆形的直径。
相关数据类型及接口

IaaSsl_Init

IaaSsl_Reset

4.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）注意：低于此值将会把该帧作为噪声部分处理，则不会进入方向的计算。范围:[0,-80] 步长为1
direction_frame_num	声源定位功能检测的帧数，步长为32。注意：进行声源定位检测的帧数越大较为稳定，声源定位处理的一帧数据为128个采样点。检测一次的时间 = s32DirectionFrameNum * 128 / 采样率。如：当前采样率为16K，s32DirectionFrameNum设置成32，则检测时间=32 * 128 / 16000 = 0.256(s)

注意事项
- AI 模式下，direction_frame_num 必须为32。
- 传统模式下，direction_frame_num尽量为16的倍数为佳。
相关数据类型及接口

IaaSsl_Config

IaaSsl_Get_Config

4.4. SSL_HANDLE¶

说明

定义SSL算法的句柄类型。
定义
```
typedef void* SSL_HANDLE;
```
相关数据类型及接口

IaaSsl_Init

IaaSsl_Config

IaaSsl_Get_Config

IaaSsl_Set_Shape

IaaSsl_Cal_Params

IaaSsl_Run

IaaSsl_Get_Direction

IaaSsl_Reset_Mapping

IaaSsl_Reset

IaaSsl_Free

IaaSsl_SetMode

IaaSsl_SetCallbackFunction

IaaSsl_ApplyDigitalGain

IaaSsl_GetAPIVersion

5. 错误码¶

SSL API 错误码如下表所示：

表5‑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正在运行
0x10000110	ALGO_SSL_RET_INVALID_CHANNEL	SSL 通道数无效
0x10000111	ALGO_SSL_RET_INVALID_GEOMETRY_TYPE	SSL 阵列形状无效
0x10000112	ALGO_SSL_RET_INVALID_ARRAY_TYPE	SSL 双麦克风阵列必为线性阵列
0x10000113	ALGO_SSL_RET_BELOW_NOISE_GATE	警告:音量小于噪音阀值
0x10000114	ALGO_SSL_RET_RESULT_UNRELIABLE	警告:数据量不足以计算出可信的方向
0x10000115	ALGO_SSL_RET_INVALID_MODE	SSL 设定模式及相关参数错误
0x10000116	ALGO_SSL_RET_INVALID_CNN	SSI AI模式无法执行
0x10000117	ALGO_SSL_RET_INVALID_SETCALLBACK	警告:SSL授权失败
0x10000118	ALGO_SSL_RET_FAILED	SSL 算法缺少对应输入
0x10000119	ALGO_SSL_RET_INVALID_GAIN	SSL 设定增益超出范围

参数名称	描述	输入/输出
working_buffer	SSL算法所使用的内存地址，用户申请内存大小后所得地址	输入
ssl_init	SSL算法的初始化结构体指针	输入

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

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