SGS DH 算法使用参考¶

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. 概述¶

1.1. 算法说明¶

DH(Dehowling)啸叫抑制，是一种抑制啸叫的功能。啸叫常见于扩音系统，当麦克风和扬声器在同一个会场时，声音从扬声器扩音后又从被麦克风拾取，形成了声音反馈回路。当扩音的增益足够大，在某些频率就会产生自激振荡，形成刺耳的啸叫。

1.2. 关键词说明¶

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

峰值阈值功率比，为啸叫侦测标准之一，若此值越小，则越容易被判断为啸叫频带。

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

峰值均值功率比，为啸叫侦测标准之一，若此值越小，则越容易被判断为啸叫频带。

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

峰值谐波功率比, 为啸叫侦测标准之一，若此值越小，则越容易被判断为啸叫频带。

2. API 参考¶

API名	功能
IaaDh_GetBufferSize	获取Dh算法运行需要的内存大小
IaaDh_Init	初始化Dh算法
IaaDh_Config	配置Dh算法
IaaDh_GetConfig	获取Dh算法当前的配置参数信息
IaaDh_Run	Dh算法处理
IaaDh_Reset	重新初始化Dh算法
IaaDh_Free	释放Dh算法资源
IaaDh_GetAPIVersion	返回当前Dh算法版号
IaaDh_SetLatency	设定延迟估计判断系统的延迟时间
IaaDh_GetJsonFileSize	DH获取解析Json文件内容所需要的内存大小
IaaDh_InitReadFromJson	配置Json参数到DH算法的初始化结构体指针
IaaDh_ConfigReadFromJson	配置Json参数到DH算法的参数结构体指针

2.1. IaaDh_GetBufferSize¶

功能

获取Dh算法运行所需要的内存大小。

语法

unsigned int IaaDh_GetBufferSize(void);

形参

参数名称描述输入/输出

N/A
返回值

返回值为Dh算法运行所需要的内存大小
依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a
注意

该接口仅返回需要的内存大小，申请和释放内存的动作需应用来处理。
举例

请参考IaaDh_Run举例部分。

2.2. IaaDh_Init¶

功能

初始化Dh算法。

语法

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

形参

参数名称描述输入/输出

working_buffer Dh算法所使用的内存地址输入

dh_init Dh算法的初始化结构体指针输入
返回值

返回值结果

非NULL 成功

NULL 失败
依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a
注意

无。
举例

请参考IaaDh_Run举例部分。

2.3. IaaDh_Config¶

功能

配置Dh算法。
语法

ALGO_DH_RET IaaDh_Config(DH_HANDLE handle, AudioDhConfig *dh_config);
形参

参数名称描述输入/输出

handle Dh算法handle 输入

dh_config Dh算法的配置结构体指针输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a
注意

无。
举例

请参考IaaDh_Run举例部分。

2.4. IaaDh_GetConfig¶

功能

获取Dh算法当前的配置参数。

语法

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

形参

参数名称描述输入/输出

handle Dh算法handle 输入

dh_init Dh算法的初始化结构体指针输出

dh_config Dh算法的配置结构体指针输出
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a
注意

无。
举例

无。

2.5. IaaDh_Run¶

功能

DH算法处理

语法

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

形参

参数名称	描述	输入/输出
handle	Dh算法handle	输入
lower_vol	此值默认值为0，代表不需调整音量。当此值转变为1时，表示啸叫频带超过设定值，须将音量调小，改善啸叫情况。当此值转为2时，表示啸叫情况已稳定，可将音量调回。	输出
pss_audio_in	待进行啸叫抑制的数据指针	输入

返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a
注意

无

举例

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¶

功能

重新初始化Dh算法。

语法

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

形参

参数名称描述输入/输出

working_buffer Dh算法运行的内存地址输入

dh_init Dh算法的初始化参数结构体指针输入
返回值

返回值结果

非NULL 成功

NULL 失败
依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a
注意

无。
举例

无。

2.7. IaaDh_Free¶

功能

释放Dh算法资源

语法

ALGO_DH_RET IaaDh_Free(DH_HANDLE handle);

形参

参数名称描述输入/输出

handle Dh算法handle 输入
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a
注意

无。
举例

请参考IaaDh_Run举例部分。

2.8. IaaDh_GetAPIVersion¶

功能

返回当前Dh算法版号

语法

ALGO_DH_RET IaaDh_GetAPIVersion(unsigned short* major, unsigned short* minor);

形参

参数名称描述输入/输出

major 主板号输入/输出

