SGS DH ALGORITHM USER GUIDE¶

REVISION HISTORY¶

Revision No.	Description	Date
0.1	Initial release	11/09/2020
1.0	Revised Config	06/01/2021
1.1	Independent from MI, add error code	09/14/2021
1.2	Add function IaaDh_GetAPIVersion	02/27/2024
1.3	Add function IaaDh_SetLatency	12/09/2024
1.31	Add Json API description	01/03/2025
1.32	Update file description and copyright	04/25/2025
1.33	Remove copyright	05/14/2025
1.34	Revised description of IaaDh_Run	08/06/2025
1.35	Corrected format	10/28/2025

1. OVERVIEW¶

1.1. Algorithm Description¶

De-Howling (DH) function is created to suppress howling, a phenomenon commonly found in sound amplification system. When microphone and speaker are placed in the same venue and the sound is amplified by the speaker, microphone will pick up the amplified sound, forming a sound feedback loop. When the gain of amplification is strong enough, self-excited oscillation will occur at certain frequency band, resulting in harsh howling.

1.2. Keyword Description¶

1.2.1. PTPR (Peak-to-Threshold Power Ratio)¶

Peak-to-Threshold Power Ratio. It is one of the criteria for howling detection. The smaller the value is set, the easier it is to be detected as howling frequency band.

1.2.2. PAPR (Peak-to-Average Power Ratio)¶

Peak-to-Average Power Raio. It is one of the criteria for howling detection. The smaller the value is set, the easier it is to be detected as howling frequency band.

1.2.3. PHPR (Peak-to-Harmonics Power Ratio)¶

Peak-to-Harmonics Power Raio. It is one of the criteria for howling detection. The smaller the value is set, the easier it is to be detected as howling frequency band.

2. API Description¶

API Name	Function
IaaDh_GetBufferSize	Get the memory size required to run Dh algorithm.
IaaDh_Init	Initialize Dh algorithm.
IaaDh_Config	Configure Dh algorithm.
IaaDh_GetConfig	Get the current parameter configuration information of Dh algorithm.
IaaDh_Run	Run Dh algorithm.
IaaDh_Reset	Re-initialize Dh algorithm.
IaaDh_Free	Release resources from Dh algorithm.
IaaDh_GetAPIVersion	Return current DH API version.
IaaDh_SetLatency	Enable latnecy estimation system and set latnecy time (ms)
IaaDh_GetJsonFileSize	DH get size of json file
IaaDh_InitReadFromJson	Set json parameter into DH init structure
IaaDh_ConfigReadFromJson	Set json parameter into DH config structure

2.1. IaaDh_GetBufferSize¶

Function

Get the memory size required to run Dh algorithm.

Syntax

unsigned int IaaDh_GetBufferSize(void);

Parameter

Parameter Name Description Input/Output

N/A
Return Value

The return value is the memory size required to run the Dh algorithm.
Dependency
- Header File: AudioDhProcess.h
- Library: libDH_LINUX.so/ libDH_LINUX.a
Note

This interface only returns the required memory size. Actions such as the application for memory as well as its release should be done by application.
Example

Please refer to the Example section of IaaDh_Run.

2.2. IaaDh_Init¶

Function

Initialize Dh algorithm.

Syntax

DH_HANDLE IaaDh_Init(char* working_buffer_address, AudioDhInit *dh_init);

Parameter

Parameter Name Description Input/Output

working_buffer The address of memory used by Dh algorithm. Input.

dh_init Pointer to the initialization structure of Dh algorithm. Input.
Return Value

Return value Result

Not NULL Successful

NULL Failed
Dependency
- Header File: AudioDhProcess.h
- Library: libDH_LINUX.so/ libDH_LINUX.a
Note

N/A.
Example

Please refer to the Example section of IaaDh_Run.

2.3. IaaDh_Config¶

Function

Configure Dh algorithm.

Syntax

ALGO_DH_RET IaaDh_Config(DH_HANDLE handle, AudioDhConfig *dh_config);

Parameter

Parameter Name Description Input/Output

handle Handle of Dh algorithm. Input.

dh_config Pointer to the configuration structure of Dh algorithm. Input.
Return Value

Return value Result

0 Successful

Non-zero Failed, refer to Error code
Dependency
- Header File: AudioDhProcess.h
- Library: libDH_LINUX.so/ libDH_LINUX.a
Note

N/A.
Example

Please refer to the Example section of IaaDh_Run.

2.4. IaaDh_GetConfig¶

Function

Get the current parameter configuration information of Dh algorithm.

Syntax

ALGO_DH_RET IaaDh_GetConfig(DH_HANDLE handle, AudioDhInit *dh_init, AudioDhConfig *dh_config);

Parameter

Parameter Name Description Input/Output

handle Handle of Dh algorithm. Input.

dh_config Pointer to the configuration structure of Dh algorithm. Output.
Return Value

Return value Result

0 Successful

Non-zero Failed, refer to Error code
Dependency
- Header File: AudioDhProcess.h
- Library: libDH_LINUX.so/ libDH_LINUX.a
Note

N/A.
Example

N/A.

2.5. IaaDh_Run¶

Function

Run Dh algorithm.

Syntax

ALGO_DH_RET IaaDh_Run(DH_HANDLE handle, unsigned char* lower_vol, short* pss_audio_in);

Parameter

Parameter Name	Description	Input/Output
handle	Handle of Dh algorithm.	Input.
lower_vol	The default value of this value is 0, which means no volume adjustment is required. When this value changes to 1, it means that the howling frequency band exceeds the set value, and the volume must be turned down to reduce howling. When this value changes to 2, it means that the howling situation has been stabilized and the volume can be adjusted back.	Output.
pss_audio_in	Pointer to the data pending to undergo howling suppression.	Input.

Return Value

Return value Result

0 Successful

Non-zero Failed, refer to Error code
Dependency
- Header File: AudioDhProcess.h
- Library: libDH_LINUX.so/ libDH_LINUX.a
Note

N/A.

Example

 1. int count = 0;
2.    fread(input, sizeof(char), 44, fin); // read header 44 bytes
3.    while(fread(input, sizeof(short), dh_init.point_number*dh_init.channel, fin))
4.#include <stdio.h>
5.#include <string.h>
6.#include <stdlib.h>
7.
8.#include "AudioDhProcess.h"
9.
10.
11.int main(int argc, char *argv[])
12.{
13.    /*********Input file init*******/
14.    short input[1024];
15.    unsigned int T0, T1;
16.    float avg = 0;
17.    FILE * fin, * fout;
18.    char input_file[512];
19.    char output_file[512];
20.    unsigned char lower_vol = 0;
21.    int PN=128;
22.    int ret1;
23.
24.    /*******DH data init*********/
25.    int Buffer_size = IaaDh_GetBufferSize();
26.    char *working_buf_ptr = (char*)malloc(Buffer_size);
27.    AudioDhInit dh_init;
28.    AudioDhConfig dh_config;
29.    DH_HANDLE handle;
30.
31.    /****User change section start****/
32.    dh_init.point_number = PN;
33.    dh_init.channel = 1;
34.    dh_init.sample_rate = IAA_DH_SAMPLE_RATE_8000;
35.
36.    handle = IaaDh_Init((char *)working_buf_ptr, &dh_init);
37.    if(handle==NULL)
38.    {
39.        printf("DH init error\r\n");
40.        return -1;
41.    }
42.    else
43.    {
44.        printf("DH init succeed\r\n");
45.    }
46.
47.    dh_config.dh_enable = 1;
48.    dh_config.lower_freq = 400;
49.    dh_config.PTPR_thres = 0;
50.    dh_config.PAPR_thres = 10;
51.    dh_config.PHPR_thres = 20;
52.    dh_config.suppression_thres = 5;
53.    dh_config.supbins = 25;
54.    dh_config.excess_supbins_time = 240;
55.    dh_config.within_supbins_time = 800;
56.
57.    if(IaaDh_Config(handle, &dh_config) != 0)
58.    {
59.        printf("Config Error!");
60.        return -1;
61.    }
62.
63.    sprintf(input_file,"%s","./../sample/data/DH_AFE_8K.wav");
64.    sprintf(output_file,"%s","./../sample/data/DH_out_8K.wav");
65.
66.    fin = fopen(input_file, "rb");
67.    if(!fin)
68.    {
69.        printf("the input file %s could not be open\n",input_file);
70.        return -1;
71.    }
72.
73.    fout = fopen(output_file, "wb");
74.    if(!fout)
75.    {
76.        printf("the output file could not be open\n");
77.        return -1;
78.    }
79.
80.    fread(input, sizeof(char), 44, fin); // read header 44 bytes
81.    fwrite(input, sizeof(char),44, fout); // write 44 bytes output
82.
83.    while(fread(input, sizeof(short), dh_init.point_number*dh_init.channel, fin))
84.    {
85.
86.        ret1 = IaaDh_Run(handle,&lower_vol,input);
87.
88.        if(ret1 != 0)
89.        {
90.            printf("Error occured in De-Howling\n");
91.            break;
92.        }
93.
94.        fwrite(input, sizeof(short), dh_init.point_number*dh_init.channel, fout);
95.    }
96.
97.    IaaDh_Free(handle);
98.    free(working_buf_ptr);
99.    fclose(fin);
100.  fclose(fout);
101.  printf("Done\n");
102.
103.  return 0;
104.}

