SGS BF 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	4 MIC Beamforming and modified API	08/03/2021
1.3	Add function IaaBf_SetArbitraryShape, IaaBf_GetArrayPosition, IaaBf_DynamicLoading, IaaBf_SetMode, IaaBf_SetAdaptiveIntensity, IaaBf_SetCallbackFunction	12/05/2022
1.4	Add function IaaBf_GetAPIVersion	04/10/2023
1.5	Add function IaaBf_SetPfFlow, IaaBf_SetCalibration, AIBF	10/27/2023
1.6	Extend BF_WORKFLOW for BF+AEC+ APC scenarios	12/21/2023
1.7	Add function IaaBf_GetJsonFileSize, IaaBf_InitReadFromJson, IaaBf_ConfigReadFromJson, IaaBf_OptionReadFromJson, IaaBf_SetHandleId. Extend BF_WORKFLOW for BF+AEC+AIWNR+APC scenarios	10/30/2024
1.8	Update file description. Deprecate API: IaaBf_SetCallbackFunction.	04/19/2025
1.81	Fix spelling error.	05/01/2025
1.82	Modify dynamic loading frequency band range.	07/16/2025
1.83	Add and update description of Chapter 1 and Chapter 7	11/25/2025

---

---

1. Overview

1.1. Algorithm Description

Bf (short for Beamforming) or spatial filtering is a directional signal processing method for sensor array transmission or reception. With spatial filtering and the sensor (microphone) array, the signal from a specific angle could be strengthened, while the signal from other direction could be suppressed. Beamforming is applicable to be used at the transmitter and receiver to achieve spatial selectivity.

Keyword

• Noise Gate and Voice Activity Detection Mode

  • The Bf filter is only updated when current frame is judged to be noise frame. If current frame is judged to be speech frame, then the Bf will use past filter for processing. Currently we support two methods to decide if current frame is noise. Please refer to AudioBfConfig.

  • noise_gate_dbfs: The volume threshold(dBFS). The current frame will be judged as noise frame if the recording volume is smaller than the threshold. Please be careful to use this parameter. This parameter must be referred to the actual volume from microphones. Range: [-80,0], the recommend value is -20, and the step size is 1.

  • vad_enable: Voice Activity Detection (VAD) Mode. Whether to use VAD method to judge the current frame is noise frame or speech frame. Range: [0,1], the recommend value is 0, and the step size is 1. If vad_enable=0, use noise_gate_dbfs for judgement. If vad_enable=1, use VAD for judgement.

• Diagonal loading

  In order to improve Beamforming robustness, applying diagonal loading is able to guarantee the inverse matrix exists, and hence achieve regularization. Please be careful to use this parameter. If the setting is too high, it will deteriorate spatial filtering performance. If the setting is too low, it will cause speech distortion. Range: [1,100], the recommend value is 10, and the step size is 1. Please refer to AudioBfConfig.

• Array shape and coordinate system definition.

  Bf Algorithm currently provides 1-dimensional or 2-dimensional array. Please refer to 3. Coordinate System of Microphone Array.

Note

We currently provide 2 or 4 microphone array Bf libraries. The user needs to confirm whether the corresponding Bf library is used correctly. If you need Bf 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. With the help of Audio Process Chain (APC), Beamforming could achieve better signal enhancement and interference suppression effect.

1.2. Basic Structure

An input signal buffer and a output signal buffer are required for Bf algorithm to process. After the Bf algorithm allocates memory and completes parameter initialization and configuration, the input data buffer is processed by th Bf algorithm, and then written into the output data buffer. Notice that the length of input signal buffer and output signal buffer are not same because the Bf algorithm is a multi-channel input single channel output system.

1.3. Function Introduction

The Bf algorithm preserves sound from the enhanced direction and suppresses sound from other direction to improve the signal-to-interference ratio.

1.4. Application Scenarios

Bf algorithm is commonly applied in conference systems, building intercoms, security monitoring, and consumer electronic products. In addition to enhancing the user’s directional voice and filtering out surrounding noise, BF combined with APC can provide a comfortable audio experience with low distortion, good sound quality, and stable volume in diverse environments.

1.5. Chip Difference

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

1.6. Examples Introduction

