MI SSL API

REVISION HISTORY

Revision No.
Description
 Date
1.0
  • Initial release
    		•  09/12/2020
    1.1
  • Modified API
    		•  10/15/2020
    1.2
  • 4MIC Sound Source Localization and Modified API
    		•  11/03/2021

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

    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)

      1.  #include <stdio.h>
2.  #include <unistd.h>
3.  #include <fcntl.h>
4.  #include <string.h>
5.  #include <sys/time.h>
6.  #include <sys/ioctl.h>
7.  #include <stdlib.h>
8.  #include "AudioSslProcess.h"
9.  
10. #define MIC_NUM (2)
11. #define USE_MALLOC   (1)
12. typedef unsigned char               uint8;
13. typedef unsigned short              uint16;
14. typedef unsigned long               uint32;
15. 
16. 
17. unsigned int _OsCounterGetMs(void)
18. {
19.     struct  timeval t1;
20.     gettimeofday(&t1,NULL);
21.     unsigned int T = ( (1000000 * t1.tv_sec)+ t1.tv_usec ) / 1000;
22.     return T;
23. }
24. 
25. int main(int argc, char *argv[])
26. {
27.     /*******Input file init*********/
28.     short input[256];
29.     char infileName[512];
30.     char outfileName[512];
31.     FILE * fin;
32.     FILE * fout;
33.     ALGO_SSL_RET ret;
34.     int counter2 = 0;
35.     unsigned int T0,T1,T2,T3;
36.     float avg = 0.0;
37.     float avg2 = 0.0;
38.     /**********common setting SSL***************/
39.     int point_number = 128;
40.     float microphone_distance = 12.0;
41.     int temperature = 20;
42.     int sample_rate = 16000;
43.     int delay_sample[1] = {0};
44.     int shape = 0;
45.     int direction = 0;
46.     int frame_number = 32;
47.     /**************SSL data init***********/
48.     int counter = 0;
49. #if USE_MALLOC
50.     char *WorkingBuffer2;
51.     WorkingBuffer2 = (char*)malloc(IaaSsl_GetBufferSize());
52. #endif
53.     AudioSslInit ssl_init;
54.     AudioSslConfig ssl_config;
55.     SSL_HANDLE handle;
56.     
57.     ssl_init.mic_distance = microphone_distance; //cm
58.     ssl_init.point_number = point_number;
59.     ssl_init.sample_rate = sample_rate;
60.     ssl_init.bf_mode = 0;
61.     ssl_init.channel = MIC_NUM;
62.     ssl_config.temperature = temperature; //c
63.     ssl_config.noise_gate_dbfs = -80;
64.     ssl_config.direction_frame_num = frame_number;
65.     /******init algorithm********/
66.     handle = IaaSsl_Init((char*)WorkingBuffer2, &ssl_init);
67.     if (handle==NULL)
68.     {
69.         printf("SSL init error\n\r");
70.         return -1;
71.     }
72.     else
73.     {
74.         printf("SSL init succeed\n\r");
75.     }
76.     
77.     ret = IaaSsl_Config(handle ,&(ssl_config));
78.     if (ret)
79.     {
80.         printf("Error occured in SSL Config\n\r");
81.         return -1;
82.     }
83.     ret = IaaSsl_Set_Shape(handle,shape);
84.     if (ret)
85.     {
86.         printf("Error occured in Array shape\n\r");
87.         return -1;
88.     }
89. 
90.     ret = IaaSsl_Cal_Params(handle);
91.     if (ret)
92.     {
93.         printf("Error occured in Array matrix calculation\n\r");
94.         return -1;
95.     }
96. 
97.     sprintf(infileName,"%s","./../sample/data/Chn_Left_right_12_0.wav");
98.     sprintf(outfileName,"%s","./SSL_result.txt");
99.     
100.        fin = fopen(infileName, "rb");
101.        if(!fin)
102.        {       printf("the input file 0 could not be open\n\r");
103.            return -1;
104.        }
105.    
106.        fout = fopen(outfileName, "w");
107.        if(!fout)
108.        {
109.            printf("the output file could not be open\n\r");
110.            return -1;
111.        }
112.    
113.        fread(input, sizeof(char), 44, fin); // read header 44 bytes
114.        fprintf(fout,"%s\t%s\t%s\n\r","time","direction","case");
115.        while(fread(input, sizeof(short), ssl_init.point_number*2, fin))
116.        {
117.            counter++;
118.            T0  = (long)_OsCounterGetMs();
119.            ret = IaaSsl_Run(handle,input,delay_sample);
120.            if(ret != 0)
121.            {
122.                printf("The Run fail\n");
123.                return -1;
124.            }
125.            // low resolution
126.    //      if (ssl_init.bf_mode == 1)
127.    //      {
128.    //          printf("delay_sample: %d\n",delay_sample[0]);
129.    //      }
130.            T1  = (long)_OsCounterGetMs();
131.            avg += (T1-T0);
132.            if(counter == ssl_config.direction_frame_num && ssl_init.bf_mode == 0)
133.            {
134.                counter2++;
135.                counter= 0;
136.                T2  = (long)_OsCounterGetMs();
137.                ret = IaaSsl_Get_Direction(handle, &direction);
138.                T3  = (long)_OsCounterGetMs();
139.                avg2 += (T3-T2);
140.                if(ret != 0 && ret!=ALGO_SSL_RET_RESULT_UNRELIABLE && ret!=ALGO_SSL_RET_BELOW_NOISE_GATE&&ret!=ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE)
141.                {
142.                    printf("The Get_Direction fail\n");
143.                    return -1;
144.                }
145.                // write txt file
146.                fprintf(fout,"%f\t%d",(float)(counter2*ssl_config.direction_frame_num*0.008),direction);
147.                if (ret==0)
148.                {
149.                    fprintf(fout,"\t%s\n\r","current time is reliable!");
150.                }
151.                else if (ret==ALGO_SSL_RET_BELOW_NOISE_GATE)
152.                {
153.                    fprintf(fout,"\t%s\n\r","current time volume is too small!");
154.                }
155.                else if(ret==ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE)
156.                {
157.                    fprintf(fout,"\t%s\n\r","current time delay_sample is out of range!");
158.                }
159.                else
160.                {
161.                    fprintf(fout,"\t%s\n\r","current time is not reliable!");
162.                }
163.                // reset voting
164.                ret = IaaSsl_Reset_Mapping(handle);
165.                if(ret != 0)
166.                {
167.                    printf("The ResetVoting fail\n");
168.                    return -1;
169.                }
170.            }
171.        }
172.        avg  = avg / (float)(ssl_config.direction_frame_num*counter2);
173.        avg2 = avg2 / (float)(counter2);
174.        printf("AVG for IaaSSL_RUN is %.3f ms\n",avg);
175.        printf("AVG for IaaSSL_GetDirection is %.3f ms\n",avg2);
176.        IaaSsl_Free(handle);
177.        fclose(fin);
178.        fclose(fout);
179.        free(WorkingBuffer2);
180.        printf("Done\n");
181.        return 0;
182.}

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

      1.  #include <stdio.h>
