MI SSL API

1. Overview¶

1.1. Algorithm Description¶

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

1.2. Keyword¶

• Direction

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

  

1.3. Note¶

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.

2. API Reference¶

2.1. API List¶

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

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_LINUX.so/ libSSL_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.

2.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	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_LINUX.so/ libSSL_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

2.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_LINUX.so/ libSSL_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

2.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_LINUX.so/ libSSL_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

2.6. 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	Data pointer for SSL	Input
  delay_sample	The number of delayed samples for microphone dual channel. 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_LINUX.so/ libSSL_LINUX.a

• Note

  The data pointed to by 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 (That is, how many sampling points do a SSL process) set in IaaSsl_Init. Assuming that the point number is set to 128, each frame needs to read 128*2 point samples, because the SSL microphone_input must be dual-channel.

• Example

  #include <stdio.h>  
  #include <stdlib.h>
  
  #include "AudioSslProcess.h"
  
  /*  0:Fixed input file  1:User input file   */  
  #define IN_PARAMETER 1
  
  int main(int argc, char *argv[])  
  {  
      AudioSslInit ssl_init;  
      AudioSslConfig ssl_config;  
      /**************User change section start**********************/  
      /* The user modifies as needed,for example:5, 6(Unit: cm) */  
      ssl_init.mic_distance = 5;  
      /* The user modifies as needed,for example:128, ... */  
      ssl_init.point_number = 128;  
      /* The user modifies as needed */  
      ssl_init.sample_rate = 48000;  
      /* The user modifies as needed */  
      ssl_init.bf_mode = 0;  
      /* The user modifies as needed */  
      ssl_config.temperature = 25;  
      /* The user modifies as needed */  
      ssl_config.noise_gate_dbfs = -40;  
      /* The user modifies as needed */  
      ssl_config.direction_frame_num = 100;  
      /**************User change section end**********************/  
      unsigned int workingBufferSize;  
      SSL_HANDLE handle;  
      ALGO_SSL_RET ret = ALGO_SSL_RET_SUCCESS;  
      int delay_sample = 0;  
      int direction;  
      int counter = 0;  
      int frame_number = ssl_config.direction_frame_num;  
      short input[1024];  
      char *workingBufferAddress = NULL;  
      FILE* fpIn;  //input file  
      char src_file[128] = {0};
  
  #if IN_PARAMETER  
      if(argc < 2)  
      {  
          printf("Please enter the correct parameters!\n");  
          return -1;  
      }  
      sscanf(argv[1], "%s", src_file);  
  #else  
      sprintf(src_file, "%s", "./mic34_gain1_ssong_continue.wav");  
  #endif
  
      fpIn = fopen(src_file, "rb");  
      if(NULL == fpIn)  
      {  
          printf("fopen in_file failed !\n");  
          return -1;  
      }  
      printf("\nfopen in_file success !\n");  
      //(1)IaaSsl_GetBufferSize  
      workingBufferSize = IaaSsl_GetBufferSize();  
      workingBufferAddress = (char *)malloc(sizeof(char) * workingBufferSize);  
      if(NULL == workingBufferAddress)  
      {  
          printf("malloc SSL workingBuffer failed !\n");  
          return -1;  
      }  
      printf("malloc SSL workingBuffer success !\n");  
      //(2)IaaSsl_Init  
      handle = IaaSsl_Init(workingBufferAddress, &ssl_init);  
      if(NULL == handle)  
      {  
          printf("SSL:IaaSsl_Init  failed !\n");  
          return -1;  
      }  
      printf("SSL:IaaSsl_Init  success !\n");  
      //(3)IaaSsl_Config  
      ret = IaaSsl_Config(handle, &ssl_config);  
      if(ALGO_SSL_RET_SUCCESS != ret)  
      {  
          printf("SSL:IaaSsl_Config  failed !, ret = %d\n", ret);  
          return -1;  
      }  
      printf("SSL:IaaSsl_Config  success !\n");  
      ret = IaaSsl_Get_Config(handle, &ssl_config);  
      if(ALGO_SSL_RET_SUCCESS != ret)  
      {  
          printf("IaaSsl_Get_Config failed !, ret = %d\n", ret);  
      }  
      printf("IaaSsl_Get_Config succeed !\n");  
      printf("ssl_config.temperature = %u\n", ssl_config.temperature);  
      printf("ssl_config.noise_gate_dbfs = %d\n", ssl_config.noise_gate_dbfs);  
      printf("ssl_config.direction_frame_num = %d\n", ssl_config.direction_frame_num);  
  #if 1  
      /*Consider whether the input file has a header*/  
      fread(input, sizeof(char), 44, fpIn); // Remove the 44 bytes header  
  #endif  
      while(1)  
      {  
          /*2 is the number of channels*/  
          ret = fread(input, sizeof(short), ssl_init.point_number * 2, fpIn);  
          if(ret != ssl_init.point_number * 2)  
          {  
              printf("break:endReadSize = The remaining size = %d.\n", ret);  
              break;  
          }  
          //(4)IaaSsl_Run  
          ret = IaaSsl_Run(handle, input, &delay_sample);  
          if(ALGO_SSL_RET_SUCCESS != ret)  
          {  
              printf("SSL:IaaSsl_Run  failed !, ret = %d\n", ret);  
          }  
          counter ++;  
          if(counter == frame_number && ssl_init.bf_mode == 0)  
          {  
              //(5)IaaSsl_Get_Direction  
              ret = IaaSsl_Get_Direction(handle, &direction);  
              if(ALGO_SSL_RET_SUCCESS != ret)  
              {  
                  printf("SSL:IaaSsl_Get_Direction  failed !, ret = %d\n", ret);  
              }  
              printf("The current direction:%d \n", direction);  
              handle = IaaSsl_Reset(handle, &ssl_init);  
              if(NULL == handle)  
              {  
                  printf("SSL:IaaSsl_Reset failed !\n");  
                  return -1;  
              }  
              ret = IaaSsl_Config(handle, &ssl_config);  
              if(ALGO_SSL_RET_SUCCESS != ret)  
              {  
                  printf("SSL:IaaSsl_Config failed !, ret = %d\n", ret);  
                  return -1;  
              }  
              counter = 0;  
          }  
      }  
      printf("Explain:If the current direction is not \  
      in the -90~90 range, consult the API documentation.\n");  
      //(6)IaaSsl_Free  
      ret = IaaSsl_Free(handle);  
      if(ALGO_SSL_RET_SUCCESS != ret)  
      {  
          printf("IaaSsl_Free failed !, ret = %d\n", ret);  
      }  
      free(workingBufferAddress);  
      fclose(fpIn);  
      printf("SSL end !\n");  
      return 0;  
  }
  

2.7. 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	The value is between -90~90. When the value is -112, if the return value is success, there are two possibilities, one is that the volume is lower than noise_gate_dbfs, and the other is that the amount of data is not enough to calculate a credible direction. If the return value is not 0, correct it according to the error code.	Output

• Return value

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

• Dependency

  • Header: AudioSslProcess.h

  • Library: libSSL_LINUX.so/ libSSL_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

2.8. 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_LINUX.so/ libSSL_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

2.9. 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_LINUX.so/ libSSL_LINUX.a

• Example

  Please refer to IaaSsl_Run example.

3. SSL Data Type¶

3.1. SSL data type list¶

3.2. AudioSslInit¶

• Description

  Define Ssl algorithm initialization parameter structure type.

• Definition

  typedef struct
  
  {
  
      unsigned int point_number;
  
      unsigned int sample_rate;
  
      unsigned int mic_distance;
  
      unsigned int bf_mode;
  
  }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

• Note

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

• Related data types and interfaces

  IaaSsl_Init

  IaaSsl_Reset

3.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 50. Note: The number of frames for SSL detection must be a multiple of 50. 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 48K, setting s32DirectionFrameNum to 300, detection time =300 * 128 / 48000 = 0.8(s)

• Related data types and interfaces

  IaaSsl_Config

  IaaSsl_Get_Config

3.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_Run

  IaaSsl_Get_Direction

  IaaSsl_Reset

  IaaSsl_Free

4. Error Code¶

SSL API error codes are shown as follow: