MI BF API

1. Overview¶

1.1. Algorithm Description¶

BF (short for Beamforming) or spatial filtering is a directional signal processing technology for sensor array transmission or reception. Strengthen the signal to achieve a specific angle combination of components in the microphone array in such a way, while others will be attenuated. Beamforming can be used at the transmitter and receiver to achieve spatial selectivity.

1.2. Keyword¶

1.2.1. Noise Gate¶

Noise Gate (dBFS), below this value, the frame will be treated as noise.

If the setting is too high, it will easily cause voice distortion. If the setting is too low, the algorithm effect will be affected. So we should to handle it with care. The value range is [-80,0], the recommended value is -44, and the step size is 1.

1.2.2. Noise Suppression Mode¶

Noise Suppression Mode, the larger the value, the stronger the noise cancellation intensity.

If the setting is too high, it will easily cause voice distortion. If the setting is too low, the algorithm effect will be affected. So we should to handle it with care. The value range is [0,30], the recommended value is 44, and the step size is 1.

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. IaaBf_GetBufferSize¶

• Features

  Get the memory size required for Bf algorithm running.

• Syntax

  unsigned int IaaBf_GetBufferSize(void);
  

• Return value

  Return value is the memory size required for Bf algorithm running.

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_LINUX.so/ libBF_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 IaaBf_Run example.

2.3. IaaBf_Init¶

• Features

  Initialize the Bf algorithm.

• Syntax

  BF_HANDLE IaaBf_Init(char*
  working_buffer,AudioBfInit* bf_init);
  

• Parameters

  Parameter Name	Description	Input/Output
  working_buffer	Memory address used by Bf algorithm	Input
  bf_init	Bf algorithm initialization structure pointer	Input

• Return value

  Return value	Result
  Not NULL	Successful
  NULL	Failed

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_LINUX.so/ libBF_LINUX.a

• Example

  Please refer to IaaBf_Run example.

2.4. IaaBf_Config¶

• Features

  Configure Bf algorithm.

• Syntax

  ALGO_BF_RET IaaBf_Config(BF_HANDLE
  handle,AudioBfConfig* bf_config);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  bf_config	Bf algorithm configuration structure pointer	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_LINUX.so/ libBF_LINUX.a

• Example

  Please refer to IaaBf_Run example.

2.5. IaaBf_Get_Config¶

• Features

  Get the current configuration parameter information of the Bf algorithm.

• Syntax

  ALGO_BF_RET IaaBf_Get_Config(BF_HANDLE
  handle,AudioBfConfig *bf_config);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  bf_config	Bf algorithm configuration structure pointer	Output

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_LINUX.so/ libBF_LINUX.a

• Example

  Please refer to IaaBf_Run example.

2.6. IaaBf_Run¶

• Features

  Bf algorithm processing.

• Syntax

  ALGO_BF_RET IaaBf_Run(BF_HANDLE handle,short* microphone_input,int *
  microphone_doa);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  microphone_input	Data pointer waiting for sound source location confirming	Input
  microphone_doa	Beamforming processing angle. Calculated by SSL, which will calculate the direction of the voice. If the sound comes from the front (fixed direction), you can input array 0. The length of this array should be the number of microphones minus 1.	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_LINUX.so/ libBF_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 (the number of sampling points once beamforming process) set in IaaBf_Init.

• Example

  #include <stdio.h>  
  #include <string.h>  
  #include <sys/time.h>  
  #include <stdlib.h>
  
  #include "AudioBfProcess.h"
  
  /*  0:Fixed input file  1:User input file   */  
  #define IN_PARAMETER 1
  
  int main(int argc, char *argv[])  
  {  
      short in_output[1024];  
      char *workingBuffer = NULL;  
      unsigned int workingBufferSize;  
      ALGO_BF_RET ret = ALGO_BF_RET_SUCCESS;  
      int tempSize;  
      int delay_sample = 0;  
      AudioBfInit bf_init;  
      AudioBfConfig bf_config, bf_get_config;  
      BF_HANDLE handle;  
      FILE* fpIn;  
      FILE* fpOut;  
      char src_file[128] = {0};  
      char dst_file[128] = {0};
  
  #if IN_PARAMETER  
      if(argc < 3)  
      {  
          printf("Please enter the correct parameters!\n");  
          return -1;  
      }  
      sscanf(argv[1], "%s", src_file);  
      sscanf(argv[2], "%s", dst_file);  
  #else  
      sprintf(src_file, "%s", "./12cm_2mic_8k_0degree.wav");  
      if(argc < 2)  
      {  
          printf("Please enter the correct parameters!\n");  
          return -1;  
      }  
      sscanf(argv[1], "%s", dst_file);  
  #endif
  
      /****User change section start****/  
      bf_init.mic_distance = 12;  
      bf_init.point_number = 128;  
      bf_init.sample_rate = 8000;  
      bf_init.channel = 2;
  
      bf_config.noise_gate_dbfs = -40;  
      bf_config.temperature = 25;  
      bf_config.noise_supression_mode = 8;  
      bf_config.noise_estimation = 1;  
      bf_config.output_gain = 0.7;  
      bf_config.vad_enable = 0;
  
      /****User change section end ****/  
      //(1)IaaBf_GetBufferSize  
      workingBufferSize = IaaBf_GetBufferSize();  
      workingBuffer = (char*)malloc(workingBufferSize);  
      if(NULL == workingBuffer)  
      {  
          printf("workingBuffer malloc failed !\n");  
          return -1;  
      }  
      //(2)IaaBf_Init  
      handle = IaaBf_Init(workingBuffer, &bf_init);  
      if (NULL == handle)  
      {  
          printf("IaaBf_Init failed !\n");  
          return -1;  
      }  
      printf("IaaBf_Init succeed !\n");  
      //(3)IaaBf_Config  
      ret = IaaBf_Config(handle, &bf_config);  
      if (ALGO_BF_RET_SUCCESS != ret)  
      {  
          printf("IaaBf_Config failed !, ret = %d\n", ret);  
          return -1;  
      }  
      printf("IaaBf_Config succeed !\n");  
      //(4)IaaBf_Get_Config  
      ret = IaaBf_Get_Config(handle, &bf_get_config);  
      if(ALGO_BF_RET_SUCCESS != ret)  
      {  
          printf("IaaBf_Get_Config dailed !, ret = %d\n", ret);  
          return -1;  
      }  
      printf("IaaBf_Get_Config succeed !\n");  
      printf("bf_get_config.noise_gate_dbfs = %d\n", bf_get_config.noise_gate_dbfs);  
      printf("bf_get_config.temperature = %u\n", bf_get_config.temperature);  
      printf("bf_get_config.noise_supression_mode = %d\n", bf_get_config.noise_supression_mode);  
      printf("bf_get_config.noise_estimation = %d\n", bf_get_config.noise_estimation);  
      printf("bf_get_config.output_gain = %f\n", bf_get_config.output_gain);  
      fpIn = fopen(src_file, "rb");  
      if(NULL == fpIn)  
      {  
          printf("fopen in_file failed !\n");  
          return -1;  
      }  
      printf("fopen in_file success !\n");  
      fpOut = fopen(dst_file, "wb");  
      if(NULL == fpOut)  
      {  
          printf("fopen out_file failed !\n");  
          return -1;  
      }  
      printf("fopen out_file success !\n");  
  #if 1  
      fread(in_output, sizeof(char), 44, fpIn);  
      fwrite(in_output, sizeof(char), 44, fpOut);  
  #endif  
      tempSize = bf_init.point_number * bf_init.channel;  
      while(tempSize == fread(in_output, sizeof(short), tempSize, fpIn))  
      {  
          //(5)IaaBf_Run  
          ret = IaaBf_Run(handle, in_output, &delay_sample);  
          if(ALGO_BF_RET_SUCCESS != ret)  
          {  
              printf("IaaBf_Run failed !\n");  
              return -1;  
          }  
          fwrite(in_output, sizeof(short), tempSize, fpOut);  
      }  
      //(6)IaaBf_Free  
      ret = IaaBf_Free(handle);  
      if(ALGO_BF_RET_SUCCESS != ret)  
      {  
          printf("IaaBf_Free failed !, ret = %d\n", ret);  
          return -1;  
      }  
      printf("IaaBf_Free succeed !\n");  
      fclose(fpIn);  
      fclose(fpOut);  
      free(workingBuffer);  
      printf("BF end !\n");
  
      return 0;  
  }
  

