BF Algorithm User Guide

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. Through the spatial filtering method and the sensor array, the signal of a specific angle can be strengthened, while the signal from other directions can be suppressed. Beamforming can be used at the transmitter and receiver to achieve spatial selectivity.

1.2. Keyword¶

1.2.1. Noise Gate¶

Noise Gate (dBFS). If the recording volume is smaller than noise gate, the frame will be treated as noise and update BF filters.

If the setting is too high, it may cause speech distortion. If the setting is too low, it is unable to update BF filters so the previous filters will be used for spatial filtering. Please be careful to use this parameter. This parameter must be referred to the actual recording volume of microphones. If the volume is too low and this parameter is set to a large value, the frame will be treated as noise. The value range is [-80, 0], the recommend value is -20, and the step size is 1.

1.2.2. Diagonal loading¶

By adding a diagonal loading to the diagonal elements of the matrix for regularization, it can be ensured that the inverse matrix must exist and hence improve the robustness of Beamforming. Please be careful to use this parameter. If the setting is too high, it will cause Beamforming result not good enough. If the setting is too low, it will cause speech distortion. The value range is [100, 1], the recommend value is 10, and the step size is 1.

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

With the help of Audio Process Chain, Beamforming will have better signal enhancement and interference suppression effect.

1.3.3. 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. SPECIFICATION¶

The number of microphones must be at least two or more.
The microphones should be the same type.
The microphones gain should be the same.
For best performance, background environment should be quiet.
If you are using audio files as the sound source , you should make sure that there is no signal clipping in audio files, see Figure 1.

Figure 1: Audio example of clipping

3. Coordinate system of Microphone Array¶

3.1. Multichannel Microphone array¶

Compared to the system consisting of a dual microphone array, multichannel microphone array system is capable of reaching better spatial selectivity at a specific angle because it has better bandwidth resolution and more microphone weights could be controlled. We denotes the specific angle (the angle we want to improve) microphone_doa that represents the direction of sound. 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.

3.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 microphone_doa locates at the upper plane (from -90 degree to 90 degree). Figure 2 illustrates the uniform linear array and its coordinate system. The microphone_doa 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: Uniform linear array and its coordinate system

3.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 microphone_doa locates at the whole plane (from -90 degree to 270 degree). Figure 3 illustrates the uniform circular array and its coordinate system. The microphone_doa 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 3: Uniform circular array and its coordinate system

4. API Reference¶

4.1. API List¶

API name	Features
IaaBf_GetBufferSize	Get the memory size required for Bf algorithm running
IaaBf_Init	Initialize Bf algorithm
IaaBf_SetConfig	Configure Bf algorithm
IaaBf_GetConfig	Get the current configuration parameter information of the Bf algorithm
IaaBf_SetShape	Assign the array shape of 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 by user.
IaaBf_GetArrayPosition	Obtain the mic array position from BF.
IaaBf_DynamicLoading	Assign the frequency band and corresponding intensity of diagonal loading.
IaaBf_SetMode	Assign the mode of BF.
IaaBf_SetAdaptiveIntensity	Assign the adaptive intensity for BF mode0, mode 3 or mode4.
IaaBf_SetCallbackFunction	Ikayaki chip authorization and licence checking for BF algorithm
IaaBf_GetAPIVersion	Return current BF API version
IaaBf_SetPfFlow	Assign where to apply the post filter for BF
IaaBf_SetCalibration	Calibrate the volume difference between microphones

4.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_2MIC_LINUX.so/ libBF_2MIC_LINUX.a/libBF_4MIC_LINUX.so/libBF_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 IaaBf_Run example.

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