2.  #include <unistd.h>
3.  #include <fcntl.h>
4.  #include <string.h>
5.  #include <sys/time.h>
6.  #include <sys/ioctl.h>
7.  #include <stdlib.h>
8.  #include "AudioSslProcess.h"
9.  
10. #define MIC_NUM (4)
11. #define USE_MALLOC   (1)
12. typedef unsigned char               uint8;
13. typedef unsigned short              uint16;
14. typedef unsigned long               uint32;
15. 
16. unsigned int _OsCounterGetMs(void)
17. {
18.     struct  timeval t1;
19.     gettimeofday(&t1,NULL);
20.     unsigned int T = ( (1000000 * t1.tv_sec)+ t1.tv_usec ) / 1000;
21.     return T;
22. }
23. 
24. int main(int argc, char *argv[])
25. {
26.     /*********Input file init*******/
27.     short input[512];
28.     short input_tmp1[128],input_tmp2[128],input_tmp3[128],input_tmp4[128];
29.     char infileName[MIC_NUM][512];
30.     char outfileName[512];
31.     FILE * fin0,* fin1,* fin2,* fin3;
32.     FILE * fout;
33.     int k;
34.     ALGO_SSL_RET ret;
35.     int counter2 = 0;
36.     unsigned int T0,T1,T2,T3;
37.     float avg = 0.0;
38.     float avg2 = 0.0;
39.     /********common setting  SSL ********/
40.     int point_number = 128;
41.     float microphone_distance = 4.0;
42.     int temperature = 20;
43.     int sample_rate = 16000;
44.     int delay_sample[MIC_NUM-1] = {0,0,0}; //channel-1
45.     int shape  = 0;
46.     int direction = 0;
47.     int frame_number = 32;
48.     /********SSL data init********/
49.     int counter = 0;
50. #if USE_MALLOC
51.     char *WorkingBuffer_SSL;
52.     WorkingBuffer_SSL = (char*)malloc(IaaSsl_GetBufferSize());
53. #endif
54.     AudioSslInit ssl_init;
55.     AudioSslConfig ssl_config;
56.     SSL_HANDLE ssl_handle;
57.     
58.     ssl_init.mic_distance = microphone_distance;
59.     ssl_init.point_number = point_number;
60.     ssl_init.sample_rate = sample_rate;
61.     ssl_init.bf_mode = 0;
62.     ssl_init.channel  = MIC_NUM;
63.     ssl_config.temperature = temperature;
64.     ssl_config.noise_gate_dbfs = -80;
65.     ssl_config.direction_frame_num = frame_number;
66. 
67.     /*******init algorithm *****/
68.     ssl_handle = IaaSsl_Init((char*)WorkingBuffer_SSL, &ssl_init);
69.     if (ssl_handle == NULL)
70.     {
71.         printf("Init fail\n\r");
72.         return -1;
73.     }
74.     else
75.     {
76.         printf("SSL init succeed\n\r");
77.     }
78. 
79.     ret = IaaSsl_Config(ssl_handle ,&(ssl_config));
80.     if (ret)
81.     {
82.         printf("Error occured in SSL Config\n\r");
83.         return -1;
84.     }
85. 
86.     ret = IaaSsl_Set_Shape(ssl_handle,shape);
87.     if (ret)
88.     {
89.         printf("Error occured in Array shape\n\r");
90.         return -1;
91.     }
92. 
93.     ret = IaaSsl_Cal_Params(ssl_handle);
94.     if (ret)
95.     {
96.         printf("Error occured in Array matrix calculation\n\r");
97.         return -1;
98.     }
99.     
100.        /********open input file and input file*****/
101.    
102.        sprintf(infileName[0],"%s","./../sample/data/Chn-01.wav");
103.        sprintf(infileName[1],"%s","./../sample/data/Chn-02.wav");
104.        sprintf(infileName[2],"%s","./../sample/data/Chn-03.wav");
105.        sprintf(infileName[3],"%s","./../sample/data/Chn-04.wav");
106.        sprintf(outfileName,"%s","./SSL_result.txt");
107.        fin0 = fopen(infileName[0], "rb");
108.        if(!fin0)
109.        {       
110.            printf("the input file0 could not be open\n\r");
111.            return -1;
112.        }
113.        fin1 = fopen(infileName[1], "rb");
114.        if(!fin1)
115.        {       
116.            printf("the input file 1 could not be open\n\r");
117.            return -1;
118.        }
119.        fin2 = fopen(infileName[2], "rb");
120.        if(!fin2)
121.        {       
122.            printf("the input file 2 could not be open\n\r");
123.            return -1;
124.        }
125.        fin3 = fopen(infileName[3], "rb");
126.        if(!fin3)
127.        {       
128.            printf("the input file 3 could not be open\n\r");
129.            return -1;
130.        }
131.        fout = fopen(outfileName, "w");
132.        if(!fout)
133.        {
134.            printf("the output file could not be open\n\r");
135.            return -1;
136.        }
137.    
138.        fread(input, sizeof(char), 44, fin0); // read header 44 bytes
139.        fread(input, sizeof(char), 44, fin1); // read header 44 bytes
140.        fread(input, sizeof(char), 44, fin2); // read header 44 bytes
141.        fread(input, sizeof(char), 44, fin3); // read header 44 bytes
142.        
143.        short * input_ptr;
144.        fprintf(fout,"%s\t%s\t%s\n\r","time","direction","case");
145.        while(fread(input_tmp1, sizeof(short), point_number, fin0))
146.        {
147.            fread(input_tmp2, sizeof(short), point_number, fin1);
148.            fread(input_tmp3, sizeof(short), point_number, fin2);
149.            fread(input_tmp4, sizeof(short), point_number, fin3);
150.            input_ptr = input;
151.            for(k=0;k<point_number;k++)
152.            {
153.                *input_ptr =  input_tmp1[k];
154.                input_ptr++;
155.                *input_ptr =  input_tmp2[k];
156.                input_ptr++;
157.                *input_ptr =  input_tmp3[k];
158.                input_ptr++;
159.                *input_ptr =  input_tmp4[k];
160.                input_ptr++;
161.            }
162.            counter++;
163.            T0  = (long)_OsCounterGetMs();
164.            ret = IaaSsl_Run(ssl_handle,input,delay_sample);
165.            if(ret != 0)
166.            {
167.                printf("The Run fail\n");
168.                return -1;
169.            }
170.            // low resolution
171.    //      if (ssl_init.bf_mode == 1)
172.    //      {
173.    //          printf("delay_sample: %d,%d,%d\n",delay_sample[0],delay_sample[1],delay_sample[2]);
174.    //      }
175.            T1  = (long)_OsCounterGetMs();
176.            avg += (T1-T0);
177.            
178.            if(counter == ssl_config.direction_frame_num && ssl_init.bf_mode == 0)
179.            {
180.                counter2++;
181.                counter= 0;
182.                T2  = (long)_OsCounterGetMs();
183.                ret = IaaSsl_Get_Direction(ssl_handle, &direction);
184.                T3  = (long)_OsCounterGetMs();
185.                avg2 += (T3-T2);
186.                if(ret != 0 && ret!=ALGO_SSL_RET_RESULT_UNRELIABLE && ret!=ALGO_SSL_RET_BELOW_NOISE_GATE&&ret!=ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE)
187.                {
188.                    printf("The Get_Direction fail\n");
189.                    return -1;
190.                }
191.                // write txt file
192.                fprintf(fout,"%f\t%d",(float)(counter2*ssl_config.direction_frame_num*0.008),direction);
193.                if (ret==0)
194.                {
195.                    fprintf(fout,"\t%s\n\r","current time is reliable!");
196.                }
197.                else if (ret==ALGO_SSL_RET_BELOW_NOISE_GATE)
198.                {
199.                    fprintf(fout,"\t%s\n\r","current time volume is too small!");
200.                }
201.                else if(ret==ALGO_SSL_RET_DELAY_SAMPLE_TOO_LARGE)
202.                {
203.                    fprintf(fout,"\t%s\n\r","current time delay_sample is out of range!");
204.                }
205.                else
206.                {
207.                    fprintf(fout,"\t%s\n\r","current time is not reliable!");
208.                }
209.                // reset voting
210.                ret = IaaSsl_Reset_Mapping(ssl_handle);
211.                if(ret != 0)
212.                {
213.                    printf("The ResetVoting fail\n");
214.                    return -1;
215.                }
216.            }
217.        }
218.        avg  = avg / (float)(ssl_config.direction_frame_num*counter2);
219.        avg2 = avg2 / (float)(counter2);
220.        printf("AVG for IaaSSL_RUN is %.3f ms\n",avg);
221.        printf("AVG for IaaSSL_GetDirection is %.3f ms\n",avg2);
222.        IaaSsl_Free(ssl_handle);
223.        fclose(fin0);
224.        fclose(fin1);
225.        fclose(fin2);
226.        fclose(fin3);
227.        fclose(fout);
228.        free(WorkingBuffer_SSL);
229.        printf("Done\n");
230.        
231.        return 0;
232.}

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

    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. Step size is 1
      direction_frame_num The number of frames detected by the SSL function. Step size is 32. Note: The number of frames for SSL detection must be a multiple of 32. 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)

    • Related data types and interfaces

      IaaSsl_Config

      IaaSsl_Get_Config

    4.4. SSL_HANDLE

    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.