Use the Bf API to obtain the memory size required by the Bf algorithm, initialize the Bf algorithm handle, configure parameters to the Bf handle, execute the Bf algorithm, and release the Bf 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 "AudioBfProcess.h"
    
    #define USE_MALLOC   (1)
    typedef unsigned char               uint8;
    typedef unsigned short              uint16;
    typedef unsigned long               uint32;
    
    float AVERAGE_RUN(int a)
    {
        static unsigned int num = 0;
        static float avg = 0;
        if(num == 0) avg = 0;
        num++;
        avg = avg + ((float)a - avg) / ((float)num);
        return avg;
    }
    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[])
    {
        short input[256];
        short output[128];
        char infileName[512];
        char outfileName[512];
    
        FILE * fin, * fout;
        ALGO_BF_RET ret;
        int shape = 0;
        float direction = 0.0;
        int delay_sample = 0;
        float avg = 0;
        int counter = 0;
        unsigned int T0,T1;
        AudioBfInit bf_init;
        AudioBfConfig bf_config;
        BF_HANDLE handle;
        bf_init.mic_distance = 8.0;
        bf_init.point_number = 128;
        bf_init.sample_rate = 16000;
        bf_init.channel = 2;
        bf_config.noise_gate_dbfs = -20;
        bf_config.temperature = 20;
        bf_config.noise_estimation = 0;
        bf_config.output_gain = 0.7;
        bf_config.vad_enable = 0;
        bf_config.diagonal_loading = 10;
    #if USE_MALLOC
        char *WorkingBuffer2;
        WorkingBuffer2 = (char*)malloc(IaaBf_GetBufferSize());
    #endif
        handle = IaaBf_Init((char*)WorkingBuffer2, &bf_init);
        if (handle==NULL)
        {
            printf("BF init error\r\n");
            return -1;
        }
        else
        {
            printf("BF init succeed\r\n");
        }
        ret = IaaBf_SetConfig(handle,&bf_config);
        if (ret)
        {
            printf("Error occured in Config\n");
            return -1;
        }
        ret = IaaBf_SetShape(handle,shape);
        if (ret)
        {
            printf("Error occured in Array shape\n");
            return -1;
        }
        sprintf(infileName,"%s","./../sample/data/Chn-14.wav");
        sprintf(outfileName,"%s","./BFOut.pcm");
    
        fin = fopen(infileName, "rb");
        if(!fin)
        {
            printf("the input file could not be open\n");
            return -1;
        }
    
        fout = fopen(outfileName, "wb");
        if(!fout)
        {
            printf("the output file could not be open\n");
            return -1;
        }
    
        fread(input, sizeof(char), 44, fin); // read header 44 bytes
        fwrite(input, sizeof(char),44, fout); // write 44 bytes output
        // int delay_sample = 0;
        while(fread(input, sizeof(short), bf_init.point_number*bf_init.channel, fin))
        {
            counter++;
            T0  = (long)_OsCounterGetMs();
            ret = IaaBf_Run(handle,input,output,&direction);
            T1  = (long)_OsCounterGetMs();
            avg += (T1 - T0);
            if(ret)
            {
                printf("Error occured in Run\n");
                return -1;
            }
            fwrite(output, sizeof(short), bf_init.point_number, fout);
        }
        avg /= counter;
        printf("AVG is %.2f ms\n",avg);
        IaaBf_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 "AudioBfProcess.h"
    
    #define MIC_NUM (4)
    #define USE_MALLOC   (1)
    typedef unsigned char               uint8;
    typedef unsigned short              uint16;
    typedef unsigned long               uint32;
    
    float AVERAGE_RUN(int a)
    {
        static unsigned int num = 0;
        static float avg = 0;
        if(num == 0) avg = 0;
        num++;
        avg = avg + ((float)a - avg) / ((float)num);
        return avg;
    }
    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 output[128];
        short input_tmp1[128],input_tmp2[128],input_tmp3[128],input_tmp4[128];
        FILE * fin0, * fin1, * fin2, * fin3, * fout;
    
        char infileName[MIC_NUM][512];
        char outfileName[512];
        ALGO_BF_RET ret;
        int k;
        float avg = 0;
        int counter = 0;
        unsigned int T0, T1;
        /********common setting between SSL and BF********/
        int point_number = 128;
        float microphone_distance = 4.0;
        int temperature = 20;
        int sample_rate = 16000;
        int shape =  0;
        // int delay_sample[MIC_NUM-1] = {0,0,0}; //channel-1
        float direction = 0.0;
        /*******BF data init*********/
    #if USE_MALLOC
        char *WorkingBuffer_BF;
        WorkingBuffer_BF = (char*)malloc(IaaBf_GetBufferSize());
    #endif
    
        AudioBfInit bf_init;
        AudioBfConfig bf_config;
        BF_HANDLE bf_handle;
        bf_init.mic_distance = microphone_distance;
        bf_init.point_number = point_number;
        bf_init.sample_rate = sample_rate;
        bf_init.channel = MIC_NUM;
        bf_config.noise_gate_dbfs = -20;
        bf_config.temperature = temperature;
        bf_config.noise_estimation = 0;
        bf_config.output_gain = 0.7;
        bf_config.vad_enable = 0;
        bf_config.diagonal_loading = 10;
        bf_handle = IaaBf_Init((char*)WorkingBuffer_BF, &bf_init);
        if (bf_handle==NULL)
        {
            printf("BF init error\r\n");
            return -1;
        }
        else
        {
            printf("BF init succeed\r\n");
        }
        ret = IaaBf_SetConfig(bf_handle,&bf_config);
        if (ret)
        {
            printf("Error occured in Config\n");
            return -1;
        }
        ret = IaaBf_SetShape(bf_handle,shape);
        if (ret)
        {
            printf("Error occured in Array shape\n");
            return -1;
        }
        /********open input file and output 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","./BFOut.pcm");
    
        fin0 = fopen(infileName[0], "rb");
        if(!fin0)
        {
            printf("the input file 0 could not be open\n");
            return -1;
        }
    
        fin1 = fopen(infileName[1], "rb");
        if(!fin1)
        {
            printf("the input file 1 could not be open\n");
            return -1;
        }
        fin2 = fopen(infileName[2], "rb");
        if(!fin2)
        {
            printf("the input file 2 could not be open\n");
            return -1;
        }
        fin3 = fopen(infileName[3], "rb");
        if(!fin3)
        {
            printf("the input file 3 could not be open\n");
            return -1;
        }
        fout = fopen(outfileName, "wb");
        if(!fout)
        {
            printf("the output file could not be open\n");
            return -1;
        }
        fread(input, sizeof(char), 44, fin0);
        fread(input, sizeof(char), 44, fin1);
        fread(input, sizeof(char), 44, fin2);
        fread(input, sizeof(char), 44, fin3);
        fwrite(input, sizeof(char),44, fout);
        short * input_ptr;
    
        while(fread(input_tmp1, sizeof(short), bf_init.point_number, fin0))
        {
            fread(input_tmp2, sizeof(short), bf_init.point_number, fin1);
            fread(input_tmp3, sizeof(short), bf_init.point_number, fin2);
            fread(input_tmp4, sizeof(short), bf_init.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 = IaaBf_Run(bf_handle,input,output,&direction);
            T1  = (long)_OsCounterGetMs();
            avg += (T1 - T0);
            if(ret)
            {
                printf("Error occured in Run\n");
                return -1;
            }
            fwrite(output, sizeof(short),point_number, fout);
        }
        avg /= counter;
        printf("AVG is %.2f ms\n",avg);
        IaaBf_Free(bf_handle);
        fclose(fin0);
        fclose(fin1);
        fclose(fin2);
        fclose(fin3);
        fclose(fout);
        free(WorkingBuffer_BF);
        printf("Done\n");
    
        return 0;
    }
    

2. Specification

• The number of microphones must be at least two or more.

• The microphones specs should be the same.

• The microphones gain should be the same.

• For best performance, background environment should be quiet.

• Make sure that there is no signal clipping in audio files, see below figure.

  ​

---

3. Coordinate System of Microphone Array

3.1. Multichannel Microphone array

Compared to dual microphone array, multichannel microphone array is capable of achieving better spatial selectivity at enhanced direction because it has better bandwidth resolution and more controllable microphone filters. In Practice, there are two main types of multichannel array system, one is the uniform linear array, and the other is uniform circular array.

3.1.1. Uniform Linear Array

Uniform linear array is a line array that is spaced evenly. Because of its symmetry, only the enhanced direction located at the upper plane (from -90 degree to 90 degree) is considered. Below figure illustrates the uniform linear array and its coordinate system. The enhanced 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.

3.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, the enhanced direction located at the whole plane (from -90 degree to 270 degree) is considered. Below figure illustrates the uniform circular array and its coordinate system. The enhanced 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.

---

4. API Reference

4.1. API List

API name	Features
IaaBf_GetBufferSize	Get memory size required for Bf algorithm.
IaaBf_Init	Initialize Bf algorithm.
IaaBf_SetConfig	Configure Bf algorithm.
IaaBf_GetConfig	Get current configuration parameters of Bf algorithm.
IaaBf_SetShape	Assign array shape for Bf.
IaaBf_Run	Bf algorithm processing.
IaaBf_Reset	Reinitialize Bf algorithm.
IaaBf_Free	Release Bf algorithm resources.
IaaBf_SetArbitraryShape	Assign the arbitrary array geometry for Bf.
IaaBf_GetArrayPosition	Obtain the mic array position from Bf.
IaaBf_DynamicLoading	Assign the frequency band and corresponding intensity of diagonal loading.
IaaBf_SetMode	Assign Bf operation mode.
IaaBf_SetAdaptiveIntensity	Assign the adaptive intensity for Bf mode0, mode 3 or mode4.
IaaBf_SetCallbackFunction	Ikayaki chip authorization and licence checking for BF algorithm( Deprecated, no longer restricted).
IaaBf_GetAPIVersion	Return current Bf API version.
IaaBf_SetPfFlow	Assign where to apply the Bf's post filter in audio flow.
IaaBf_SetCalibration	Calibrate the volume difference between microphones.
IaaBf_GetJsonFileSize	Get the memory size to parse the content of the Json file required by Bf algorithm.
IaaBf_InitReadFromJson	Configure Json parameters to the init structure of the Bf algorithm.
IaaBf_ConfigReadFromJson	Configure Json parameters to the config structure of the Bf algorithm.
IaaBf_OptionReadFromJson	Configure Json parameters to the option structure of the Bf algorithm.
IaaBf_ReadJson	Read option parameters from Json file and call Bf common API with these parameters additionally.
IaaBf_SetHandleId	Set Bf Handle Id.

4.2. IaaBf_GetBufferSize

• Features

  Get memory size required for Bf algorithm.

• Syntax

  unsigned int IaaBf_GetBufferSize(void);
  

• Return value

  Return value is the memory size required to run Bf algorithm.

• Dependency

  • Header: AudioBfProcess.h

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

4.3. IaaBf_Init

• Features

  Initialize 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_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Example

  Please refer to IaaBf_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.

4.4. IaaBf_SetConfig

• Features

  Configure Bf algorithm.

• Syntax

  ALGO_BF_RET IaaBf_SetConfig(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_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Example

  Please refer to IaaBf_Run example.

4.5. IaaBf_GetConfig

• Features

  Get current configuration parameters of Bf algorithm.

• Syntax

  ALGO_BF_RET IaaBf_GetConfig(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_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Example

  Please refer to IaaBf_Run example.

4.6. IaaBf_SetShape

• Features

  Assign array shape for Bf.

• Syntax

  ALGO_BF_RET IaaBf_Setshape(BF_HANDLE handle,int shape);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  shape	The assigned array shape for Bf. 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: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  • The Bf lib only supports uniform linear array and uniform circular array. Please refer to 3. Coordinate system_of Microphone Array. IaaBf_SetArbitraryShape is applicable to special array geometry.

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

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

• Example

  Please refer to IaaBf_Run example.

4.7. IaaBf_Run

• Features

  Bf algorithm processing.

• Syntax

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

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  microphone_input	The microphone raw data.	Input
  microphone_output	Output data after Beamforming.	Output
  microphone_doa	Enhanced direction for Beamforming. The direction could be set by user or obtained from SSL. Range:[-90,270]. Please refer to 3. Coordinate System of Microphone Array.	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_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 beamforming process) set in IaaBf_Init. Please refer to Example I.

  • For multichannel microphone array (microphone number is bigger than two where binaural data is not enough), the input data of each microphone is 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 beamforming process) set in IaaBf_Init. Please refer to Example II.

  • Take 4mic uniform linear array as example, the microphone_input order should be placed in the format of [MIC1→MIC2→MIC3→MIC4].

  • The data length of microphone_output must correspond to the point_number set in IaaBf_init. For 4mic example, if point_number =128points→ microphone_input = 128x4 = 512points, and microphone_output = 128points.

• Example

  Please refer to 1.6. Examples Introduction.

4.8. 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_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

4.9. 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_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Example

  Please refer to IaaBf_Run example.

4.10. IaaBf_SetArbitraryShape

• Features

  Assign the arbitrary array geometry for Bf.

• Syntax

  ALGO_BF_RET IaaBf_SetArbitraryShape(BF_HANDLE handle, float* array_pos);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  array_pos	Microphone array position pointer. Units: cm.	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  • The API supports user to set arbitrary array geometry. If this API is called after IaaBf_SetShape, it will overwrite the array_geometry defined previously by IaaBf_SetShape, vise versa.

  • The input array_pos is the two-dimensional coordinates of Cartesian coordinate system with the order [X,Y]. Therefore, it must contain (numbers of microphone x 2) elements.

  • The position of array center is the average value of the given array_pos along [X,Y] axis, respectively. The position of each microphone is the vector pointing from array center to each microphone.

  • Notice that the microphone_doa(enhanced direction) for the system is still defined as the angle between the array center and the x-axis where counterclockwise is positive.

  • Giving array_pos:{-4,-2,-1,-3,2,3,4,2}, the array center is [X=0.25,Y=0], while Mic1’s [X,Y] is [-4.25,-2], Mic2’s [X,Y] is [-1.25,-3], Mic3’s [X,Y] is [1.75,3], and Mic4’s [X,Y] is [3.75,2].

4.11. IaaBf_GetArrayPosition

• Features

  Obtain the mic array position from Bf.

• Syntax

  ALGO_BF_RET IaaBf_GetArrayPosition(BF_HANDLE handle,float* array_pos);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  array_pos	Microphone array position pointer. Units: cm.	Input/Output

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  • The output is the three-dimensional coordinates of Cartesian coordinate system with the order [x,y,z] while the value of z-axis will always be zero. The array_pos must contain (number of microphone x 3) elements.

  • If the API is called after IaaBf_SetShape, the output order of the microphone array is same as Section 3.1 (From left to right).

  • If the API is called after IaaBf_SetArbitraryShape, the output order of the microphone array is same as IaaBf_SetArbitraryShape.

  • The API is only applicable to obtain the array position. It won’t affect the BF performance.

4.12. IaaBf_DynamicLoading

• Features

  Assign the frequency band and corresponding intensity of diagonal loading.

• Syntax

  ALGO_BF_RET IaaBf_DynamicLoading(BF_HANDLE handle,int* band, int* dl_intensity, int* is_dynamic);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  band	Frequency band pointer. Range: [0,128]; step size: 1	Input
  dl_intensity	Diagonal loading intensity pointer. Range: [1,1000]; step size: 1	Input
  is_dynamic	0: disable 1: enable	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  • IaaBf_SetConfig must be called before using this API and the dl_intensity is only applied to BF algorithm when is_dynamic equals 1.

  • The first six elements of band are used to set different frequency subbands. Thus, totally seven frequency subbands are obtained. Notice that the elements must be in ascending order.

  • The first seven elements of dl_intensity are used to set the intensity for seven frequency subbands, which is able to amplify the diagonal_loading in AudioBfConfig for each frequency subbands, respectively.

  • The highest frequency corresponding to the current sampling rate is divided into 128 parts evenly. For example, the sampling rate is 16K, the corresponding maximum frequency is 8K, each one is 8000 / 128 ≈ 62.5Hz.

  • Under the band settings {4,6,36, 49,50,51}, the corresponding frequency subbands are set as {0~4 * 62.5Hz, 4~6 * 62.5Hz, 6~36 * 62.5Hz, 36~49 * 62.5Hz, 49~50 * 62.5Hz, 50~51 * 62.5Hz, 51-127 * 62.5Hz} = {0~250Hz, 250~375Hz, 375~2250Hz, 2250~3062.5Hz, 3062.5~3125Hz, 3125~3187.5Hz, 3187.5Hz~8000Hz}.

  • Optional API (Default: Disable). The algorithm will be executed based on diagonal loading set in AudioBfConfig.

4.13. IaaBf_SetMode

• Features

  Assign Bf operation mode.

• Syntax

  ALGO_BF_RET IaaBf_SetMode(BF_HANDLE handle,float choose_doa, int mode);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  choose_doa	Enhanced direction for Beamforming. The direction could be set by user or obtained from SSL. Range:[-90,270]. Please refer to 3. Coordinate System of Microphone Array.	Input
  mode	Range: [0,4]. Step size: 1	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  • Our Bf library supports mode from 0~4. 0: Adaptive Beamforming, 1: Fixed Beamforming, 2: GSC Beamforming, 3: Enhanced-Adaptive Beamforming, 4: AI Beamforming. If the API is not used, the default mode is 0: Adaptive Beamforming.

  • Speed: Mode 1 > Mode 2 > Mode 0 > Mode 3 > Mode 4. BF performance: Mode4 > Mode 3 > Mode 0 > Mode 2 > Mode 1.

  • Mode 3 and Mode 4 are both post filter for Mode 0 output. User can set different enhanced direction (choose_doa) to further improve the effect of spatial filtering but may have few distortion. Notice that there isn't a rotational relationship between different directions due to array physical characteristics. User can tune the intensity of post filter via IaaBf_SetAdaptiveIntensity.

  • When either BF mode 3 or BF mode 4 and APC are used simultaneously, IaaApc_EnhanceNNBFMode must be called in APC algorithm. In addition, The user can use IaaBf_SetPfFlow to assign where to apply the post filter in the audio workflow. The algorithm supports four positions to apply post filter currently. (1) After BF's Output. (2)BF->APC, After APC's Output (3) BF->AEC->APC, After APC's Output. (4) BF->AEC->AIWNR->APC, After APC's Output.

  • It's better to use linear array with 5cm spacing when using Mode 4 (AIBF not guarantee the performance with other spacing). Notice that Mode 4 is only provided with LINUX library.

4.14. IaaBf_SetAdaptiveIntensity

• Features

  Assign the adaptive intensity for Bf mode0, mode 3 or mode4.

• Syntax

  ALGO_BF_RET IaaBf_SetAdaptiveIntensity(BF_HANDLE handle,int intensity);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  intensity	Range: [0,4]. Step size: 1. 0: low; 1,2: normal; 3,4: high	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  • The API will assign the intensity of Adaptive Bf such as mode0, mode3, and mode4. When the intensity becomes bigger, the spatial filtering performance will be better while it may introduce more distortion, especially for Enhanced-Adaptive Bf and AI Bf.

  • Default intensity=1.

4.15. IaaBf_SetCallbackFunction

• Features

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

• Syntax

  ALGO_BF_RET IaaBf_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	Input
  envGetString	Function pointer for obtaining the license message from envrionment 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: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  • The API for authorization is only for Ikayaki chip.

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

4.16. IaaBf_GetAPIVersion

• Features

  Return current Bf API version.

• Syntax

  ALGO_BF_RET IaaBf_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: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

4.17. IaaBf_SetPfFlow

• Features

  Assign where to apply the Bf's post filter in audio flow.

• Syntax

  ALGO_BF_RET IaaBf_SetPfFlow(BF_HANDLE handle, BF_WORKFLOW bf_workflow);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  bf_workflow	Position where the post filter is applied	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  • The algorithm supports four positions to apply post filter. 0(BF->APC): After APC's output. 1(BF) : After BF's output. 2(BF->AEC->APC): After APC's output. 3(BF->AEC->AIWNR->APC): After APC's output. If the API is not used, the default position is 1: After BF's Output.

  • When bf_workflow is assigned as 0, the post filter would be applied after APC's output. The built-in conventional noise reduction effect from BF would be closed while the user can tune the noise reduction performance via APC.

  • When bf_workflow is assigned as 1, the post filter would be applied after BF's output. The built-in conventional noise reduction effect from BF would be opened. It's recommended to turn off NR from APC to avoid too much distortion.

  • When bf_workflow is assigned as 2, it means that AEC is implemented between BF and APC. The post filter would be applied after APC's output. The built-in conventional noise reduction effect from BF would be closed while the user can tune the noise reduction performance via APC.

  • When bf_workflow is assigned as 3, it means that AEC and AI-based WNR are implemented between BF and APC. The post filter would be applied after APC's output. The built-in conventional noise reduction effect from BF would be closed while the user can tune the noise reduction performance via APC.

4.18. IaaBf_SetCalibration

• Features

  Calibrate the volume difference between microphones.

• Syntax

  ALGO_BF_RET IaaBf_SetCalibration(BF_HANDLE handle, BF_CALIBRATION calibration_flag);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  calibration_flag	Flag to decide if using calibration. Please refer to BF_CALIBRATION	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  • The API will calibrate the volume difference between microphones. 0: Without calibration. 1: With calibration. If the API is not used, the default mode is 0: without calibration.

4.19. IaaBf_GetJsonFileSize

• Features

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

• Syntax

  unsigned int IaaBf_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: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

4.20. IaaBf_InitReadFromJson

• Features

  Configure Json parameters to the init structure of the Bf algorithm.

• Syntax

  ALGO_BF_RET IaaBf_InitReadFromJson(AudioBfInit* bf_init, char* jsonBuffer, char* jsonfile, unsigned int buffSize);
  

• Parameters

  Parameter Name	Description	Input/Output
  bf_init	Bf 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: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  The API parses the initialization parameters into AudioBfInit structure from jsonfile, and is going to be used by IaaBf_Init.

4.21. IaaBf_ConfigReadFromJson

• Features

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

• Syntax

  ALGO_BF_RET IaaBf_ConfigReadFromJson(AudioBfConfig* bf_config, char* jsonBuffer, char* jsonfile, unsigned int buffSize);
  

• Parameters

  Parameter Name	Description	Input/Output
  bf_config	Configure the structure handle of the Bf 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: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  The API parses the config parameters into AudioBfConfig structure from jsonfile, and is going to be used by IaaBf_SetConfig.

4.22. IaaBf_OptionReadFromJson

• Features

  Configure Json parameters to the option structure of the Bf algorithm.

• Syntax

  ALGO_BF_RET IaaBf_OptionReadFromJson(AudioBfOption* bf_option, char* jsonBuffer, char* jsonfile, unsigned int buffSize);;
  

• Parameters

  Parameter Name	Description	Input/Output
  bf_option	Configure the option handle of the BF 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: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  The API parses the option parameters into AudioBfOption structure from jsonfile, and is going to be used by IaaBf_SetShape,IaaBf_Run,IaaBf_SetArbitraryShape,IaaBf_DynamicLoading,IaaBf_SetMode,IaaBf_SetAdaptiveIntensity](#414-iaabf_setadaptiveintensity),IaaBf_SetPfFlow,IaaBf_SetCalibration,IaaBf_ReadJson.

4.23. IaaBf_ReadJson

• Features

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

• Syntax

  ALGO_BF_RET IaaBf_ReadJson(BF_HANDLE handle,AudioBfOption* bf_option, char* jsonBuffer, char* jsonfile, unsigned int buffSize);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  bf_option	Configure the option handle of the BF 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: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

• Note

  The API reads the AudioBfOption parameters from jsonfile, and additionally calls common API IaaBf_SetShape,IaaBf_SetMode,IaaBf_SetAdaptiveIntensity,IaaBf_SetPfFlow,IaaBf_SetCalibration with these parameters.

4.24. IaaBf_SetHandleId

• Features

  Set Bf Handle Id.

• Syntax

  ALGO_BF_RET IaaBf_SetHandleId(BF_HANDLE handle, int id);
  

• Parameters

  Parameter Name	Description	Input/Output
  handle	Bf algorithm handle	Input
  id	Bf handle id range:[0,100]	Input

• Return value

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

• Dependency

  • Header: AudioBfProcess.h

  • Library: libBF_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_4MIC_LINUX.a

---

5. Bf Data Type

5.1. Bf data type list

DATA TYPE	Description
AudioBfInit	Bf algorithm initialization parameter structure type.
AudioBfConfig	Bf algorithm configuration parameter structure type.
BF_HANDLE	Bf algorithm handle type.
BF_WORKFLOW	Assign the post filter position for Bf algorithm.
BF_CALIBRATION	Bf algorithm volume calibration indicator.
AudioBfOption	Bf algorithm option parameter structure type.

5.2. AudioBfInit

• Description

  Bf algorithm initialization parameter structure type.

• Definition

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

• Member

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

• Related data types and interfaces

  IaaBf_Init

  IaaBf_Reset

  IaaBf_InitReadFromJson

5.3. AudioBfConfig

• Description

  Bf algorithm configuration parameter structure type.

• Definition

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

• Member

  Member name	Description
  temperature	Ambient temperature (Celsius). Celsius = (5/9) * (Fahrenheit-32). Step size is 1.
  noise_gate_dbfs	Noise volume threshold. This parameter must be referred to the actual recording volume. Please be careful to use this parameter. Range: [-80,0]. Recommend: -20. Step size is 1.
  noise_estimation	Noise estimation mode. Range: [0,1]. 0: adaptation method. 1: average method. Recommend: 0
  output_gain	Output signal gain. Range: [0~1]. 0.7: 0dB gain. 1: 3~4dB gain. Recommend: 0.7.
  vad_enable	Whether to use Voice Activity detection (VAD). Range: [0,1]. 1: VAD is used to decide whether each frame is noise part. 0: noise_gate_dbfs is used to decide whether each frame is noise part. Recommend: 0.
  diagonal_loading	Regularization term for inverse matrix. Range: [1,100]. Step size: 1. Please be careful to use this parameter. If diagonal loading is too high, it will cause result not good enough. If diagonal loading is too low, it will cause speech distortion. Recommend: 10.

• Related data types and interfaces

  IaaBf_SetConfig

  IaaBf_GetConfig

  IaaBf_ConfigReadFromJson

5.4. BF_HANDLE

• Description

  Bf algorithm handle type.

• Definition

  typedef void* BF_HANDLE;
  

• Related data types and interfaces

  IaaBf_Init

  IaaBf_SetConfig

  IaaBf_GetConfig

  IaaBf_SetShape

  IaaBf_Run

  IaaBf_Reset

  IaaBf_Free

  IaaBf_SetArbitraryShape

  IaaBf_GetArrayPosition

  IaaBf_DynamicLoading

  IaaBf_SetMode

  IaaBf_SetAdaptiveIntensity

  IaaBf_GetAPIVersion

  IaaBf_SetPfFlow

  IaaBf_SetCalibration

  IaaBf_ReadJson

  IaaBf_SetHandleId

5.5. BF_WORKFLOW

• Description

  Assign the post filter position for Bf algorithm.

• Definition

  typedef enum {
  
      BF_WORKFLOW_AFTER_APC = 0,
  
      BF_WORKFLOW_AFTER_BF = 1,
  
      BF_WORKFLOW_AFTER_BF_AEC_APC = 2,
  
      BF_WORKFLOW_AFTER_BF_AEC_AIWNR_APC = 3,
  
  }BF_WORKFLOW;
  

• Member

  Member name	Description
  BF_WORKFLOW_AFTER_APC	Apply post filter after APC
  BF_WORKFLOW_AFTER_BF	Apply post filter after BF
  BF_WORKFLOW_AFTER_BF_AEC_APC	Apply post filter after APC when an AEC is implemented between BF and APC
  BF_WORKFLOW_AFTER_BF_AEC_AIWNR_APC	Apply post filter after APC when an AEC and AI-based WNR are implemented between BF and APC

• Related data types and interfaces

  IaaBf_SetPfFlow

5.6. BF_CALIBRATION

• Description

  Bf algorithm volume calibration indicator.

• Definition

  typedef enum {
  
      BF_CALIBRATION_DISABLE = 0,
  
      BF_CALIBRATION_ENABLE  = 1,
  
  }BF_CALIBRATION;
  

• Member

  Member name	Description
  BF_CALIBRATION_DISABLE	Bf processing without calibrating volume difference
  BF_CALIBRATION_ENABLE	Calibrate the volume difference before Bf processing

• Related data types and interfaces

  IaaBf_SetCalibration

5.7. AudioBfOption

• Description

  Bf algorithm option parameter structure type.

• Definition

  typedef struct
  
  {
  
      int shape;
  
      float direction;
  
      int is_dynamic;
  
      int mode;
  
      int intensity;
  
      BF_WORKFLOW bf_workflow;
  
      BF_CALIBRATION calibration_flag;
  
      float array_pos[8];
  
      int band[6];
  
      int dl_intensity[7];
  
  }AudioBfOption;
  

• Member

  Member name	Description
  shape	Please refer to IaaBf_SetShape
  direction	Please refer to IaaBf_SetMode,IaaBf_Run
  is_dynamic	Please refer to IaaBf_DynamicLoading
  mode	Please refer to IaaBf_SetMode
  intensity	Please refer to IaaBf_SetAdaptiveIntensity
  bf_workflow	Please refer to IaaBf_SetPfFlow
  calibration_flag	Please refer to IaaBf_SetCalibration
  array_pos	Please refer to IaaBf_SetArbitraryShape
  band	Please refer to IaaBf_DynamicLoading
  dl_intensity	Please refer to IaaBf_DynamicLoading

• Note

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

• Related data types and interfaces

  IaaBf_OptionReadFromJson

---

6. Error code

Bf API error codes are shown as follow:

Error code	Definition	Description
0x00000000	ALGO_BF_RET_SUCCESS	Bf runs successfully.
0x10000301	ALGO_BF_RET_INIT_ERROR	Invalid Bf initialization.
0x10000302	ALGO_BF_RET_INVALID_CONFIG	Invalid Bf Config.
0x10000303	ALGO_BF_RET_INVALID_HANDLE	Invalid Bf Handle.
0x10000304	ALGO_BF_RET_INVALID_NOISE_ESTIMATION	Invalid Bf noise estimation settings.
0x10000305	ALGO_BF_RET_INVALID_VAD_ENABLE	Invliad VAD settings for BF.
0x10000306	ALGO_BF_RET_INVALID_OUTPUT_GAIN	Invalid Bf output gain settings.
0x10000307	ALGO_BF_RET_INVALID_INPUT_POINTER	Invalid Bf input indicator.
0x10000308	ALGO_BF_RET_INVALID_SAMPLERATE	Invalid Bf sampling rate.
0x10000309	ALGO_BF_RET_INVALID_POINTNUMBER	Invalid Bf sampling point.
0x10000310	ALGO_BF_RET_INVALID_CHANNEL	Invalid Bf channel number.
0x10000311	ALGO_BF_RET_INVALID_CALLING	Bf API sequence error.
0x10000312	ALGO_BF_RET_API_CONFLICT	Other APIs are running.
0x10000313	ALGO_BF_RET_INVALID_GEOMETRY_TYPE	Invalid Bf array shape.
0x10000314	ALGO_BF_RET_INVALID_MIC_DISTANCE	Invalid Bf microphone distance.
0x10000315	ALGO_BF_RET_INVALLD_DYNAMIC_BAND	Invalid Bf band and dl_intensity.
0x10000316	ALGO_BF_RET_INVALID_SETMODE	Invalid Bf operation mode.
0x10000317	ALGO_BF_RET_INVALID_GETPOSITION	Bf fails to get array position.
0x10000318	ALGO_BF_RET_INVALID_SETINTENSITY	Bf fails to assign adaptive intensity.
0x10000319	ALGO_BF_RET_INVALID_SETCALLBACK	Warning: Bf authorization and license checking fails.
0x10000320	ALGO_BF_RET_INVALID_SETPFFLOW	Bf fails to assign post filter position.
0x10000321	ALGO_BF_RET_INVALID_CALIBRATION	Bf fails to calibrate volume difference.
0x10000322	ALGO_BF_RET_INVALID_JSONFILE	Bf fails to open Json file.

---

7. Relationship between Bf and APC connection

The user can customize the location where the Bf post filter is applied and the source of ANR module (from Bf intrinsic conventional NR or from APC) within overall system.

• Examples of Bf and APC connection

  ret = IaaBf_SetPfFlow(handle_bf, BF_WORKFLOW_AFTER_APC);
  while(fread(input, sizeof(short), bf_init.point_number*bf_init.channel, fin))
  {
      ret = IaaBf_Run(handle_bf,input,output,&direction);
      ret = IaaApc_EnhanceNNBFMode(handle_apc,handle_bf,1);
      ret = IaaApc_Run(handle_apc,output);
  }