SSL Algorithm User Guide

---

1. Overview

1.1. Algorithm Description

SSL (short for Sound Source Localization) is used to locate the direction of the sound.

1.2. Keyword

When the distance between the two microphones is 5cm, the following figure describes the definition of the sound direction:

​

When the number of microphone is more than two, there are two possible configurations for the corresponding microphone array system: Uniform Linear Array (ULA) or Uniform Circular Array (UCA).

1.3. Note

1.3.1. Implementation

In order to facilitate debugging and confirm the effect of the algorithm, the user application needs to implement replacement algorithm parameter and grab audio data.

1.3.2. Correspondence

Different channel numbers will correspond to different reference libraries. The user needs to confirm whether to use the correct number of channels and the corresponding reference library.

2. Coordinate system of Microphone Array

2.1. Multichannel Microphone array

There are two main types of multichannel array system used in practice, one is the uniform linear array, and the other is uniform circular array.

2.1.1. Uniform Linear Array

Uniform linear array is a straight line array that is spaced evenly. Because of its DOA symmetry, we only consider the sound direction locates at the upper plane (from -90 degree to 90 degree). Figure 2-1 illustrates the uniform linear array and its coordinate system. The sound direction is defined as the angle between the array center and the x-axis where counterclockwise is positive. We recommend the distance of adjacent microphones should be bigger than 5cm or 6cm.

Figure 2-1: Uniform linear array and its coordinate system.

2.1.2. Uniform Circular Array

Uniform circular array is a circular array that the angle between adjacent microphones and array center are the same. Because of its DOA asymmetry, we consider the sound direction locates at the whole plane (from -90 degree to 270 degree). Figure 2-2 illustrates the uniform circular array and its coordinate system. The sound direction is defined as the angle between the array center and the x-axis where counterclockwise is positive. The distance is the diameter of the circle. We recommend the distance should be bigger than 6cm.

​

Figure 2-2: Uniform circular array and its coordinate system.

3. API Reference

3.1. API List

API name	Features
IaaSsl_GetBufferSize	Get the memory size required for SSL algorithm running
IaaSsl_Init	Initialize SSL algorithm
IaaSsl_Config	Configure SSL algorithm
IaaSsl_Get_Config	Get the current configuration parameter information of the SSL algorithm
IaaSsl_Set_Shape	Define the type of array system belongs to either ULA or UCA.
IaaSsl_Cal_Params	Recalculate some parameters required for SSL algorithm according to the type of array system.
IaaSsl_Run	SSL algorithm processing
IaaSsl_Get_Direction	Get the result direction of SSL algorithm processing
IaaSsl_Reset_Mapping	Reinitialize the buffer after IaaSsl_Get_Direction.
IaaSsl_Reset	Reinitialize SSL algorithm
IaaSsl_Free	Release SSL algorithm resources
IaaSsl_SetMode	Set the SSL algorithm mode
IaaSsl_SetCallbackFunction	Ikayaki chip authorization and licence checking for SSL algorithm
IaaSsl_ApplyDigitalGain	SSL apply digital gain
IaaSsl_GetAPIVersion	Return current SSL API version

3.2. IaaSsl_GetBufferSize

• Features

  Get the memory size required for SSL algorithm running.

• Syntax

  unsigned int IaaSsl_GetBufferSize(void);
  

• Return value

  Return value is the memory size required for SSL algorithm running. The memory size is dependent on the microphone number.

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Note

  The interface only returns the required memory size, and the application and release of memory need to be processed by the application.

• Example

  Please refer to IaaSsl_Run example.

3.3. IaaSsl_Init

• Features

  Initialize SSL algorithm.

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  working_buffer	Memory address used by SSL algorithm.The memory address will be obtained after user applies for the memory size.	Input
  ssl_init	SSL algorithm initialization structure pointer	Input

• Return value

  Return value	Result
  Not NULL	Successful
  NULL	Failed

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

3.4. IaaSsl_Config

• Features

  Configure SSL algorithm.

• Syntax

  ALGO_SSL_RET IaaSsl_Config(SSL_HANDLE handle, AudioSslConfig* ssl_config);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input
  ssl_config	SSL algorithm configuration parameter structure pointer	Input

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

3.5. IaaSsl_Get_Config

• Features

  Get the current configuration parameter information of the SSL algorithm.

• Syntax

  ALGO_SSL_RET IaaSsl_Get_Config(SSL_HANDLE handle, AudioSslConfig *ssl_config);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input
  ssl_config	SSL algorithm configuration parameter structure pointer	Output

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

3.6. IaaSsl_Set_Shape

• Features

  Define the type of array system belongs to either ULA or UCA.

• Syntax

  ALGO_SSL_RET IaaSsl_Set_Shape(SSL_HANDLE handle,int shape);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input
  shape	The integer to decide array shape of Microphone array 0: Uniform Linear Array. 1: Uniform Circular Array.	Input

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Note

  • Our lib only supports uniform linear array and uniform circular array (Figure 2-1 and Figure 2-2). User has to inform the modification if he/she requires special array geometry.

  • Only uniform linear array exists when there are only two microphones.

  • The settings of array position will impact largely on SSL performance. Therefore, the settings of array position must be matched to the microphone array being used.

• Example

  Please refer to IaaSsl_Run example.

3.7. IaaSsl_Cal_Params

• Features

  Recalculate some parameters required for SSL algorithm according to the type of array system.

• Syntax

  ALGO_SSL_RET IaaSsl_Cal_Params(SSL_HANDLE handle);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

3.8. IaaSsl_Run

• Features

  SSL algorithm processing.

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input
  microphone_input	The microphone raw data	Input
  delay_sample	The number of delayed samples for each microphone pair. It’s recommended to be used when bf_mode is enable.	Output

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Note

  • For dual microphone array (the microphone input is binaural data), the data pointed to microphone_input should use the sampling point as the smallest unit and be placed in the format of L,R,L,R … .The length must correspond to the point_number (the number of sampling points once Ssl process) set in IaaSsl_Init. →Example I

  • For multichannel microphone array (microphone number is bigger than two where binaural data is not enough for processing), the input data of each microphone must be mono-channel. The data pointed to microphone_input should use the sampling point as the smallest unit and be placed in the format of [Left → Right], according to the relative position. The length must correspond to the point_number (the number of sampling points once Ssl process) set in IaaSsl_Init. →Example II

  • Take microphone array in both Figure 2-1 and Figure 2-2 as example, the microphone_input should be placed in the format of [MIC1→MIC2→MIC3→MIC4].

• Example

  • Example I: Dual Microphone array(The microphone input is a binaural audio)

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

  • Example II: Multichannel Microphone array (Microphone input are 4x mono-channel audio)

    #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

• Features

  Get the result of SSL algorithm processing.

• Syntax

  ALGO_SSL_RET IaaSsl_Get_Direction(SSL_HANDLE handle, int* direction);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input
  direction	For ULA, the value is between -90~90. For UCA, the value is between -90~270. When the value is -10000, there are three possibilities. The first is that the volume is lower than noise_gate_dbfs,and the second is that the amount of data is not enough to estimate a reliable direction, and the third is that the estimation is out of range.	Output

• Return value

  Return value	Result
  0	Successful
  0x10000107	Successful.Warning: The estimation is out of range.
  0x10000113	Successful.Warning: The volume is lower than noise_gate_dbfs.
  0x10000114	Successful.Warning: The amount of data is not enough to estimate a reliable direction.
  others	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Note

  IaaSsl_Reset_Mapping must be called after using IaaSsl_Get_Direction.

• Example

  Please refer to IaaSsl_Run example.

3.10. IaaSsl_Reset_Mapping

• Features

  Reinitialize the buffer after IaaSsl_Get_Direction.

• Syntax

  ALGO_SSL_RET IaaSsl_Reset_Mapping(SSL_HANDLE handle);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Note

  IaaSsl_Reset_Mapping must be called after using IaaSsl_Get_Direction.

• Example

  Please refer to IaaSsl_Run example.

3.11. IaaSsl_Reset

• Features

  Reinitialize SSL algorithm.

• Syntax

  SSL_HANDLE IaaSsl_Reset(SSL_HANDLE working_buffer, AudioSslInit* ssl_init);
  

• Parameters

  Parameter Name	Description	Input/Output
  working_buffer	Memory address for SSL algorithm running	Input
  ssl_init	SSL algorithm initialization structure pointer	Input

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

3.12. IaaSsl_Free

• Features

  Release SSL algorithm resources.

• Syntax

  ALGO_SSL_RET IaaSsl_Free(SSL_HANDLE handle);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

3.13. IaaSsl_SetMode

• Features

  Set the SSL algorithm mode.

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input
  mode	SSL Mode. Range: [0,1]. 0: Conventional mode, 1: AI Mode	Input
  angular_distance	Minimum angular distance between adjacent Localization results for AI Mode. Range:[1,180]	Input
  convidence	Convidence threshold(level) for AI Mode. Range: [1,90]	Input

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_4MIC_LINUX.a

• Note

  • If using Mode 0, SSL algorithm will output one valid result only. If using AI mode, SSL algorithm will output up three valid results.

  • AI mode can only be used with libSSL_4MIC_LINUX.a with a 4MIC ULA, spacing = 5cm.

  • angular_distance and convidence will only affect the results from AI Mode. Recommend to set angular_distance as 8 and convidence as 60, respectively.

  • Adjust noise_gate_dbfs from SSL_Config as the threshold of volume for further judgement.

  • If using AI mode, the sampling rate must be set as 16KHz and the direction_frame_number from SSL config must be set as 32.

3.14. IaaSsl_SetCallbackFunction

• Features

  Ikayaki chip authorization and licence checking for SSL algorithm

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  log	Function pointer for debugging message	Input
  envSet	Function pointer for setting environment variables (No practical usage currently)	Input
  envGetString	Function pointer for obtaining the license message from environment variables	Input
  envsave	Function pointer for saving the calculated authorized message to environment variables (No practical usage currently)	Input
  readUuid	Function pointer for reading the Uuid from chip waited for authorization	Input

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

• Note

  • The API for authorization is only for Ikayaki chip.

  • If using Ikayaki chip, there will be a corresponding usage time with SSL algorithm depending on the results of authorization.

3.15. IaaSsl_ApplyDigitalGain

• Features

  SSL apply digital gain

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input
  microphone_input	The microphone raw data	Input/Output
  gain	Gain value. Range: [-120,120]	Input

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

3.16. IaaSsl_GetAPIVersion

• Features

  Return current SSL API version

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  major	Main API version	Input/Output
  minor	Secondary API version	Input/Output

• Return value

  Return value	Result
  0	Successful
  Non-zero	Failed, refer to error code

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_2MIC_LINUX.so/ libSSL_2MIC_LINUX.a/libSSL_4MIC_LINUX.so/libSSL_4MIC_LINUX.a

4. SSL Data Type

4.1. SSL data type list

Data type	Definition
AudioSslInit	SSL algorithm initialization parameter structure type
AudioSslConfig	SSl algorithm configuration parameter structure type
SSL_HANDLE	SSl algorithm handle type

4.2. AudioSslInit

• Description

  Define SSL algorithm initialization parameter structure type.

• Definition

  typedef struct
  
  {
  
      unsigned int point_number;
  
      unsigned int sample_rate;
  
      float mic_distance;
  
      unsigned int bf_mode;
  
      int channel;
  
  }AudioSslInit;
  

• Member

  Member name	Description
  point_number	The sampling points that SSL algorithm processed once
  sample_rate	Sampling rate, currently supports 8k/16k/32k/48k
  mic_distance	The distance between two mics, unit: cm
  bf_mode	Whether it is beamforming mode. If want to use direction from SSL, please set as 0 and take the direction from IaaSsl_Get_Direction. If want to use the delay sample from SSL, please set as 1.
  channel	The number of microphones

• Note

  • If delay_sample is required, it is recommended to enable bf_mode.

  • If bf_mode is set as 1, IaaSsl_Get_Direction and IaaSsl_ResetVoting can’t be used.

  • If microphone geometry belongs to uniform linear array, the mic_distance needs to be set as the distance between adjacent microphones. If microphone geometry belongs to uniform circular array, the mic distance needs to be set as the diameter of the circle.

• Related data types and interfaces

  IaaSsl_Init

  IaaSsl_Reset

4.3. AudioSslConfig

• Description

  Define SSL algorithm configuration parameter structure type.

• Definition

  typedef struct
  
  {
  
      unsigned int temperature;
  
      int noise_gate_dbfs;
  
      int direction_frame_num;
  
  }AudioSslConfig;
  

• Member

  Member name	Description
  temperature	Ambient temperature (Celsius) Celsius = (5 / 9) * (Fahrenheit - 32) Step size is 1
  noise_gate_dbfs	Noise gain threshold (dBfs) Note: Below this value, the frame will be treated as noise and will not enter the calculation of the direction. Range:[-80,0]. Step size is 1
  direction_frame_num	The number of frames detected by the SSL function. Step size is 16. Note: The results for SSL will be more stable if using larger frames. One frame of data processed by SSL is 128 sampling points. Time of detection once = s32DirectionFrameNum * 128 / sampling rate. For example: ：The current sampling rate is 16K, setting s32DirectionFrameNum to 32, detection time =32 * 128 / 16000=0.256(s)

• Note

  • direction_frame_num must be set as 32 if using AI mode.

  • direction_frame_num is better to be set as multiple of 16 if using conventional mode.

• Related data types and interfaces

  IaaSsl_Config

  IaaSsl_Get_Config

4.4. SSL_HANDLE

• Description

  Define SSL algorithm handle type.

• Definition

  typedef void* SSL_HANDLE;
  

• Related data types and interfaces

  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. Error Code

SSL API error codes are shown as follow:

Table 5‑1: SSL API error code

Error code	Definition	Description
0x00000000	ALGO_SSL_RET_SUCCESS	SSL runs successfully
0x10000101	ALGO_SSL_RET_INIT_ERROR	SSL initialization error
0x10000102	ALGO_SSL_RET_INVALID_CONFIG	SSL Config is invalid
0x10000103	ALGO_SSL_RET_INVALID_HANDLE	SSL Handle is invalid
0x10000104	ALGO_SSL_RET_INVALID_SAMPLERATE	SSL sample rate is invalid
0x10000105	ALGO_SSL_RET_INVALID_POINTNUMBER	SSL sampling point is invalid
0x10000106	ALGO_SSL_RET_INVALID_BFMODE	bf_mode setting of SSL init is invalid
0x10000107	ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE	Warning:The delayed sample is too large, please check the set distance and sampling rate
0x10000108	ALGO_SSL_RET_INVALID_CALLING	SSL API call sequence error
0x10000109	ALGO_SSL_RET_API_CONFLICT	Other APIs are running
0x10000110	ALGO_SSL_RET_INVALID_CHANNEL	SSL channel number is invalid
0x10000111	ALGO_SSL_RET_INVALID_GEOMETRY_TYPE	SSL array shape is invalid.
0x10000112	ALGO_SSL_RET_INVALID_ARRAY_TYPE	The shape of dual microphone must be 0
0x10000113	ALGO_SSL_RET_BELOW_NOISE_GATE	Warning: The volume is lower than noise_gate_dbfs
0x10000114	ALGO_SSL_RET_RESULT_UNRELIABLE	Warning: The amount of data is not enough to estimate a reliable direction.
0x10000115	ALGO_SSL_RET_INVALID_MODE	SSL Setting mode and related parameters are wrong
0x10000116	ALGO_SSL_RET_INVALID_CNN	SSI AI mode cannot be executed
0x10000117	ALGO_SSL_RET_INVALID_SETCALLBACK	Warning : SSL authorization and license checking fail
0x10000118	ALGO_SSL_RET_FAILED	SSL lacks corresponding inputs
0x10000119	ALGO_SSL_RET_INVALID_GAIN	SSL digital gain value is out of range