SGS AEC ALGORITHM USER GUIDE¶

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	09/08/2020
1.1	Modified API	10/15/2020
1.2	Added IaaAec_SetRecursiveRatio function	02/16/2022
1.21	more detail for point number and channel	08/18/2022
1.22	more detail for stereo data arrangement	10/25/2022
1.23	Added IaaAec_ADF_Run and IaaAec_NLP_Run function	03/10/2023
1.3	Added IaaAec_GetAPIVersion and IaaAec_GetConfig function	04/14/2023
1.31	Added input pointer length detail	07/12/2023
1.4	Added IaaAec_SetHandleId function	02/19/2024
1.5	Added IaaAec_GetJsonFileSize, IaaAec_InitReadFromJson,IaaAec_ConfigReadFromJson,IaaAec_OptionReadFromJson function	10/30/2024
1.51	Update description of suppression_mode_freq in AudioAecConfig	03/24/2025
1.52	Update file description and copyright	04/19/2025
1.53	Remove copyright	05/13/2025
1.54	Modify suppression_mode_freq range in AudioAecConfig	07/16/2025
1.6	Added IaaAec_SetADFBlockNum	08/01/2025
1.7	Added IaaAec_SetMode	08/15/2025
1.71	Added IaaAec_SetMode note	09/23/2025
1.72	Fix formatting and textual errors	10/28/2025
1.73	Add and update description of Chapter 1	11/21/2025

1. OVERVIEW¶

1.1. Module Description¶

AEC (short for Acoustic Echo Cancellation) is a function used to suppress far-end echo.

Echo is common in conference systems, building intercom, security monitoring and other scenarios. When the far-end sound is played from the speaker, the microphone re-collects the sound played by the speaker and transmits it back to the far-end after a very small delay, which will cause an echo to be heard at the far-end.

Keyword

Far-end signal (Sin)

The signal source of the device speaker, or the signal from the remote.
Near-end signal (Rin)

The signal recorded by the microphone of the device, which may include acoustic echo and near-end talker signals.
Acoustic echo (AE)

The sound played from the speaker of the device is transmitted back to the microphone through a direct or indirect path, and the echo is generated. The far-end talker will hear his echo after a certain delay after speaking. This echo is claimed as an acoustic echo (AE).
Single talk

Only the speaker on the device side plays the far-end signal (Sin = AE + NS when NS =0)
Double talk

While the speaker on the device side is playing, the near-end talker also speaks into the microphone (Sin = AE + NS when NS≠0)

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.

1.2. Basic Structure¶

After the AEC algorithm allocates memory and completes parameter initialization and configuration, it requires an input Near-End signal buffer and an input Far-End signal buffer. The AEC processes the Near-End and Far-End buffers according to the configured parameters and algorithm, and then writes the processed data back to the Near-End input buffer.

1.3. Function Introduction¶

AEC :

To remove the far-end signal present in the near-end audio, preventing the occurrence of acoustic echo.

1.4. Application Scenarios¶

AEC is commonly used in conference systems, building intercoms, and security monitoring, preventing the far-end system from capturing its own acoustic echo due to signal transmission delays.

1.5. Chip Difference Description¶

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

1.6. Example Introduction¶