2.6. IaaDh_Reset¶

Function

Re-initialize Dh algorithm.

Syntax

DH_HANDLE IaaDh_Reset(char* working_buffer_address, AudioDhInit *dh_init);

Parameter

Parameter Name Description Input/Output

working_buffer The address of memory used by Dh algorithm. Input.

dh_init Pointer to the initialization structure of Dh algorithm. Input.
Return Value

Return value Result

Not NULL Successful

NULL Failed
Dependency
- Header File: AudioDhProcess.h
- Library: libDH_LINUX.so/ libDH_LINUX.a
Note

N/A.
Example

N/A.

2.7. IaaDh_Free¶

Function

Release resources from Dh algorithm.

Syntax

ALGO_DH_RET IaaDh_Free(DH_HANDLE handle);

Parameter

Parameter Name Description Input/Output

handle Handle of Dh algorithm. Input.
Return Value

Return value Result

0 Successful

Non-zero Failed, refer to Error code
Dependency
- Header File: AudioDhProcess.h
- Library: libDH_LINUX.so/ libDH_LINUX.a
Note

N/A.
Example

Please refer to the Example section of IaaDh_Run.

2.8. IaaDh_GetAPIVersion¶

Function

Return current DH API version

Syntax

ALGO_DH_RET IaaDh_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: AudioDhProcess.h
- Library: libDH_LINUX.so/ libDH_LINUX.a

2.9. IaaDh_SetLatency¶

Function

Enable latnecy estimation system and set latnecy time (ms)

Syntax

ALGO_DH_RET IaaDh_SetLatency(DH_HANDLE handle, int latency_ms);

Parameters

Parameter Name Description Input/Output

handle Handle of Dh algorithm. input

latency_ms Howling loop delay time input
Return value

Return value Result

0 Successful

Non-zero Failed, refer to Error code
Dependency
- Header: AudioDhProcess.h
- Library: libDH_LINUX.so/ libDH_LINUX.a
Note

User have to call this function for enabling latency estimation system. This system is independant from frequency feature determined system.

2.10. IaaDh_GetJsonFileSize¶

Function

DH get size of json file

Syntax

unsigned int IaaDh_GetJsonFileSize(char* jsonfile);

Parameter

Parameter name Description Input/Output

jsonfile name of json file Input
Return Value

Return value is the memory size required for decoding json file.
Dependency
- Header file: AudioDhProcess.h
- Library file: libDH_LINUX.so/ libDH_LINUX.a
Note

N/A

2.11. IaaDh_InitReadFromJson¶

Function

Set json parameter into DH init structure

Syntax

