简介：dtmf2num.zip 是一款面向电话按键识别与音频信号处理学习者的轻量级工具源码包，聚焦从 PCM 波形与 WAV 文件中解码 DTMF 双音多频信号，可用于九键按键识别、电话拨号音分析等实验场景。包内共 6 个文件，以 3 个 C 源文件为核心实现，配合 1 个头文件与 1 个 Makefile 构成可编译工程，另附 1 个可直接运行的 exe 程序，整体仅 28KB，便于快速阅读与二次开发。工具支持任意采样频率、单双声道及 8/16/24/32 位波形文件，并内置直流偏置调整与归一化等自动优化处理，同时兼容 WAV 与原始 PCM 数据输入。已有 1071 人学习下载，适合嵌入式音频开发、信号处理课程实践及需要理解 DTMF 解码原理的读者参考，可从中获取完整的解码流程、重采样与 DSP 处理思路以及可复用的工程结构。
1. dtmf2num.zip：一个压缩包名背后，藏着电话按键音识别的完整落地链路
第一次看到dtmf2num.zip这个标题，很多人会以为它只是某个小工具的分发包，解压、双击、输入音频、输出数字，完事。真到项目里用起来才发现，DTMF 识别远不是「读个文件、跑个函数」这么简单：采样率不对，识别率断崖式下跌；音频里混进人声，检测器开始乱报；双音频率偏差几十赫兹，Goertzel 就判不出来。这个标题真正指向的，是一条从音频输入、双音检测、按键判决到结果输出的完整链路，压缩包只是它的外壳。它适合两类人：一类是想把电话按键音、IVR 导航音、录音里的拨号音转成数字序列的工程从业者；另一类是想搞懂「两个频率同时出现怎么被稳定识别」的信号处理入门者。下面按我实际搭过的最小系统，把选型、参数、代码和翻车点一次讲透。
2. DTMF 双音检测的原理与选型：为什么 Goertzel 比 FFT 更适合按键音
2.1 DTMF 的频率编码规则与判决边界
DTMF 的本质是「行频 + 列频」两个正弦波叠加，每个按键对应唯一的一对频率。低频组是 697、770、852、941 Hz，高频组是 1209、1336、1477、1633 Hz，两组交叉得到 16 个键位（0-9、*、#、A-D）。识别器的任务不是「听清声音」，而是判断当前音频片段里是否同时存在某一对频率，且两者的能量都足够强、其余频率足够弱。
这里有个容易被忽略的判决边界：标准要求检测到的频率偏差在 ±1.5% 以内，同时「 twist」（高低频能量差）通常允许 8 dB 左右，噪声和语音引起的杂散能量必须被压制。很多开源实现只做「找最大峰」，结果在带噪录音上把语音共振峰误判成按键。我一般会同时设三道门槛：目标频率能量相对总能量的占比、目标频率与相邻频率的能量比、以及双音持续时间。只靠单一阈值，玄学成分太大，换个录音环境就翻车。
2.2 Goertzel 算法的最小实现与参数含义
FFT 会把整个频带都算一遍，而 DTMF 只需要关心 8 个已知频率。Goertzel 算法正是为「只算少数几个频点」设计的，复杂度从 O(N log N) 降到 O(N·K)，K 就是关心的频点数。对 8 kHz 采样、每帧 205 个采样点这种典型配置，Goertzel 的计算量小到可以在一颗低端 MCU 上实时跑。
import numpy as np # 标准 DTMF 频率表 LOW = [697, 770, 852, 941] HIGH = [1209, 1336, 1477, 1633] KEYS = [['1','2','3','A'], ['4','5','6','B'], ['7','8','9','C'], ['*','0','#','D']] def goertzel_power(samples, fs, target_freq): """计算单个目标频率的归一化能量""" n = len(samples) k = int(0.5 + n * target_freq / fs) # 频点索引，四舍五入 omega = 2.0 * np.pi * k / n coeff = 2.0 * np.cos(omega) s_prev = s_prev2 = 0.0 for x in samples: s = x + coeff * s_prev - s_prev2 s_prev2, s_prev = s_prev, s power = s_prev2**2 + s_prev**2 - coeff * s_prev * s_prev2 return power / (n * n) # 按帧长归一化，便于跨帧比较这段代码里三个参数决定成败。n是帧长，8 kHz 下取 205 点约等于 25.6 ms，正好覆盖 DTMF 最短有效时长（标准建议 40 ms，检测窗口可以更短但要连续多帧确认）。k的四舍五入决定了实际分析频点，帧长越短频率分辨率越粗，205 点时分辨率约 39 Hz，对 ±1.5% 的容差是够用的。最后的归一化除以n*n，是为了让不同帧长的能量可比，否则调阈值时会被帧长变化带偏。
2.3 从能量到按键：判决逻辑怎么写才不飘
拿到 8 个频点的能量后，不能直接取两组各自最大就完事。我的做法是先算低频组和高频组的总能量，再分别找组内最大，然后做三重校验：组内最大值要显著高于组内次大值（防止两个频率能量接近时误判）、高低两组最大能量之比要在 twist 容差内、该帧总能量要高于静音门限。三关都过，才输出候选键。
def detect_key(frame, fs, energy_floor=1e-6, ratio_min=2.0, twist_db=10.0): low_p = [goertzel_power(frame, fs, f) for f in LOW] high_p = [goertzel_power(frame, fs, f) for f in HIGH] li = int(np.argmax(low_p)); hi = int(np.argmax(high_p)) lp, hp = low_p[li], high_p[hi] total = sum(low_p) + sum(high_p) if total < energy_floor: return None # 静音或能量过低 # 组内主峰必须明显高于次峰 low_sorted = sorted(low_p, reverse=True) high_sorted = sorted(high_p, reverse=True) if low_sorted[0] < ratio_min * low_sorted[1]: return None if high_sorted[0] < ratio_min * high_sorted[1]: return None # twist 校验：高低频能量差不能超过阈值 twist = abs(10 * np.log10((lp + 1e-12) / (hp + 1e-12))) if twist > twist_db: return None return KEYS[li][hi]ratio_min设 2.0 是经验值，语音干扰强时可以提到 3.0，代价是弱按键漏检。twist_db放到 10 dB 比标准略宽，因为实际录音经过压缩和增益调整后 twist 会漂。energy_floor必须结合你的音频幅度范围来定，直接抄数值大概率不合适，建议先跑一段纯静音统计底噪再定。判决逻辑写完后，还要加「连续 N 帧同一按键才确认」的去抖，否则一个按键会被切成好几个。
3. 把 dtmf2num.zip 跑起来：音频预处理、分帧与结果输出
3.1 音频读取与重采样到 8 kHz 的坑
DTMF 的有效频率上限是 1633 Hz，按奈奎斯特采样，4 kHz 以上就够了，工程上统一用 8 kHz 是行业惯例。但手头的录音往往是 44.1 kHz 或 48 kHz，直接降采样会引入混叠，1633 Hz 附近可能混进镜像频率。正确顺序是先低通滤波再抽取，而不是简单隔点取数。
import wave import numpy as np from scipy.signal import resample_poly def load_wav_8k(path): with wave.open(path, 'rb') as w: fs = w.getframerate() ch = w.getnchannels() width = w.getsampwidth() raw = w.readframes(w.getnframes()) if width == 2: data = np.frombuffer(raw, dtype='<i2').astype(np.float64) / 32768.0 elif width == 1: data = (np.frombuffer(raw, dtype=np.uint8).astype(np.float64) - 128) / 128.0 else: raise ValueError('unsupported sample width') if ch > 1: data = data.reshape(-1, ch).mean(axis=1) # 多声道取平均 if fs != 8000: # 用有理数重采样，内部自带抗混叠滤波 from math import gcd g = gcd(fs, 8000) data = resample_poly(data, 8000 // g, fs // g) return data, 8000resample_poly内部会做多相滤波，比直接data[::step]安全得多。多声道取平均而不是取第一声道，是因为有些录音左右声道电平差很大，取单边可能丢掉有效信号。采样位宽只处理 8 bit 和 16 bit，24 bit 的 WAV 需要单独分支，这一点在解压后先看文件头再决定，别假设都是 16 bit。
3.2 分帧、加窗与帧移的选择
帧长和帧移是一对要一起调的参数。帧长 205 点（25.6 ms）时频率分辨率约 39 Hz，帧移取帧长的一半（102 点）能保证相邻帧有重叠，不会把跨帧的按键切丢。加窗方面，Goertzel 对矩形窗的频点计算本身是精确的，但实际信号不会正好落在整数频点上，加汉宁窗能压低频谱泄漏，代价是主瓣变宽。我的习惯是：干净录音用矩形窗，带噪录音用汉宁窗并把ratio_min调高。
def frame_signal(data, frame_len=205, hop=102): frames = [] for start in range(0, len(data) - frame_len + 1, hop): frames.append(data[start:start + frame_len]) return frames def decode_dtmf(data, fs, min_frames=2): frames = frame_signal(data) seq, last, run = [], None, 0 for fr in frames: key = detect_key(fr, fs) if key == last and key is not None: run += 1 else: if last is not None and run >= min_frames: seq.append(last) last, run = key, 1 if last is not None and run >= min_frames: seq.append(last) return ''.join(seq)min_frames=2意味着至少连续两帧（约 51 ms）判为同一键才输出，这能滤掉大部分瞬态误判。如果录音里按键很短，可以降到 1，但要配合更严的ratio_min。帧移 102 点是帧长的一半，重叠 50%，这是语音处理里最常用的折中，帧移再小计算量翻倍收益有限。
3.3 输出格式与批量处理脚本
单个文件跑通后，实际项目往往是批量处理一批录音。批量脚本要解决三件事：遍历目录、单文件失败不中断、结果落盘带原始文件名。下面这个脚本把前面几个函数串起来，输出「文件名 → 识别序列」的对照表。
import os, csv def batch_decode(in_dir, out_csv): rows = [] for name in sorted(os.listdir(in_dir)): if not name.lower().endswith('.wav'): continue path = os.path.join(in_dir, name) try: data, fs = load_wav_8k(path) seq = decode_dtmf(data, fs) rows.append((name, seq)) except Exception as e: rows.append((name, f'ERROR:{e}')) # 单文件失败不影响整体 with open(out_csv, 'w', newline='', encoding='utf-8') as f: writer = csv.writer(f) writer.writerow(['file', 'digits']) writer.writerows(rows) if __name__ == '__main__': batch_decode('./wavs', './result.csv')ERROR:前缀让后续排查能一眼定位问题文件，而不是整批静默失败。CSV 用 UTF-8 编码，避免文件名含中文时乱码。批量跑之前建议先拿 3 到 5 个已知答案的样本做回归，确认识别序列和预期一致，再放开全量，这是省时间的后悔药。
4. 识别率上不去的排查清单：五个高频翻车点
4.1 现象：静音段疯狂输出数字
原因通常是energy_floor设得太低，底噪被当成有效信号，加上组内比值校验在低能量下不稳定，随机峰被放大成按键。解决方法是先跑一段纯静音，统计每帧总能量的分布，把门限设在底噪均值的 3 到 5 倍以上；同时给detect_key加一个「总能量低于门限直接返回 None」的前置判断，别让后续逻辑在噪声上做文章。
4.2 现象：同一个按键被识别成两个不同数字
这是分帧边界导致的：按键起始和结束的过渡帧里，两个频率的能量此消彼长，可能先判成 A 再判成 B。解决方法是把去抖逻辑从「连续同键计数」改成「滑窗投票」，窗口内出现次数最多的键且占比超过 60% 才输出；另外检查帧移是否过大，帧移接近帧长时跨帧信息丢失严重，把帧移降到帧长一半以下通常能缓解。
4.3 现象：换一台设备录的音，识别率从 95% 掉到 60%
设备差异主要体现在采样率、增益和频响上。先确认重采样路径是否走了抗混叠滤波，再检查 twist 是否超出阈值——有些设备的麦克风频响在 1.2 kHz 附近有凹陷，高频组能量被压低，twist_db设 10 dB 就不够了。我的做法是把 twist 阈值做成可配置，并对每个新设备先用一段标准按键音标定，记录实际 twist 分布再定阈值，而不是一套参数打天下。
4.4 现象：带背景音乐的录音里误检率飙升
音乐里的和弦、人声共振峰都可能落在 DTMF 频点附近，单帧能量校验挡不住。这时要加「双音持续性」约束：不仅要求连续多帧同键，还要求这多帧里高低频能量比稳定，波动超过一定范围就丢弃。另一个有效手段是提高ratio_min到 3.0 以上，牺牲一点灵敏度换准确率，具体取值看你的场景更怕漏检还是更怕误检。
4.5 现象：长录音跑到后面越来越慢
多半是逐帧 Python 循环里反复创建数组或做了不必要的拷贝。把goertzel_power里的循环用 NumPy 向量化重写，或者把 8 个频点的计算合并成一次矩阵运算，速度能提升一个数量级。另外批量脚本里每个文件都重新 import 或重新初始化滤波器也是浪费，把重采样滤波器系数缓存起来复用。性能问题先 profile 再优化，别凭感觉改。
5. 进阶：把识别器做成可标定、可回归的小系统
做到能跑通只是起点，真正决定这套东西能不能长期用的，是它有没有「可标定」和「可回归」的能力。我一般会给识别器配一个极简的标定脚本：准备一段包含全部 16 个按键、每个按键重复若干次的标准音频，跑一遍识别，统计每个键的召回率和误检率，输出一张混淆矩阵。参数调整前后各跑一次，对比矩阵变化，比凭耳朵听靠谱得多。
def evaluate(seq, truth): """逐位对比，返回准确率和首个错误位置""" n = min(len(seq), len(truth)) wrong = [i for i in range(n) if seq[i] != truth[i]] acc = (n - len(wrong)) / max(len(truth), 1) return acc, (wrong[0] if wrong else -1)这个函数故意做得简单，因为它要嵌进回归脚本里反复调用。acc的分母用len(truth)而不是len(seq)，是为了让漏检也计入错误，避免「少输出反而准确率高」的假象。首个错误位置-1表示全对，非负值直接指向需要人工回听的帧，排查效率比逐帧打印高很多。
标定之外，还有两个我踩过坑才加上的习惯。第一，所有阈值集中放在一个配置字典里，不散落在函数默认参数中，改参数时只动一处，回归时能明确知道变了什么。第二，每次改判决逻辑都保留旧版本的输出做对照，新版本在标定集上不劣于旧版本才合入，这条规矩救过我好几次——有一次为了压误检把ratio_min调高，标定集准确率涨了，但真实录音里短按键全漏了，正是对照旧输出才发现的。
还有一个容易被低估的点：DTMF 识别器的输出最好带置信度，而不是只给一个字符。置信度可以用「主峰能量占比」和「连续帧一致性」组合出来，下游拿到低置信度的结果可以选择丢弃或人工复核。很多线上问题不是识别错了，而是错了却没有任何信号提示，等用户投诉才发现。给每个输出附一个 0 到 1 的分数，阈值以下标记为可疑，这套机制的成本很低，收益在长期运维里非常明显。
最后说句实在的，dtmf2num.zip这类工具的价值不在于算法多新，而在于参数是否被认真标定过、失败路径是否被覆盖过。我现在的习惯是：任何识别类脚本，先写标定和回归，再写主逻辑，顺序反过来迟早要返工。希望帮到你。
本文还有配套的精品资源，点击获取