Use the AEC API to obtain the memory size required by the AEC algorithm, initialize the AEC algorithm handle, configure parameters to the AEC handle, execute the AEC algorithm, and release the AEC algorithm resources.

    #include <stdio.h>
    #include <unistd.h>
    #include <fcntl.h>
    #include <string.h>
    #include <time.h>
    #ifndef OS_WINDOWS
    #include <sys/ioctl.h>
    #endif
    #include <sys/types.h>
    #include <sys/stat.h>
    #include <stdlib.h>
    #include <string.h>
    #include <sys/time.h>

    #include "AudioAecProcess.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[1024];
        short input_aec[1024];
    #if USE_MALLOC
        char *WorkingBuffer2;
    #else
        char WorkingBuffer2 [1024*500];
    #endif

        char infileName[512];
        char infileName_aec[512];
        char outfileName[512];
        int counter=0;
        unsigned int T0, T1;
        float avg;
        FILE * fin, * fout, * fin_aec;
        ALGO_AEC_RET ret;
        AudioAecInit aec_init;
        AudioAecConfig aec_config;
        AEC_HANDLE handle;

        unsigned int supMode_band[6] = {20,40,60,80,100,120};
        unsigned int supMode[7] = {4,4,4,4,4,4,4};

        int PN = 128;
        unsigned int recursive_ratio = 1;
        unsigned int block_num = 8;
        unsigned int mode = 0;
        aec_init.point_number = PN;
        aec_init.nearend_channel = 1;
        aec_init.farend_channel = 1;
        aec_config.delay_sample = 0;
        aec_init.sample_rate = IAA_AEC_SAMPLE_RATE_16000;
        aec_config.comfort_noise_enable = IAA_AEC_FALSE;
        memcpy(&(aec_config.suppression_mode_freq[0]),supMode_band,sizeof(int)*6);
        memcpy(&(aec_config.suppression_mode_intensity[0]),supMode,sizeof(int)*7);

    #if USE_MALLOC
        WorkingBuffer2 = (char*)malloc(IaaAec_GetBufferSize());
    #endif
        handle = IaaAec_Init((char*)WorkingBuffer2, &aec_init);
        if (handle==NULL)
        {
            printf("AEC init error\r\n");
            return -1;
        }
        else
        {
            printf("AEC init succeed\r\n");
        }
        sprintf(infileName,"%s",".//..//sample//data//AEC_AFE_16K_mono.wav"); //near
        sprintf(infileName_aec,"%s",".//..//sample//data//I2S_16K_mono.wav"); //far
        sprintf(outfileName,"%s",".//AecOut.wav");

        ret = IaaAec_Config(handle ,&(aec_config));
        ret += IaaAec_SetRecursiveRatio(handle, recursive_ratio);
        ret += IaaAec_SetADFBlockNum(handle, block_num);
        ret += IaaAec_SetMode(handle, mode);
        if(ret != ALGO_AEC_RET_SUCCESS)
        {
            printf("Error occured in AEC config function \n");
            return -1;
        }

        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


        fin_aec = fopen(infileName_aec, "rb");
        if(!fin_aec)
        {
            printf("the input file could not be open\n");
            return -1;
        }
        fread(input_aec, sizeof(char), 44, fin_aec); // read header 44 bytes
    #if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
        printf("The chip is big-endian!!!\n");
        int k=0;
        short right = 0x0000;
        short left = 0x0000;
    #endif

        while(fread(input, sizeof(short), PN*aec_init.nearend_channel, fin))
        {
            fread(input_aec, sizeof(short), PN*aec_init.farend_channel, fin_aec);
    #if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__


            for(k=0;k<PN*aec_init.nearend_channel;k++)
            {
                right = (input[k]>>8)&(0x00ff);
                left = (input[k]<<8)&(0xff00);
                input[k] = left|right;
                right = (input_aec[k]>>8)&(0x00ff);
                left = (input_aec[k]<<8)&(0xff00);
                input_aec[k] = left|right;
            }

    #endif
            counter++;

            T0  = (long)_OsCounterGetMs();
            ret = IaaAec_Run(handle, input , input_aec );
            T1  = (long)_OsCounterGetMs();
            avg = AVERAGE_RUN(T1 - T0);

            if(counter%100 == 0)
            {
                printf("counter = %d\n", counter);
                printf("current time = %f\n", (float)counter*PN/aec_init.sample_rate);

                printf("process time = %lu(ms)\t",(long)(T1 - T0));
                printf("AVG is %.2f ms\n",avg);
            }
            if(ret != ALGO_AEC_RET_SUCCESS)
            {
                printf("Error occured in AEC run function \n");
                break;
            }

    #if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__


            for(k=0;k<PN*aec_init.nearend_channel;k++)
            {
                right = (input[k]>>8)&(0x00ff);
                left = (input[k]<<8)&(0xff00);
                input[k] = left|right;
            }

    #endif
            fwrite(input, sizeof(short), PN*aec_init.nearend_channel, fout);

        }
        ret = IaaAec_Free(handle);
        if(ret != ALGO_AEC_RET_SUCCESS)
        {
            printf("Error occured in AEC free function \n");
            return -1;
        }
        fclose(fin);
        fclose(fin_aec);
        fclose(fout);

        printf("Done\n");
    return 0;
    }

Use the AEC API to read parameters from the AEC JSON file, obtain the memory size required for AEC algorithm execution, initialize the AEC algorithm handle, configure parameters to the handle, execute the AEC algorithm, and release the AEC algorithm resources.

    #include <stdio.h>
    #include <unistd.h>
    #include <fcntl.h>
    #include <string.h>
    #include <time.h>
    #ifndef OS_WINDOWS
    #include <sys/ioctl.h>
    #endif
    #include <sys/types.h>
    #include <sys/stat.h>
    #include <stdlib.h>
    #include <string.h>
    #include <sys/time.h>


    #include "AudioAecProcess.h"


    #define PN              (128)
    #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 input_aec[256];
    #if USE_MALLOC
        char *WorkingBuffer2;
    #else
        char WorkingBuffer2 [1024*500];
    #endif

        char infileName[512];
        char infileName_aec[512];
        char outfileName[512];
        int counter=0;
        unsigned int T0, T1;
        float avg;
        FILE * fin, * fout, * fin_aec;


        char aec_para_json_file[512];
        sprintf(aec_para_json_file,"%s","./../sample/data/AecParamJson.json");
        unsigned int aec_para_buffersize = IaaAec_GetJsonFileSize(aec_para_json_file);


    #if USE_MALLOC
        WorkingBuffer2 = (char*)malloc(IaaAec_GetBufferSize());
        char *aec_para_json_buf_ptr = (char*)malloc(aec_para_buffersize);
    #endif

        ALGO_AEC_RET ret;
        AudioAecInit aec_init;
        AudioAecConfig aec_config;
        AEC_HANDLE handle;
        AudioAecOption aec_option;

        memset(&aec_init,0,sizeof(AudioAecInit));
        memset(&aec_config,0,sizeof(AudioAecConfig));
        memset(&aec_option,0,sizeof(AudioAecOption));
        ret = IaaAec_InitReadFromJson(&aec_init, aec_para_json_buf_ptr, aec_para_json_file, aec_para_buffersize);
        ret += IaaAec_ConfigReadFromJson(&aec_config, aec_para_json_buf_ptr, aec_para_json_file, aec_para_buffersize);
        ret += IaaAec_OptionReadFromJson(&aec_option, aec_para_json_buf_ptr, aec_para_json_file, aec_para_buffersize);


        handle = IaaAec_Init((char*)WorkingBuffer2, &aec_init);
        if (handle==NULL)
        {
            printf("AEC init error\r\n");
            return -1;
        }
        else
        {
            printf("AEC init succeed\r\n");
        }
        sprintf(infileName,"%s","./../sample/data/AEC_AFE_16K_mono.wav"); //near
        sprintf(infileName_aec,"%s","./../sample/data/I2S_16K_mono.wav"); //far
        sprintf(outfileName,"%s","./../sample/data/AecOut.wav");

        ret += IaaAec_Config(handle ,&(aec_config));
        ret += IaaAec_SetRecursiveRatio(handle, aec_option.recursive_ratio);
        ret += IaaAec_SetADFBlockNum(handle, aec_option.block_num);
        ret += IaaAec_SetMode(handle, aec_option.mode);
        if(ret != ALGO_AEC_RET_SUCCESS)
        {
            printf("Error occured in AEC config function \n");
            return -1;
        }

        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


        fin_aec = fopen(infileName_aec, "rb");
        if(!fin_aec)
        {
            printf("the input file could not be open\n");
            return -1;
        }
        fread(input_aec, sizeof(char), 44, fin_aec); // read header 44 bytes
    #if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
        printf("The chip is big-endian!!!\n");
        int k=0;
        short right = 0x0000;
        short left = 0x0000;
    #endif

        while(fread(input, sizeof(short), PN*aec_init.nearend_channel, fin))
        {
            fread(input_aec, sizeof(short), PN*aec_init.farend_channel, fin_aec);
    #if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__


            for(k=0;k<PN*aec_init.nearend_channel;k++)
            {
                right = (input[k]>>8)&(0x00ff);
                left = (input[k]<<8)&(0xff00);
                input[k] = left|right;
                right = (input_aec[k]>>8)&(0x00ff);
                left = (input_aec[k]<<8)&(0xff00);
                input_aec[k] = left|right;
            }

    #endif
            counter++;

            T0  = (long)_OsCounterGetMs();
            ret = IaaAec_Run(handle, input , input_aec );
            T1  = (long)_OsCounterGetMs();
            avg = AVERAGE_RUN(T1 - T0);

            if(counter%100 == 0)
            {
                printf("counter = %d\n", counter);
                printf("current time = %f\n", (float)counter*PN/aec_init.sample_rate);

                printf("process time = %lu(ms)\t",(long)(T1 - T0));
                printf("AVG is %.2f ms\n",avg);
            }
            if(ret != ALGO_AEC_RET_SUCCESS)
            {
                printf("Error occured in AEC run function \n");
                break;
            }

    #if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__


            for(k=0;k<PN*aec_init.nearend_channel;k++)
            {
                right = (input[k]>>8)&(0x00ff);
                left = (input[k]<<8)&(0xff00);
                input[k] = left|right;
            }

    #endif
            fwrite(input, sizeof(short), PN*aec_init.nearend_channel, fout);

        }
        ret = IaaAec_Free(handle);
        if(ret != ALGO_AEC_RET_SUCCESS)
        {
            printf("Error occured in AEC free function \n");
            return -1;
        }
        fclose(fin);
        fclose(fin_aec);
        fclose(fout);

        printf("Done\n");
    return 0;
    }

2. API REFERENCE¶

2.1. API List¶

API name	Features
IaaAec_GetBufferSize	Get the memory size required for Aec algorithm running
IaaAec_Init	Initialize the memory required for the Aec algorithm
IaaAec_Config	Configure Aec algorithm
IaaAec_Reset	Reinitialize the memory of Aec algorithm
IaaAec_Free	Release Aec algorithm resources
IaaAec_Run	Aec algorithm processing
IaaAec_GetLibVersion	Get the version information of the Aec algorithm
IaaAec_SetRecursiveRatio	Set Aec recursive ratio for adjusting converge speed.
IaaAec_ADF_Run	Run Linear Aec algorithm.
IaaAec_NLP_Run	Run Non-Linear Aec algorithm.
IaaAec_GetConfig	Get the Aec algorithm current configuration parameters.
IaaAec_GetAPIVersion	Get API version.
IaaAec_SetHandleId	Set Aec Handle Id
IaaAec_GetJsonFileSize	Get the memory size to parse the content of the Json file required by Aec algorithm
IaaAec_InitReadFromJson	Configure Json parameters to the init structure of the Aec algorithm
IaaAec_ConfigReadFromJson	Configure Json parameters to the config structure of the Aec algorithm
IaaAec_OptionReadFromJson	Configure Json parameters to the option structure of the Aec algorithm
IaaAec_SetADFBlockNum	Set Aec adf block number at different sampling rate
IaaAec_SetMode	Set Aec mode

2.2. IaaAec_GetBufferSize¶

Features

Get the memory size required for Aec algorithm running.

Syntax

unsigned int IaaAec_GetBufferSize(void);

Parameters

Parameter name Description Input/Output
Return value

Return value is the memory size required for Aec algorithm running.
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_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

None.

2.3. IaaAec_Init¶

Features

Initialize the memory required for the Aec algorithm.

Syntax

AEC_HANDLE IaaAec_Init (char* working_buffer_address, AudioAecInit * aec_init);

Parameters

Parameter Name Description Input/Output

working_buffer_address Memory address used by Aec algorithm input

aec_init Aec algorithm initialization structure pointer input
Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so / libAEC_LINUX.a
Note
- Aec algorithm only supports 8K/16K sampling rate.
Example

None.

2.4. IaaAec_Config¶

Features

Configure Aec algorithm.

Syntax

ALGO_AEC_RET IaaAec_Config(AEC_HANDLE handle, AudioAecConfig *aec_config);

Parameters

Parameter Name Description Input/Output

handle Aec algorithm handle input

aec_config Aec algorithm configuration parameter structure pointer input
Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so / libAEC_LINUX.a
Example

None.

2.5. IaaAec_Reset¶

Features

Reinitialize the memory of Aec algorithm.

Syntax

AEC_HANDLE IaaAec_Reset(char* working_buffer_address, AudioAecInit * aec_init);

Parameters

Parameter Name Description Input/Output