2.7. IaaBf_Reset¶

• Features

  Reinitialize Bf algorithm.

• Syntax

  BF_HANDLE IaaBf_Reset(BF_HANDLE
  working_buffer,AudioBfInit* bf_init);
  

• Parameters

  Parameter Name	Description	Input/Output
  working_buffer	Bf algorithm running memory address	Input
  bf_init	Bf algorithm initialization structure pointer	Input

• Return value

  Return value	Result
  Not NULL	Successful
  NULL	Failed

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_LINUX.so/ libBF_LINUX.a

2.8. IaaBf_Free¶

• Features

  Release Bf algorithm resources.

• Syntax

  ALGO_BF_RET IaaBf_Free(BF_HANDLE handle);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_LINUX.so/ libBF_LINUX.a

• Example

  Please refer to IaaBf_Run example.

3. BF Data Type¶

3.1. BF data type list¶

3.2. AudioBfInit¶

• Description

  Define Bf algorithm initialization parameter structure type.

• Definition

  typedef struct
  
  {
  
      unsigned int point_number;
  
      unsigned int sample_rate;
  
      unsigned int mic_distance;
  
      unsigned int channel;
  
  }AudioBfInit;
  

• Member

  Member name	Description
  point_number	The sampling points that Bf algorithm processed once
  sample_rate	Sampling rate, currently supports 8k/16k/32k/48k
  mic_distance	The distance between two mics, unit: cm, recommend: 5cm or 6cm
  channel	Number of channels

• Related data types and interfaces

  IaaBf_Init

  IaaBf_Reset

3.3. AudioBfConfig¶

• Description

  Define Bf algorithm configuration parameter structure type

• Definition

  typedef struct
  
  {
  
      unsigned int temperature;
  
      int noise_gate_dbfs;
  
      int noise_supression_mode;
  
      int noise_estimation;
  
      float output_gain;
  
      int vad_enable;
  
  }AudioBfConfig;
  

• Member

  Member name	Description
  temperature	Ambient temperature (Celsius) Celsius = (5/9) * (Fahrenheit-32) Step size is 1
  noise_gate_dbfs	Noise Gate(dB) below this value, the frame will be treated as noise. So we should to handle it with care. If the setting is too high, it will easily cause voice distortion. If the setting is too low, it will affect the effect of BF. Recommended value: -44, step size: 1.
  noise_supression_mode	Noise Suppression Mode, the larger the value, the stronger the noise cancellation intensity. So we should to handle it with care. If the setting is too high, it will easily cause voice distortion. If the setting is too low, it will affect the effect of BF. Range: [0,30], Recommended value: 8, step size: 1
  noise_estimation	Noise estimation mode,Input: 0 or 1. 0: Adaptive mode; recommended for keyword positioning preprocessing; 1: Average mode; recommended for voice communication.
  output_gain	Output gain, range: [0,1] Setting to 0.7 is normal, Recommendation value without any gain; Setting to 1, will increase 4dB.
  vad_enable	Whether voice alive detection (VAD) mode is enable. Input: 0 or 1. If this setting is enable, VAD is used to calculate whether each frame enters the noise estimation process. If this setting is disable, the noise_gate_dbfs set above is used to determine whether it is treated as noise.

• Related data types and interfaces

  IaaBf_Config

  IaaBf_Get_Config

3.4. BF_HANDLE¶

• Description

  Bf algorithm handle type.

• Definition

  typedef void* BF_HANDLE;
  

• Related data types and interfaces

  IaaBf_Init

  IaaBf_Config

  IaaBf_Get_Config

  IaaBf_Run

  IaaBf_Reset

  IaaBf_Free

4. Error code¶

BF API error codes are shown as follow: