SGS SSL ALGORITHM USER GUIDE

---

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. Overview

1.1. Algorithm Description

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

Keyword

• noise_gate_dbfs

  The lowest volume level to detect sound. If the recording volume is smaller than the threshold, the source won't be detected by the SSL algorithm.

• direction_frame_num

  Number of required frames to obtain localization results. When the number becomes bigger, the localization result will be more stable while the reaction time will be longer.

• Array shape and coordinate system definition.

  SSL Algorithm currently provides 1-dimensional or 2-dimensional array. Please refer to 2. Coordinate system_of Microphone Array.

Note

We currently provide 2 or 4 microphone array SSL libraries. The user needs to confirm whether the corresponding SSL library is used correctly. If you need SSL library with different channel numbers, please ask algorithm owners. In order to facilitate tuning and confirm the effect of the algorithm, users are required to implement their own logic for replacing algorithm parameters and capturing audio processing results.

1.2. Basic Structure

An input signal buffer and a localization result buffer are required for SSL algorithm to process. After the SSL algorithm allocates memory and completes parameter initialization and configuration, the input data buffer is processed by th SSL algorithm, and then the localization results are written into the localization result buffer.

1.3. Function Introduction

The SSL algorithm locates the direction of a directional sound source.

1.4. Application Scenarios

The SSL algorithm is commonly used in scenarios such as conferencing systems, security monitoring and navigation systems. The algorithm produce the results for further usage. For example, use BF to enhance the direction of a speaker's voice, or to provide a target position for navigation systems to detect or track.

1.5. Chip Difference

Across different chip series, the SSL algorithm demonstrates consistent performance with no observable differences.

1.6. Examples Introduction

Use the SSL API to obtain the memory size required by the SSL algorithm, initialize the SSL algorithm handle, configure parameters to the SSL handle, execute the SSL algorithm, and release the SSL algorithm resources.

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

---

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 line array that is spaced evenly. Because of its symmetry, we only consider the sound direction locates at the upper plane (from -90 degree to 90 degree). Below figure 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.

2.1.2. Uniform Circular Array

Uniform circular array is a circular array that the angle between adjacent microphones and array center are spaced evenly. Because of its asymmetry, we consider the sound direction locates at the whole plane (from -90 degree to 270 degree). Below figure 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 microphone distance is the diameter of the circle. We recommend the distance should be bigger than 6cm.

---

3. API Reference

3.1. API List

API name	Features
IaaSsl_GetBufferSize	Get the memory size required for SSL algorithm.
IaaSsl_Init	Initialize SSL algorithm.
IaaSsl_Config	Configure SSL algorithm.
IaaSsl_Get_Config	Get the current configuration parameter of the SSL algorithm.
IaaSsl_Set_Shape	Define the type of array system belongs to either ULA or UCA.
IaaSsl_Cal_Params	Calculate intrinsic parameters required for SSL algorithm according to the array geometry.
IaaSsl_Run	SSL algorithm processing.
IaaSsl_Get_Direction	Get the result direction of SSL algorithm.
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 (Deprecated, no longer restricted).
IaaSsl_ApplyDigitalGain	SSL apply digital gain.
IaaSsl_GetAPIVersion	Return current SSL API version .
IaaSsl_SetArbitraryShape	Set the arbitrary array shape for microphone array.
IaaSsl_GetJsonFileSize	Get the memory size to parse the content of the Json file required by SSL algorithm.
IaaSsl_InitReadFromJson	Configure Json parameters to the init structure of the SSL algorithm.
IaaSsl_ConfigReadFromJson	Configure Json parameters to the config structure of the SSL algorithm.
IaaSsl_OptionReadFromJson	Configure Json parameters to the option structure of the SSL algorithm.
IaaSsl_ReadJson	Read option parameters from Json file and call SSL common API with these parameters additionally.
IaaSsl_SetHandleId	Set SSL handle Id.

3.2. IaaSsl_GetBufferSize

• Features

  Get the memory size required for SSL algorithm.

• 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, the actions of allocating and releasing 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.

• Note

  • Currently, the AI model for CPU version only supports LINUX static library.

  • Currently, the AI model for IPU version supports LINUX static and dynamic libraries.

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

  • The SSL lib only supports uniform linear array and uniform circular array. Please refer to 2. Coordinate system_of Microphone Array. IaaSsl_SetArbitraryShape is applicable to special array geometry..

  • Two (dual) microphone array is always linear array.

  • 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 1.6. Examples Introduction.

3.7. IaaSsl_Cal_Params

• Features

  Calculate intrinsic parameters required for SSL algorithm according to the array geometry.

• 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 2. Coordinate system_of Microphone Array as example, the microphone_input should be placed in the format of [MIC1→MIC2→MIC3→MIC4].

• Example

  Please refer to 1.6. Examples Introduction.

3.9. IaaSsl_Get_Direction

• Features

  Get the result direction of SSL algorithm.

• 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 delay sample 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 confidence);
  

• 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
  confidence	confidence 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 confidence will only affect the results from AI Mode. Recommend to set angular_distance as 8 and confidence 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_num from SSL config must be set as 32.

3.14. IaaSsl_SetCallbackFunction

• Features

  Ikayaki chip authorization and licence checking for SSL algorithm (Deprecated, no longer restricted).

• 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

3.17. IaaSsl_SetArbitraryShape

• Features

  Set the arbitrary array shape for microphone array.

• Syntax

  ALGO_SSL_RET IaaSsl_SetArbitraryShape(SSL_HANDLE handle, float *array_pos);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input
  array_pos	Pointer of input array position, unit: centimetre	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

  • If this function is called after IaaSsl_Set_Shape, the array shape originally defined by IaaSsl_Set_Shape will be overwritten, and vice versa.

  • The input array is [X, Y] coordinates under the card coordinate system, so it must contain (number of microphones * 2) elements. The array center is defined as the average value of the input microphone array along the X and Y axes.

  • The position of each microphone is defined as the vector pointing from the center of the array to the position of each microphone. The angle of the sound direction (microphone_doa) is still defined as the angle with the center of the array and the x-axis. The counterclockwise direction is positive.

  • Taking four microphones as an example, if array_pos:{-4,-2,-1,-3,2,3,4,2} is given, the array center [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

• Features

  Get the memory size to parse the content of the Json file required by SSL algorithm.

• Syntax

  unsigned int IaaSsl_GetJsonFileSize(char* jsonfile);
  

• Parameters

  Parameter Name	Description	Input/Output
  jsonfile	Json file name	Input

• Return value

  Return value is the memory size required for decoding json file.

• Dependency

  • Header: AudioSslProcess.h

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

3.19. IaaSsl_InitReadFromJson

• Features

  Configure Json parameters to the init structure of the SSL algorithm

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  ssl_init	SSL algorithm initialization structure handle	Input/Output
  jsonBuffer	The memory address used to parse the Json file content	Input
  jsonfile	Json file name	Input
  buffSize	The memory size required to parse the Json file content	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 parses the initialization parameters into AudioSslInit structure from jsonfile, and is going to be used by IaaSsl_Init.

3.20. IaaSsl_ConfigReadFromJson

• Features

  Configure Json parameters to the config structure of the SSL algorithm.

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  ssl_config	Configure the structure handle of the SSL algorithm	Input/Output
  jsonBuffer	The memory address used to parse the Json file content	Input
  jsonfile	Json file name	Input
  buffSize	The memory size required to parse the Json file content	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 parses the config parameters into AudioSslConfig structure from jsonfile, and is going to be used by IaaSsl_Config.

3.21. IaaSsl_OptionReadFromJson

• Features

  Configure Json parameters to the option structure of the SSL algorithm

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  ssl_option	Configure the option handle of the SSL algorithm	Input/Output
  jsonBuffer	The memory address used to parse the Json file content	Input
  jsonfile	Json file name	Input
  buffSize	The memory size required to parse the Json file content	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 parses the option parameters into AudioSslOption structure from jsonfile, and is going to be used by IaaSsl_Set_Shape,IaaSsl_SetMode,IaaSsl_ApplyDigitalGain,IaaSsl_SetArbitraryShape.

3.22. IaaSsl_ReadJson

• Features

  Read option parameters from Json file and call SSL common API with these parameters additionally.

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input
  jsonBuffer	The memory address used to parse the Json file content	Input
  jsonfile	Json file name	Input
  buffSize	The memory size required to parse the Json file content	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 reads the AudioSslOption parameters from jsonfile, and additionally calls IaaSsl_Set_Shape, IaaSsl_Cal_Params,IaaSsl_SetMode with these parameters.

3.23. IaaSsl_SetHandleId

• Features

  Set SSL handle Id.

• Syntax

  ALGO_SSL_RET IaaSsl_SetHandleId(SSL_HANDLE handle, int id);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	SSL algorithm handle	Input
  id	SSL handle id range:[0,100]	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

---

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
AudioSslOption	SSL algorithm option parameter structure type

4.2. AudioSslInit

• Description

  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 user wants to use direction from SSL, please set as 0 and take the direction from IaaSsl_Get_Direction. If user wants 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

  IaaSsl_InitReadFromJson

4.3. AudioSslConfig

• Description

  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 gate threshold (dBfs). Note: Below this value, the frame will be treated as noise and will not go through SSL processing. Range:[-80,0]. Step size is 1
  direction_frame_num	The number of frames for on detection. Recommend to set as multiple of 16. Note: The results for SSL will be more stable if using longer frames. One frame of data processed by SSL is 128 sampling points. Therefore, the detection time = direction_frame_num * 128 / sampling rate. For example: The current sampling rate is 16K, and the setting direction_frame_num is 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

  IaaSsl_ConfigReadFromJson

4.4. SSL_HANDLE

• Description

  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

  IaaSsl_SetArbitraryShape

  IaaSsl_ReadJson

  IaaSsl_SetHandleId

4.5. AudioSslOption

• Description

  SSL algorithm option parameter structure type.

• Definition

  typedef struct
  
  {
  
      int shape;
  
      int mode;
  
      unsigned int angular_distance;
  
      unsigned int confidence;
  
      int gain;
  
      float array_pos[8];
  
  }AudioSslOption;
  

• Member

  Member name	Description
  shape	Please refer to IaaSsl_Set_Shape
  mode	Please refer to IaaSsl_SetMode
  angular_distance	Please refer to IaaSsl_SetMode
  confidence	Please refer to IaaSsl_SetMode
  gain	Please refer to IaaSsl_ApplyDigitalGain
  array_pos	Please refer to IaaSsl_SetArbitraryShape

• Note

  Please Use the option parameters with the corresponding API. Without calling the API, the parameter settings will not be applied to the algorithm.

• Related data types and interfaces

  IaaSsl_OptionReadFromJson

---

5. Error code

SSL API error codes are shown as follow:

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 two microphones 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	SSL 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.
0x10000320	ALGO_SSL_RET_INVALID_JSONFILE	SSL fails to read json file.