working_buffer_address Memory address used by Aec algorithm input

aec_init Aec algorithm initialization structure pointer input
Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Note
- Reinitialize the Aec algorithm for the same algorithm handle (same memory address) (that is, reset the sampling rate and the number of near-end and far-end channels)
- After re-initializing the Aec algorithm, it needs to be reconfigured
Example

None.

2.6. IaaAec_Free¶

Features

Release Aec algorithm resources

Syntax

ALGO_AEC_RET IaaAec_Free(AEC_HANDLE handle);

Parameters

Parameter Name Description Input/Output

handle Aec algorithm handle input
Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Note
- Must call IaaAec_Free first, and then release the memory used by the Aec algorithm.
Example

None.

2.7. IaaAec_Run¶

Features

Aec algorithm processing

Syntax

ALGO_AEC_RET IaaAec_Run(AEC_HANDLE handle, short* pss_audio_near_end, short* pss_audio_far_end);

Parameters

Parameter Name Description Input/Output

handle Algorithm handle input

pss_audio_near_end Near-end data pointer input/output

pss_audio_far_end Far-end data pointer input
Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Note
- The amount of near-end and far-end data must correspond to the point_number (the number of sampling points required for one IaaAec_Run) when calling IaaAec_Init.
- The result after AEC is output by pss_audio_near_end.
- If the input data is stereo, please arrange the left and right channel by turns.
Example
- Please refer to the Example Introduction

2.8. IaaAec_GetLibVersion¶

Features

Get the version information of the Aec algorithm.

Syntax

ALGO_AEC_RET IaaAec_GetLibVersion(unsigned short *ver_year, unsigned short *ver_date,  unsigned short *ver_time);

Parameters

Parameter Name	Description	Input/Output
ver_year	Year when Aec Algorithm Library was built	output
ver_date	Date when Aec Algorithm Library was built	output
ver_time	Date when Aec Algorithm Library was built	output

Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Note

None.
Example

None.

2.9. IaaAec_SetRecursiveRatio¶

Features

Set Aec recursive ratio for adjusting converge speed.

Syntax

ALGO_AEC_RET IaaAec_SetRecursiveRatio(AEC_HANDLE handle, unsigned int recursive_ratio);

Parameters

Parameter Name	Description	Input/Output
handle	Aec algorithm handle	input
recursive_ratio	Recursive parameter input. Larger the value, Faster the converge speed. For the scenario of switching from double talk to single talk, decrease AEC over suppress near end signal. BUT echo suppress would be more aggressive. The discontinuity of background noise become worse. Range: 1~10.	input

Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Example

None.

2.10. IaaAec_ADF_Run¶

Features

Aec linear algorithm processing

Syntax

ALGO_AEC_RET IaaAec_ADF_Run(AEC_HANDLE handle, short* pss_audio_near_end, short* pss_audio_far_end);

Parameters

Parameter Name Description Input/Output

handle Algorithm handle input

pss_audio_near_end Near-end data pointer input/output

pss_audio_far_end Far-end data pointer input
Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Note
- The amount of near-end and far-end data must correspond to thepoint_number (the number of sampling points required for one IaaAec_ADF_Run) when calling IaaAec_Init.
- The result after linear AEC is output by pss_audio_near_end.
- If the input data is stereo, please arrange the left and right channel by turns.
Example

None.

2.11. IaaAec_NLP_Run¶

Features

Aec non-linear algorithm processing

Syntax

ALGO_AEC_RET IaaAec_NLP_Run(AEC_HANDLE handle, short* pss_audio_near_end);

Parameters

Parameter Name Description Input/Output

handle Algorithm handle input

pss_audio_near_end Near-end data pointer input/output
Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Note
- The amount of near-end data must correspond to the point_number (the number of sampling points required for one IaaAec_NLP_Run) when calling IaaAec_Init.
- The result after non-linear AEC is output by pss_audio_near_end.
- If the input data is stereo, please arrange the left and right channel by turns.
Example

None.

2.12. IaaAec_GetConfig¶

Features

Get the Aec algorithm current configuration parameters.

Syntax

ALGO_AEC_RET IaaAec_GetConfig(AEC_HANDLE handle, AudioAecInit * aec_init, AudioAecConfig *aec_config);

Parameters

Parameter Name	Description	Input/Output
handle	Aec algorithm handle	Input
aec_init	Aec algorithm initialization structure pointer	Output
aec_config	The current Aec configuration parameters in the Aec algorithm	Output

Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Example

None.

2.13. IaaAec_GetAPIVersion¶

Features

Get Aec API version.

Syntax

ALGO_AEC_RET IaaAec_GetAPIVersion(unsigned short* major, unsigned short* minor);

Parameters

Parameter Name Description Input/Output

major Return version output

minor Return version output
Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Example

None.

2.14. IaaAec_SetHandleId¶

Features

Set Aec Handle Id.

Syntax

ALGO_AEC_RET IaaAec_SetHandleId(AEC_HANDLE handle, int id);

Parameters

Parameter name Description Input/Output

handle Aec algorithm handle Input

id Aec handle id
range:[0,100] Input
Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Example

None.

2.15. IaaAec_GetJsonFileSize¶

Features

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

Syntax

unsigned int IaaAec_GetJsonFileSize(char* jsonfile);

Parameters

Parameter name Description Input/Output

jsonfile Json file name Input
Return value

The return value is the memory size required to parse the Json file content.
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Example

None.

2.16. IaaAec_InitReadFromJson¶

Features

Configure Json parameters to the init structure of the Aec algorithm

Syntax