minor 副版号输入/输出
返回值

返回值结果

0 成功

非0 失败，参照错误码
依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a

2.9. IaaDh_SetLatency¶

功能

设定延迟估计判断系统的延迟时间

语法

ALGO_DH_RET IaaDh_SetLatency(DH_HANDLE handle, int latency_ms);

形参

参数名称描述输入/输出

handle Dh算法handle 输入

latency_ms 啸叫循环延迟时间输入
返回值

返回值结果

0 成功

非0 失败，参照错误码

- 依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a
注意

必须设定此条API才能启动延迟估计啸叫侦测，此套侦测系统独立于原本的频率判断方式

2.10. IaaDh_GetJsonFileSize¶

功能

DH获取解析Json文件内容所需要的内存大小

语法

unsigned int IaaDh_GetJsonFileSize(char* jsonfile);

形参

参数名称描述输入/输出

jsonfile Json檔名输入
返回值

返回值为解析Json文件内容所需要的内存大小
依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a
注意

无。

2.11. IaaDh_InitReadFromJson¶

功能

配置Json参数到DH算法的初始化结构体指针

语法

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

形参

参数名称	描述	输入/输出
dh_init	DH算法Init	输入
jsonBuffer	解析Json文件内容所使用的内存地址	输入
jsonfile	Json檔名	输入
buffSize	解析Json文件内容所需要的内存大小	输入

返回值

返回值结果

0 成功

非0 失败，参考错误码
依赖
- 头文件: AudioDhProcess.h
- 库文件:libDH_LINUX.so/ libDH_LINUX.a
注意

无。

2.12. IaaDh_ConfigReadFromJson¶

功能

配置Json参数到DH算法的参数结构体指针

语法

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

形参

参数名称	描述	输入/输出
dh_config	DH算法Config	输入
jsonBuffer	解析Json文件内容所使用的内存地址	输入
jsonfile	Json檔名	输入
buffSize	解析Json文件内容所需要的内存大小	输入

返回值

返回值结果

0 成功

非0 失败，参考错误码
依赖
- 头文件: AudioDhProcess.h
- 库文件: libDH_LINUX.so/ libDH_LINUX.a
注意

无。

3. DH 数据类型¶

DH模块相关数据类型定义如下：

数据类型	定义
IAA_DH_SAMPLE_RATE	DH算法的测采样率类型
AudioDhInit	Dh算法初始化参数结构体类型
AudioDhConfig	Dh算法配置参数结构体类型
DH_HANDLE	Dh算法句柄类型

3.1. IAA_DH_SAMPLE_RATE¶

说明

定义DH算法的测采样率类型。

定义

typedef enum

{

    IAA_DH_SAMPLE_RATE_8000 = 8000 ,

    IAA_DH_SAMPLE_RATE_16000 = 16000 ,

    IAA_DH_SAMPLE_RATE_48000 = 48000 ,

}IAA_DH_SAMPLE_RATE;

成员

成员名称描述

IAA_DH_SAMPLE_RATE_8000 采样率8000Hz

IAA_DH_SAMPLE_RATE_16000 采样率16000Hz

IAA_DH_SAMPLE_RATE_48000 采样率48000Hz
注意事项

无
相关数据类型及接口

AudioDhInit

3.2. AudioDhInit¶

说明

定义Dh算法的初始化参数类型。

定义

typedef struct

{

    unsigned int point_number;

    unsigned int channel;

    IAA_DH_SAMPLE_RATE sample_rate;

}AudioDhInit;

成员

成员名称描述

point_number Dh算法处理一次的采样点数

channel 通道数

sample_rate 采样率，目前支持8k/16k/48k
注意

无。
相关数据类型及接口

IaaDh_Init

IaaDh_GetConfig

IaaDh_Reset

IaaDh_InitReadFromJson

3.3. AudioDhConfig¶

说明

定义DH算法的配置参数结构体类型。

定义

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;

成员

