Metadata-Version: 2.4
Name: PyDTMF
Version: 1.0.0
Summary: Pure Python DTMF/MF tone detection using the Goertzel algorithm
Author: Moxin1044
License: GPL-2.0-only
Project-URL: Homepage, https://github.com/Moxin1044/PyDTMF
Project-URL: Source, https://github.com/Moxin1044/PyDTMF
Keywords: dtmf,mf,goertzel,tone-detection,dsp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# PyDTMF 🔢🎵

> 纯 Python 实现的 DTMF/MF 双音多频信号检测库 — 零外部依赖。

使用 Goertzel 算法从 WAV 音频文件中检测 DTMF（双音多频）和 Bell MF（多频）拨号音。

## 功能特点

- ✅ **DTMF 检测** — 数字 0-9、\*、#、A、B、C、D
- ✅ **Bell MF 检测** — 多频信令音检测
- ✅ **纯 Python** — 无 C 扩展、无 NumPy，仅使用标准库
- ✅ **WAV 支持** — 8/16/24/32 位 PCM，任意采样率
- ✅ **音频预处理** — 自动转单声道、去直流偏置、音量归一化、重采样至 8kHz

## 安装

```bash
pip install git+https://github.com/Moxin1044/PyDTMF.git
```

或者直接复制 `PyDTMF/` 目录即可使用 — 无需安装。

## 使用方法

### 命令行

```bash
python -m PyDTMF recording.wav
python -m PyDTMF recording.wav --mf          # 同时检测 MF 信号
python -m PyDTMF recording.wav --no-optimize  # 跳过预处理
```

### Python API

```python
from PyDTMF import from_wav, detect, from_pcm

# 从 WAV 文件检测
dtmf, mf = detect("recording.wav")
print(f"DTMF: {dtmf}")

# 从 WAV 字节数据检测（例如从网络下载）
with open("recording.wav", "rb") as f:
    dtmf, mf = from_wav(f.read())

# 从原始 PCM 采样数据检测
dtmf, mf = from_pcm(samples, sample_rate=44100, channels=1)

# 同时检测 MF 信号
dtmf, mf = from_pcm(samples, detect_mf_mode=True)
```

## 工作原理

1. 解析 WAV 文件头 → 提取格式信息
2. 转换为单声道、去除直流偏置、归一化音量
3. 重采样至 8kHz（电话标准采样率）
4. 使用 Goertzel 算法测量每个 DTMF 频率的能量
5. 当两个主导频率（一个行频、一个列频）超过阈值时判定为有效数字

### DTMF 频率表

|       | 1209 Hz | 1336 Hz | 1477 Hz | 1633 Hz |
|-------|---------|---------|---------|---------|
| 697 Hz  | 1       | 2       | 3       | A       |
| 770 Hz  | 4       | 5       | 6       | B       |
| 852 Hz  | 7       | 8       | 9       | C       |
| 941 Hz  | \*      | 0       | #       | D       |

## 许可证

GNU General Public License v2.0。