ALGO_AEC_RET IaaAec_InitReadFromJson(AudioAecInit *aec_init, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

Parameters

Parameter name	Description	Input/Output
aec_init	Configure the init structure of the Aec 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: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Example

None.

2.17. IaaAec_ConfigReadFromJson¶

Features

Configure Json parameters to the config structure of the Aec algorithm

Syntax

ALGO_AEC_RET IaaAec_ConfigReadFromJson(AudioAecConfig *aec_config, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

Parameters

Parameter name	Description	Input/Output
aec_config	Configure the config structure of the Aec 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: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Example

None.

2.18. IaaAec_OptionReadFromJson¶

Features

Configure Json parameters to the option structure of the Aec algorithm

Syntax

ALGO_AEC_RET IaaAec_OptionReadFromJson(AudioAecOption* aec_option, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

Parameters

Parameter name	Description	Input/Output
aec_option	Configure the option structure of the Aec 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: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Example

None.

2.19. IaaAec_SetADFBlockNum¶

Features

Set Aec adf block number at different sampling rate.

Syntax

ALGO_AEC_RET IaaAec_SetADFBlockNum(AEC_HANDLE handle, unsigned int block_num);

Parameters

Parameter Name	Description	Input/Output
handle	Aec algorithm handle	input
block_num	filter block number in linear Aec algorithm. Linear Acoustic Echo Cancellation (AEC) filters have specific block_num setting limits at different sampling rates: the maximum is 8 for 8kHz/16kHz, 16 for 32kHz, and 24 for 48kHz. These limits depend on whether the algorithm library supports an increased number of linear AEC filters.	input

Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Example

None.

2.20. IaaAec_SetMode¶

Features

Set Aec Mode.

Syntax

ALGO_AEC_RET IaaAec_SetMode(AEC_HANDLE handle, unsigned int mode);

Parameters

Parameter Name	Description	Input/Output
handle	Aec algorithm handle	input
mode	Different AEC Mode. Mode 0 as default traditional AEC algorithm. Mode 1 combine with NN-based non-linear process.	input

Return value

Return value Result

0 Successful

Non-zero Failed, refer to error code
Dependency
- Header: AudioAecProcess.h
- Library: libAEC_LINUX.so/ libAEC_LINUX.a
Note

Mode 1 only support 16k sampling rate.
Example

None.

3. AEC DATA TYPE¶

3.1. AEC data type list¶

The AEC module related data types are defined as follows:

DATA TYPE	Description
AudioAecInit	The initialization parameter structure of the Aec algorithm
AudioAecConfig	the configuration parameter structure of the Aec algorithm
IAA_AEC_SAMPLE_RATE	Aec algorithm supported sampling rate type
IAA_AEC_BOOL	The Boolean type used internally in the Aec algorithm
AEC_HANDLE	The handle type of the Aec algorithm
AudioAecOption	Aec option parameter structure type

3.2. AudioAecInit¶

Description

Define the initialization parameter structure of the Aec algorithm.

Definition

typedef struct

{

    unsigned int point_number;

    unsigned int nearend_channel;

    unsigned int farend_channel;

    IAA_AEC_SAMPLE_RATE sample_rate;

}AudioAecInit;

Member

Member name	Description
point_number	The number of sampling points processed by the Aec algorithm once. The default value is 128. User can use following command to check `strings libAEC_LINUX.a \| grep ALGO`
nearend_channel	The near-end channel number ( the microphone channel number). User can set mono or stereo. Range: [1, 2]
farend_channel	The far-end channel number (the speaker channel number). User can set mono or stereo. Range: [1, 2]
sample_rate	Sampling rate processed by Aec algorithm

Note
- If the input data is stereo, User need to intersect the left and right channels. For example, L/R/L/R/...
- The length of near-end data that IaaAec_Run need is $point_number \times nearend_channel \times 2 $ bytes
- The length of far-end data that IaaAec_Run need is $point_number \times farend_channel \times 2 $ bytes
- If user set near end channel as stereo, AEC would average two channel data, and then process these average data and duplicate to both channel. If user need two channel process separately, please initialize two handle for independent mono process.
Related data types and interfaces

IaaAec_Init

IaaAec_Reset

IaaAec_InitReadFromJson

3.3. AudioAecConfig¶

Description

Define the configuration parameter structure of the Aec algorithm

Definition

typedef struct

{

    IAA_AEC_BOOL comfort_noise_enable;

    short delay_sample;

    unsigned int suppression_mode_freq[6];

    unsigned int suppression_mode_intensity[7];

}AudioAecConfig;

Member

Member name	Description
comfort_noise_enable	Add comfort noise after AEC to avoid the muting part of the paragraph after echo cancellation, which makes users feel disconnected. If noise reduction is turned on after AEC, it is recommended to turn on comfort noise to help NR converge noise.
delay_sample	Echo delay samples between left and right channels When Stereo cost down is turned on, you can set the sample delay number according to the relative position of the microphone, reducing the amount of calculation required for the dual-channel. Default value : 0 Unit : the number of samples Value ranges: -9-9
suppression_mode_freq	The frequency band division of AEC processing divides the highest frequency that can be resolved by different sampling rates into 128 equal parts. Setting six values, which can cut out seven segments to set different AEC intensities. Value ranges: 0-128
suppression_mode_intensity	Set seven intensities respectively in the seven paragraphs cut by the suppression_mode_freq. Value ranges: 0-25

Note
- comfort_noise_enable
  
  After enabling the parameter, the AEC algorithm will add some comfort noise when there is no sound. This function can be enabled when you require a stable noise floor or when AEC is too clean that causes the NR convergence time is too long.
- delay_sample
  
  Due to the placement of the microphone and the speaker, the distance between the microphones, etc., the time points when the left and right channels receive the echo are not consistent, and the echo delay between the two channels is different.
  
  This value indicates how many sampling points the left channel receives the echo earlier than the right channel. You can adjust this value to align the left and right channel data. When setting, please use the left channel as a reference. For example, the echo of the left channel is 4 samples faster than the right, s16DelaySample is set to 4, otherwise it is set to -4.
- suppression_mode_freq
  
  This array divides the highest frequency of the current sampling rate into 7 frequency bands for processing. The following is the conversion formula of array elements and frequency range:
  
  $residual\ Echo\ Frequency\ Range/(sampleRate/2) \times pointNumber(128)$
  
  The array requires that each element must be greater than the previous element.
- suppression_mode_intensity
  
  This array represents the echo cancellation intensity of each frequency band, and each element corresponds to the 7 frequency bands divided by u32AecSupfreq. The greater the intensity, the more details are eliminated and the more unnatural the sound.
Related data types and interfaces

IaaAec_Config

IaaAec_GetConfig

IaaAec_ConfigReadFromJson

3.4. IAA_AEC_SAMPLE_RATE¶

Description

AEC algorithm supported sampling rate type.

Definition

typedef enum

{

    IAA_AEC_SAMPLE_RATE_8000 = 8000 ,

    IAA_AEC_SAMPLE_RATE_16000 = 16000 ,

    IAA_AEC_SAMPLE_RATE_32000 = 32000 ,

    IAA_AEC_SAMPLE_RATE_48000 = 48000 ,

}IAA_AEC_SAMPLE_RATE;

Member

Member name	Description
IAA_AEC_SAMPLE_RATE_8000	8K sampling rate
IAA_AEC_SAMPLE_RATE_16000	16K sampling rate
IAA_AEC_SAMPLE_RATE_32000	32K sampling rate
IAA_AEC_SAMPLE_RATE_48000	48K sampling rate

Note

Mode 1 only support 16K sampling rate.
Related data types and interfaces

AudioAecInit

3.5. IAA_AEC_BOOL¶

Description

Define the Boolean type used internally in the Aec algorithm.

Definition

typedef enum

{

    IAA_AEC_TRUE = 1,

    IAA_AEC_FALSE = 0,

}IAA_AEC_BOOL;

Member

Member name Description

IAA_AEC_TRUE True

IAA_AEC_FALSE False
Note

None
Related data types and interfaces

AudioAecConfig

3.6. AEC_HANDLE¶

Description

Define the handle type of the Aec algorithm.
Definition
```
typedef void* AEC_HANDLE;
```
Parameters

Parameter name Description Input/Output
Note

None.
Related data types and interfaces

IaaAec_Init

IaaAec_Config

IaaAec_Reset

IaaAec_Free

IaaAec_Run

IaaAec_SetRecursiveRatio

IaaAec_ADF_Run

IaaAec_NLP_Run

IaaAec_GetConfig

IaaAec_SetHandleId

3.7. AudioAecOption¶

Description

Define the option parameter structure of the Aec algorithm.

Definition

typedef struct

{

    unsigned int recursive_ratio;

    unsigned int block_num;

    unsigned int mode;

}AudioAecOption;

Member

Member name Description

recursive_ratio Please refer to IaaAec_SetRecursiveRatio

block_num Please refer to IaaAec_SetADFBlockNum

mode Please refer to IaaAec_SetMode
Note

None
Related data types and interfaces

IaaAec_OptionReadFromJson

4. ERROR CODE¶

AEC API error codes are shown as follow:

Error code	Definition	Description
0x00000000	ALGO_AEC_RET_SUCCESS	AEC runs successfully
0x10000401	ALGO_AEC_RET_INIT_ERROR	AEC isn`t initialized
0x10000402	ALGO_AEC_RET_INVALID_HANDLE	HANDLE is invalid
0x10000403	ALGO_AEC_RET_INVALID_SAMPLE_RATE	Sampling frequency doesn`t support
0x10000404	ALGO_AEC_RET_INVALID_POINT_NUMBER	Points per frame doesn`t support
0x10000405	ALGO_AEC_RET_INVALID_CHANNEL	Channel number doesn`t support
0x10000406	ALGO_AEC_RET_INVALID_ENABLE	Invalid calling api
0x10000407	ALGO_AEC_RET_INVALID_SUP_BAND	AEC rejection band parameter setting is invalid
0x10000408	ALGO_AEC_RET_INVALID_SUP_MODE	AEC rejection intensity parameter setting is invalid
0x10000409	ALGO_AEC_RET_INVALID_COMFORT_NOISE	AEC comfort noise parameter setting is invalid
0x10000410	ALGO_AEC_RET_INVALID_DELAY_SAMPLE	AEC delay sample number setting is invalid
0x10000411	ALGO_AEC_RET_INVALID_RECURSIVE_RATIO	AEC recursive ratio is invalid
0x10000412	ALGO_AEC_RET_API_CONFLICT	Other APIs are running
0x10000413	ALGO_AEC_RET_INVALID_CALLING	Incorrect order of calling API
0x10000414	ALGO_AEC_RET_INVALID_JSONFILE	AEC fails to read json file

Parameter Name	Description	Input/Output
working_buffer_address	Memory address used by Aec algorithm	input
aec_init	Aec algorithm initialization structure pointer	input

Parameter Name	Description	Input/Output
handle	Algorithm handle	input
pss_audio_near_end	Near-end data pointer	input/output
pss_audio_far_end	Far-end data pointer	input

Member name	Description
recursive_ratio	Please refer to IaaAec_SetRecursiveRatio
block_num	Please refer to IaaAec_SetADFBlockNum
mode	Please refer to IaaAec_SetMode

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

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