ALGO_DH_RET IaaDh_InitReadFromJson(AudioDhInit* dh_init, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

Parameter

Parameter name Description Input/Output

dh_init DH algorithm Init Input

jsonBuffer json buffer memory address Input

jsonfile name of json file Input

buffSize size of json file Input
Return Value

Return Value Result

0 Successful

Non-zero Failed, refer to Error code
Dependency
- Header file: AudioDhProcess.h
- Library file: libDH_LINUX.so/ libDH_LINUX.a
Note

N/A

2.12. IaaDh_ConfigReadFromJson¶

Function

Set json parameter into DH config structure

Syntax

ALGO_DH_RET IaaDh_ConfigReadFromJson(AudioDhConfig* dh_config, char* jsonBuffer, char* jsonfile, unsigned int buffSize);

Parameter

Parameter name	Description	Input/Output
dh_config	DH algorithm Config	Input
jsonBuffer	json buffer memory address	Input
jsonfile	name of json file	Input
buffSize	size of json file	Input

Return Value

Return Value Result

0 Successful

Non-zero Failed, refer to Error code
Dependency
- Header file: AudioDhProcess.h
- Library file: libDH_LINUX.so/ libDH_LINUX.a
Note

N/A

3. DH Data Type¶

Definition of data type in DH module is listed in the following table:

Data Type	Definition
IAA_DH_SAMPLE_RATE	The type of DH algorithm sampling rate.
AudioDhInit	The type of Dh algorithm initialization parameter structure.
AudioDhConfig	The type of Dh algorithm configuration parameter structure.
DH_HANDLE	The type of Dh algorithm handle.

3.1. IAA_DH_SAMPLE_RATE¶

Description

Define the type of DH algorithm sampling rate.

Definition

typedef enum

{

    IAA_DH_SAMPLE_RATE_8000 = 8000 ,

    IAA_DH_SAMPLE_RATE_16000 = 16000 ,

    IAA_DH_SAMPLE_RATE_48000 = 48000 ,

}IAA_DH_SAMPLE_RATE;

Member

Member name Description

IAA_DH_SAMPLE_RATE_8000 Sampling rate at 8000Hz.

IAA_DH_SAMPLE_RATE_16000 Sampling rate at 16000Hz.

IAA_DH_SAMPLE_RATE_48000 Sampling rate at 48000Hz.
Note

N/A.
Related Data Type and Interface

AudioDhInit

3.2. AudioDhInit¶

Description

Define the type of Dh algorithm initialization parameter structure.

Definition

typedef struct

{

    unsigned int point_number;

    unsigned int channel;

    IAA_DH_SAMPLE_RATE sample_rate;

}AudioDhInit;

Member

Member name	Description
point_number	The number of sampling points processed by Dh algorithm once.
channel	Number of channels.
sample_rate	Sampling rate, which currently supports 8k/16k/48k.

Note

N/A.
Related Data Type and Interface

IaaDh_Init

IaaDh_GetConfig

IaaDh_Reset

IaaDh_InitReadFromJson

3.3. AudioDhConfig¶

Description

Define the type of Dh algorithm configuration parameter structure.

Definition

typedef struct

{

    unsigned int dh_enable;

    unsigned int lower_freq;

    int PTPR_thres;

    int PAPR_thres;

    int PHPR_thres;

    int suppression_thres;

    int supbins;

    int excess_supbins_time;

    int within_supbins_time;

}AudioDhConfig;

Member

Member name	Description
dh_enable	Whether to enable DH algorithm.
lower_freq	The lowest suppressed frequency (Hz), that is, do not suppress the frequency below this value. The range is [0,(sample_rate/2)], the recommended value is 1200, and the step size is 1.
PTPR_thres	The threshold value of PTPR (dB). Peak-to-Threshold Power Ratio is one of the criteria for howling detection. The smaller the value is set, the easier it is to be detected as howling frequency band. The range is [0,80], the recommended value is 0, and the step size is 1.
PAPR_thres	The threshold value of PAPR (dB). Peak-to-Average Power Ratio is one of the criteria for howling detection. The smaller the value is set, the easier it is to be detected as howling frequency band. The range is [0,80], the recommended value is 10, and the step size is 1.
PHPR_thres	The threshold value of PHPR (dB). Peak-to-Harmonics Power Raio is one of the criteria for howling detection. The smaller the value is set, the easier it is to be detected as howling frequency band. The range is [0,80], the recommended value is 20, and the step size is 1.
suppression_thres	Total suppression threshold (%), which calculates the percentage of frequency bands detected as howling in a specific surrounding range to the total range. If the percentage exceeds this set value, the surrounding range will also be suppressed. If this value is set smaller, the degree of suppression around the howling frequency band will be stronger. The range is [0,100], the recommended value is 5, and the step size is 1.
supbins	The total number of suppressed frequency bands in the current frame (%). If the percentage of the suppressed frequency bands in the current frame to the total frequency band exceeds this setting value, the current frame will be included as an excessive howling frame. The smaller this value is set, the easier the current frame will be judged as an excessive howling frame. The range is [0,100], the recommended value is 25, and the step size is 1.
excess_supbins_time	Threshold value of excessive howling frame duration (ms). If the continuous time of excessive howling frames exceeds this setting value, the volume must be turned down to achieve better results. The range is [0,1600], the recommended value is 240, and the step size is 1.
within_supbins_time	Threshold value of non-excessive howling frame duration (ms). After the volume is turned down, you should calculate the duration of non-excessive howling frame. If the duration exceeds this setting value, the volume can be adjusted back. The range is [0,8000], the recommended value is 800, and the step size is 1.

Note

N/A.
Related Data Type and Interface

IaaDh_Config

IaaDh_GetConfig

IaaDh_ConfigReadFromJson

3.4. DH_HANDLE¶

Description

Define the type of Dh algorithm handle.
Definition

typedef void* DH_HANDLE;
Member

Member name Description

N/A
Note

N/A.
Related Data Type and Interface

IaaDh_Init

IaaDh_Config

IaaDh_GetConfig

IaaDh_Run

IaaDh_Reset

IaaDh_Free

4. Error code¶

DH API Error Code are set out as the following table shows.

Error code	Definition	Description
0x00000000	ALGO_DH_RET_SUCCESS	DH is run successfully.
0x10000701	ALGO_DH_RET_INVALID_CONFIG	Invalid DH Config.
0x10000702	ALGO_DH_RET_INVALID_HANDLE	Invalid DH Handle.
0x10000703	ALGO_DH_RET_INVALID_SAMPLERATE	Invalid DH sampling rate.
0x10000704	ALGO_DH_RET_INVALID_POINTNUMBER	Invalid DH sampling point number.
0x10000705	ALGO_DH_RET_INVALID_CHANNEL	Invalid DH channel number.
0x10000706	ALGO_DH_RET_INVALID_ENABLE	Invalid DH ENABLE.
0x10000707	ALGO_DH_RET_INVALID_LOWERFREQ	Invalid LOWERFREQ setting.
0x10000708	ALGO_DH_RET_INVALID_PTPR	Invalid PTPR setting.
0x10000709	ALGO_DH_RET_INVALID_PAPR	Invalid PAPR setting.
0x10000710	ALGO_DH_RET_INVALID_PHPR	Invalid PHPR setting.
0x10000711	ALGO_DH_RET_INVALID_SUPTHRESHLOD	Invalid SUPTHRESHLOD setting.
0x10000712	ALGO_DH_RET_INVALID_SUPBINS	Invalid SUPBINS setting.
0x10000713	ALGO_DH_RET_INVALID_EXCESS_SUPBINS_TIME	Invalid EXCESS_SUPBINS_TIME setting.
0x10000714	ALGO_DH_RET_INVALID_WITHIN_SUPBINS_TIME	Invalid WITHIN_SUPBINS_TIME setting.
0x10000715	ALGO_DH_RET_INVALID_CALLING	Invalid sequence of API called by DH.
0x10000716	ALGO_DH_RET_API_CONFLICT	There are other APIs running.
0x10000717	ALGO_DH_RET_FAILED	Wrong parameter setting.

Parameter Name	Description	Input/Output
working_buffer	The address of memory used by Dh algorithm.	Input.
dh_init	Pointer to the initialization structure of Dh algorithm.	Input.

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

Parameter name	Description	Input/Output
dh_init	DH algorithm Init	Input
jsonBuffer	json buffer memory address	Input
jsonfile	name of json file	Input
buffSize	size of json file	Input

Member name	Description
IAA_DH_SAMPLE_RATE_8000	Sampling rate at 8000Hz.
IAA_DH_SAMPLE_RATE_16000	Sampling rate at 16000Hz.
IAA_DH_SAMPLE_RATE_48000	Sampling rate at 48000Hz.

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