Please refer to IaaBf_Run example.

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 the current configuration parameter information of the 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 the array shape of 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 integer to decide array shape of 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
- Our lib only supports uniform linear array and uniform circular array (Figure 2 and Figure 3). 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 Beamforming 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	Beamforming processing angle. This value could be set by user or calculated from SSL (Need one more transformation). Set 0 for sound coming from forward,90 for sound coming from left, and -90 for sound coming from right.	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.
- 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 beamforming process) set in IaaBf_Init.
- Take uniform linear array in Figure 2 as example, the microphone_input 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 array, If point_number =128points→ microphone_input = 128x4 = 512points, and microphone_output = 128points.

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

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 by user.

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 (number of microphone x 2) elements.
- The position of array center is the mean value of the given array_pos along [X,Y] axis, perspectively. The position of each microphone is the vector pointing from array center to each microphone.
- Notice that the microphone_doa 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_mean = 0.25 ,Y_mean = 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 access 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: [1,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 executed before using this API and the intensity is only applied to BF algorithm when is_dynamic equals 1. Only the first six elements of band will be used to define the frequency band and they must be in ascending order.
- The highest frequency corresponding to the current sampling rate is divided into 128 parts on average, and the frequency range corresponds to how many parts form a frequency band.
- For example: the current sampling rate is 16K, the corresponding maximum frequency is 8K, each one is 8000 / 128 ≈ 62.5Hz. Under the setting of {4,6,36, 49,50,51}, the ANR frequency range is {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}，anr_intensity is the ANR intensity, According to the frequency band division of anr_intensity_band, different parameters are set for the noise situation of each frequency band.
- Only the first seven elements of dl_intensity will be used to define the intensity at corresponding frequency band to enlarge the diagonal_loading in AudioBfConfig.
- The API is an optional API. Default is disable. The BF algorithm will be executed based on AudioBfConfig.

4.13. IaaBf_SetMode¶

Features

Assign the mode of BF.

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	Beamforming processing angle. Set 0 for sound coming from forward, 90 for sound coming from left, and -90 for sound coming from right.	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 Beamformer, 1: Fixed Beamformer, 2: GSC Beamformer, 3: Enhanced-Adaptive Beamformer, 4: AI Beamformer. If the API is not used, the default mode is 0: Adaptive Beamformer.
- Speed: Mode 1 > Mode 2 > Mode 0 > Mode 3 > Mode 4. BF performance: Mode4 > Mode 3 > Mode 0 > Mode 2 > Mode 1.
- Mode 3 has a greater noise reduction effect but distorted slightly. The users can set different angles (choose_doa). Notice that there isn't a rotational relationship between different directions due to array physical characteristics.
- When either BF mode 3 or BF mode 4 and APC are used simultaneously and the deep learning based noise reduction is enable(AudioAnrConfig anr_filter_mode 5), IaaApc_EnhanceNNBFMode must be called in APC algorithm.
- Mode 3 and Mode 4 are both post filters for Mode 0 output. The user can use IaaBf_SetPfFlow to assign where to apply the post filter in the audio workflow. The algorithm supports two position to apply post filter currently. (1) After BF's Output. (2) After APC's Output.
- The AIBF (mode 4) only supports linear array with 16kHz sample rate currently where the choose_doa is fixed at forward direction. The half-power bandwidth(HPBW) is designed as +- 35 degrees and AIBF will suppress the sound source outside the range of HPBW.
- It's better to use linear array with 5cm spacing when using Mode 4 (AIBF not gurantee the performance with other spacing). Notice that Mode 4 is only provided with static LINUX library.

4.14. IaaBf_SetAdaptiveIntensity¶

Features

Assign the adaptive intensity for BF mode 0 , 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 suppression performance for directional interference will be better while it may introduce more dirstortion, especially for Enhanced-Adaptive Beamformer and AI Beamformer.
- If the API is not used, BF will be executed based on normal intensity.

4.15. IaaBf_SetCallbackFunction¶

Features

Ikayaki chip authorization and licence checking for BF algorithm

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 SSL 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 post filter for BF.

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 two positions to apply post filter. 0: After APC's output. 1 : After BF'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.

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

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	Define the post filter position for Bf algorithm
BF_CALIBRATION	Bf algorithm volume calibration flag

5.2. AudioBfInit¶

Description

Define 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

5.3. AudioBfConfig¶

Description

Define 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	If the power of signal is smaller than this setting, this frame will take this frame as noise part, and use this frame to calculate some estimation. Please be careful to use this parameter. This parameter must be referred to the actual recording volume of microphones. If setting too high, it will cause the speech distortion. If setting too small, it will cause BF result not good enough. Recommend: -20.
noise_estimation	Noise estimation mode, Input: 0 or 1. 0 for adaptation method. 1 for average method. Recommend to use 0 for normal application.
output_gain	Output signal gain control (range : 0 ~ 1). 0.7 is the normal case. Setting as 1 will add 4db. Recommend: 0.7 (nothing change).
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.
diagonal_loading	Regularization term for inverse matrix. Please be careful to use this parameter. If setting too high, it will cause BF result not good enough. If setting too low, it will cause the speech distortion. Recommend: 10.

Related data types and interfaces

IaaBf_SetConfig

IaaBf_GetConfig

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

5.5. BF_WORKFLOW¶

Description

Define the post filter position for Bf algorithm.

Definition

typedef enum {

    BF_WORKFLOW_AFTER_APC = 0,

    BF_WORKFLOW_AFTER_BF = 1,

}BF_WORKFLOW;

Member

Member name Description

BF_WORKFLOW_AFTER_APC Apply post filter after APC

BF_WORKFLOW_AFTER_BF Apply post filter after BF
Related data types and interfaces

IaaBf_SetPfFlow

5.6. BF_CALIBRATION¶

Description

Bf algorithm volume calibration flag

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

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 BF VAD settings
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 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

7. Beamforming Flow¶

Figure 4: Beamforming working flow

8. Beamforming-APC Flow¶

Figure 5: Serialization for Beamforming-APC (With calling IaaApc_EnhanceNNBFMode)

Figure 6: Serialization for Beamforming-APC (Without calling IaaApc_EnhanceNNBFMode)

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

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

Parameter Name	Description	Input/Output
major	Main API version	Input/Output
minor	Secondary API version	Input/Output

Member name	Description
BF_WORKFLOW_AFTER_APC	Apply post filter after APC
BF_WORKFLOW_AFTER_BF	Apply post filter after BF

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

Return value	Result
Not NULL	Successful
NULL	Failed

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

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

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