成员名称	描述
dh_enable	是否开启DH算法
lower_freq	最低压抑的频率(Hz)，即为此值设定的频率以下不要压抑。范围为[0,(sample_rate/2)]，建议值为1200，步长为1
PTPR_thres	PTPR阀值(dB)，峰值阈值功率比，为判断标准之一，若此值越小，则越容易被判断为啸叫频带。范围为[0,80] ，建议值为0，步长为1
PAPR_thres	PAPR阀值(dB)，峰值均值功率比，为判断标准之一，若此值越小，则越容易被判断为啸叫频带。范围为[0,80] ，建议值为10，步长为1
PHPR_thres	PHPR阀值(dB)，峰值谐波功率比，为判断标准之一，若此值越小，则越容易被判断为啸叫频带。范围为[0,80] ，建议值为20，步长为1
suppression_thres	压抑总数阀值(%)，计算周围特定范围内被侦测为啸叫的频带占总范围内的百分比有超过此设定值，也将被压抑。若此值设定越小，啸叫频带周围压抑程度越强。范围为[0,100] ，建议值为5，步长为1
supbins	当前帧被压抑的频带总数(%)，若当前帧被压抑的频带占总频带的百分比超过此设定值，则列入啸叫过量帧。若此值设定越小，越容易被判断为啸叫过量帧。范围为[0,100] ，建议值为25，步长为1
excess_supbins_time	啸叫过量帧连续时间阀值(ms)，若啸叫过量帧连续时间超过此设定值，则须将音量调小来达到较好的效果。范围为[0,1600] ，建议值为240，步长为1
within_supbins_time	非啸叫过量帧持续时间阀值(ms)，音量调小后，计算非啸叫过量帧连续时间若超过此设定值，则可将音量调回。范围为[0,8000]，建议值为800，步长为1

注意事项

无。
相关数据类型及接口

IaaDh_Config

IaaDh_GetConfig

IaaDh_ConfigReadFromJson

3.4. DH_HANDLE¶

说明

定义Dh算法的句柄类型。
定义

typedef void* DH_HANDLE;
成员

无
注意事项

无
相关数据类型及接口

IaaDh_Init

IaaDh_Config

IaaDh_GetConfig

IaaDh_Run

IaaDh_Reset

IaaDh_Free

4. Error code¶

DH API 错误码如下表所示：

错误码	宏定义	描述
0x00000000	ALGO_DH_RET_SUCCESS	DH执行成功
0x10000701	ALGO_DH_RET_INVALID_CONFIG	DH Config无效
0x10000702	ALGO_DH_RET_INVALID_HANDLE	DH Handle无效
0x10000703	ALGO_DH_RET_INVALID_SAMPLERATE	DH采样率无效
0x10000704	ALGO_DH_RET_INVALID_POINTNUMBER	DH采样点数无效
0x10000705	ALGO_DH_RET_INVALID_CHANNEL	DH通道数无效
0x10000706	ALGO_DH_RET_INVALID_ENABLE	DH ENABLE 无效
0x10000707	ALGO_DH_RET_INVALID_LOWERFREQ	LOWERFREQ设置无效
0x10000708	ALGO_DH_RET_INVALID_PTPR	PTPR设置无效
0x10000709	ALGO_DH_RET_INVALID_PAPR	PAPR设置无效
0x10000710	ALGO_DH_RET_INVALID_PHPR	PHPR设置无效
0x10000711	ALGO_DH_RET_INVALID_SUPTHRESHLOD	SUPTHRESHLOD设置无效
0x10000712	ALGO_DH_RET_INVALID_SUPBINS	SUPBINS设置无效
0x10000713	ALGO_DH_RET_INVALID_EXCESS_SUPBINS_TIME	EXCESS_SUPBINS_TIME 设置无效
0x10000714	ALGO_DH_RET_INVALID_WITHIN_SUPBINS_TIME	WITHIN_SUPBINS_TIME 设置无效
0x10000715	ALGO_DH_RET_INVALID_CALLING	DH呼叫API顺序错误
0x10000716	ALGO_DH_RET_API_CONFLICT	有其他API正在运行
0x10000717	ALGO_DH_RET_FAILED	参数设置错误

参数名称	描述	输入/输出
working_buffer	Dh算法所使用的内存地址	输入
dh_init	Dh算法的初始化结构体指针	输入

参数名称	描述	输入/输出
working_buffer	Dh算法运行的内存地址	输入
dh_init	Dh算法的初始化参数结构体指针	输入

成员名称	描述
IAA_DH_SAMPLE_RATE_8000	采样率8000Hz
IAA_DH_SAMPLE_RATE_16000	采样率16000Hz
IAA_DH_SAMPLE_RATE_48000	采样率48000Hz

成员名称	描述
point_number	Dh算法处理一次的采样点数
channel	通道数
sample_rate	采样率，目前支持8k/16k/48k

返回值	结果
非NULL	成功
NULL	失败

返回值	结果
0	成功
非0	失败，参照错误码

返回值	结果
0	成功
非0	失败，参照错误码

返回值	结果
0	成功
非0	失败，参照错误码