SGS SSL 算法使用参考¶

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.5	Add function IaaSsl_SetArbitraryShape and IPU implementation	04/22/2024
1.6	Add function IaaSsl_GetJsonFileSize, IaaSsl_InitReadFromJson, IaaSsl_ConfigReadFromJson, IaaSsl_OptionReadFromJson, IaaSsl_SetHandleId	10/30/2024
1.7	Update file description. Deprecate API: IaaSsl_SetCallbackFunction.	04/19/2025
1.71	Fix spelling error.	05/01/2025
1.72	Add and update description of Chapter 1	11/25/2025

1. 概述¶

1.1. 算法说明¶

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

关键词说明

噪音音量阀值

侦测声音的最低音量阶级，若音量小于此阀值则作为噪声不会进行侦测。
侦测帧数

获得一次声源定位结果所需的帧数，越大定位结果越稳定，但反应时间会因此变长。
数组形状及坐标系定义

SSL 算法库目前支持一维或是二维数组，请参考2. 数组系统及坐标系。

注意

SSL目前有2或4麦克风数组算法库。使用者需要确认是否正确地使用对应的SSL算法库。如果需要不同麦克风数量的SSL算法库，请向算法同仁提出需求。为方便调试和确认算法效果，需要用户自行实现替换算法参数和抓取音频处理结果的逻辑。

1.2. 基本结构¶

SSL需要输入 Buffer及定位结果 Buffer来进行处理。当SSL算法配置好内存，并完成参数初始化与设定后，将定位结果输出到定位结果 Buffer上。

1.3. 功能介绍¶

定位具有方向性声音来源的方向。

1.4. 应用场景¶

SSL 常用于会议系统、安防监控与导航系统等场景，计算出声音来源的方向并提供给后续系统做应用，例如使用BF强化语者声音或是导航系统做侦测及追踪。

1.5. 芯片差异说明¶

在不同系列芯片，目前MIX算法效果上没有差异。

1.6. 实例介绍¶

使用SSL API获取SSL算法运行需要的内存大小、初始化SSL算法handle、配置参数至SSL算法handle、运行SSL算法与释放SSL算法资源。

双声道或多声道输入程序范例

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

#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;
}

2. 数组系统及坐标系¶

2.1. 多麦克风数组¶

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

2.1.1. 均匀线性数组及坐标系¶

均匀线性数组为相邻麦克风之间距皆相同的直线数组，由于其对称性，定位角度仅考虑上半平面(-90度至90度)。下图为均匀线性数组于空间坐标系的示意图。声音方向的角度(microphone_doa)定义为与数组中心及x轴的夹角。逆时钟方向为正。建议相邻麦克风之间距至少大于 5cm 或 6cm。

2.1.2. 均匀圆型数组及坐标系¶

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

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算法版号
IaaSsl_SetArbitraryShape	SSL指派任意麦克风数组形状
IaaSsl_GetJsonFileSize	SSL获取解析Json文件内容所需要的内存大小
IaaSsl_InitReadFromJson	配置Json参数到SSL算法的初始化结构体指针
IaaSsl_ConfigReadFromJson	配置Json参数到SSL算法的配置结构体指针
IaaSsl_OptionReadFromJson	配置Json参数到SSL算法的其他选项结构体指针
IaaSsl_ReadJson	读取Json其他选项参数并额外使用这些参数呼叫SSL常用API
IaaSsl_SetHandleId	配置SSL算法id

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举例部分。
注意
- 神经网络模型(AI) 在CPU 版本仅支持 LINUX 静态库。
- 神经网络模型(AI) 在IPU 版本支持 LINUX 静态/动态库。

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. 数组系统及坐标系，客户有特殊数组需求，可使用IaaSsl_SetArbitraryShape。
- 麦克风个数为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(即多少个采样点进行一次SSL处理)相对应。→范例一
- 对于多颗麦克风数组(麦克风数多于两颗，双声道音频无法负荷)的情况，各个麦克风音频须为单声道，microphone_input指向的数据仍应已采样点为最小单位，并按照麦克风于数组的相对位置，由左至右的格式摆放，例如4颗线性麦克风数组，摆放的方式为 [左一→左二→右二→右一]，数据长度必须和IaaSsl_Init中设定的point_number(即多少个采样点进行一次SSL处理)相对应。→范例二
- 以2. 数组系统及坐标系的麦克风数组为例，microphone_input摆放的格式为[MIC1→MIC2→MIC3→MIC4]。
举例

请参考1.6. 实例介绍

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；第二种情况为数据量不够，无法计算出可信的方向;第三种状况为估测状况之delay_sample超出范围	输出

返回值

返回值	结果
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 confidence);

形参

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

返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioSslProcess.h
- 库文件: libSSL_4MIC_LINUX.a
注意
- 若为传统模式，仅会有一个有效定位输出，若为AI模式，最多到三个有效定位输出。
- AI模式仅支持LINUX库(CPU提供静态库，IPU提供静态及动态库)，间距5公分的四麦克风线性数组。
- 参数 angular_distance，confidence仅会影响AI模式下的结果，建议值 angular_distance 为 8，confidence 为 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

3.17. IaaSsl_SetArbitraryShape¶

功能

SSL指派任意麦克风数组形状。

语法

ALGO_SSL_RET IaaSsl_SetArbitraryShape(SSL_HANDLE handle, float *array_pos);

形参

参数名称描述输入/输出

handle SSL算法handle 输入

array_pos 输入的数组位置指针，单位:公分输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioSslProcess.h
- 库文件: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a
注意
- 此功能帮助用户设定任意的数组形状。如果此功能于IaaSsl_Set_Shape后呼叫，则会覆写原本IaaSsl_Set_Shape定义的矩阵形状，反之亦然。
- 输入数组为卡式坐标系下的[X,Y]坐标，因此必须包含(麦克风个数*2) 个元素，数组中心定义为输入的麦克风数组分别沿着X及Y轴的平均值。
- 各麦克风位置定义为数组中心指向各麦克风位置的向量，声音方向的角度(microphone_doa)仍定义为与数组中心及x轴的夹角。逆时钟方向为正。
- 以四颗麦克风为例，如果给定 array_pos:{-4,-2,-1,-3,2,3,4,2}，数组中心[X=0.25,Y=0]， Mic1[X=-4.25,Y=-2]，Mic2 [X=-1.25,Y=-3]， Mic3 [X=1.75,Y=3]， Mic4 [X=3.75,Y=2]。

3.18. IaaSsl_GetJsonFileSize¶

功能

SSL获取解析Json文件内容所需要的内存大小。

语法

unsigned int IaaSsl_GetJsonFileSize(char* jsonfile);

形参

参数名称描述输入/输出

jsonfile Json檔名输入
返回值

返回值为解析Json文件内容所需要的内存大小。
依赖
- 头文件: AudioSslProcess.h
- 库文件: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/ libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

3.19. IaaSsl_InitReadFromJson¶

功能

配置Json参数到SSL算法的初始化结构体指针。

语法

ALGO_SSL_RET IaaSsl_InitReadFromJson(AudioSslInit* ssl_init, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

形参

参数名称	描述	输入/输出
ssl_init	SSL算法的初始化结构体指针	输入/输出
jsonBuffer	解析Json文件内容所使用的内存地址	输入
jsonfile	Json檔名	输入
buffSize	解析Json文件内容所需要的内存大小	输入

返回值

返回值结果

0 成功

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

此API读取jsonfile内初始化设定至AudioSslInit结构体，提供给IaaSsl_Init使用。

3.20. IaaSsl_ConfigReadFromJson¶

功能

配置Json参数到SSL算法的配置结构体指针。

语法

ALGO_SSL_RET IaaSsl_ConfigReadFromJson(AudioSslConfig* ssl_config, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

形参

参数名称	描述	输入/输出
ssl_config	SSL算法的配置结构体指针	输入/输出
jsonBuffer	解析Json文件内容所使用的内存地址	输入
jsonfile	Json檔名	输入
buffSize	解析Json文件内容所需要的内存大小	输入

返回值

返回值结果

0 成功

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

此API读取jsonfile内初始化设定至AudioSslConfig结构体，提供给IaaSsl_Config使用。

3.21. IaaSsl_OptionReadFromJson¶

功能

配置Json参数到SSL算法的其他选项结构体指针。

语法

ALGO_SSL_RET IaaSsl_OptionReadFromJson(AudioSslOption* ssl_option, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

形参

参数名称	描述	输入/输出
ssl_option	SSL算法的其他选项结构体指针	输入/输出
jsonBuffer	解析Json文件内容所使用的内存地址	输入
jsonfile	Json檔名	输入
buffSize	解析Json文件内容所需要的内存大小	输入

返回值

返回值结果

0 成功

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

此算法读取jsonfile内其他选项设定参数至AudioSslOption结构体，提供给 IaaSsl_Set_Shape,IaaSsl_SetMode,IaaSsl_ApplyDigitalGain,IaaSsl_SetArbitraryShape 等API函式使用

3.22. IaaSsl_ReadJson¶

功能

读取Json其他选项参数并额外使用这些参数呼叫SSL常用API。

语法

ALGO_SSL_RET IaaSsl_ReadJson(SSL_HANDLE handle, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

形参

参数名称	描述	输入/输出
handle	SSL算法handle	输入
jsonBuffer	解析Json文件内容所使用的内存地址	输入
jsonfile	Json檔名	输入
buffSize	解析Json文件内容所需要的内存大小	输入

返回值

返回值结果

0 成功

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

此算法读取jsonfile内AudioSslOption参数，并使用此参数额外呼叫IaaSsl_Set_Shape, IaaSsl_Cal_Params,IaaSsl_SetMode等常用API。

3.23. IaaSsl_SetHandleId¶

功能

配置SSL算法id。

语法

ALGO_SSL_RET IaaSsl_SetHandleId(SSL_HANDLE handle, int id);

形参

参数名称描述输入/输出

handle SSL算法handle 输入

id SSL算法handle id
数值范围:[0,100] 输入
返回值

返回值结果

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算法句柄类型
AudioSslOption	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

IaaSsl_InitReadFromJson

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

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

IaaSsl_Config

IaaSsl_Get_Config

IaaSsl_ConfigReadFromJson

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

IaaSsl_SetArbitraryShape

IaaSsl_ReadJson

IaaSsl_SetHandleId

4.5. AudioSslOption¶

说明

SSL算法其他选项参数结构体类型。

定义

typedef struct

{

    int shape;

    int mode;

    unsigned int angular_distance;

    unsigned int confidence;

    int gain;

    float array_pos[8];

}AudioSslOption;

成员

成员名称	描述
shape	参考IaaSsl_Set_Shape
mode	参考IaaSsl_SetMode
angular_distance	参考IaaSsl_SetMode
confidence	参考IaaSsl_SetMode
gain	参考IaaSsl_ApplyDigitalGain
array_pos	参考IaaSsl_SetArbitraryShape

注意事项

需将其他选项参数搭配对应的API做使用，若无呼叫对应的API，参数设定就不会应用在算法内。
相关数据类型及接口

IaaSsl_OptionReadFromJson

5. Error Code¶

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	SSL AI模式无法执行
0x10000117	ALGO_SSL_RET_INVALID_SETCALLBACK	警告:SSL授权失败
0x10000118	ALGO_SSL_RET_FAILED	SSL算法缺少对应输入
0x10000119	ALGO_SSL_RET_INVALID_GAIN	SSL设定增益超出范围
0x10000320	ALGO_SSL_RET_INVALID_JSONFILE	SSL读取Json档失败

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

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

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