Metadata-Version: 2.5
Name: speexdsp-aec
Version: 0.1.0
Summary: ctypes 封装 libspeexdsp (Xiph) 的流式声学回声消除 (AEC) — 零编译纯 Python 轮子
Author: Xmov
License: Proprietary
Keywords: aec,audio,echo-cancellation,speexdsp
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.8
Requires-Dist: numpy>=1.20
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# speexdsp-aec

ctypes 封装 [libspeexdsp](https://www.speex.org/) (Xiph) 的流式**声学回声消除 (AEC)** —
零编译纯 Python 轮子 (py3-none-any)。

## 为什么不用现成的 pip 包

| 包 | 状态 |
|---|---|
| `speexdsp` (PyPI) | 2018 年后失修, 仅 sdist, 构建需要 swig + 系统头文件 |
| `webrtc-audio-processing` (PyPI) | 2016 年后失修, 仅 cp36/armv7l |
| `pyaec` (PyPI, 预编译 wheel) | 底层是 speexdsp 的 Rust 移植 (aec-rs), 实测纯回声 ERLE 仅 ~13dB 且双讲损伤语音 (相关度 0.84→0.65) |

而真 libspeexdsp 同场景实测: 纯回声 ERLE 53dB、双讲语音相关度 0.86 (比不处理还好);
其 C API 自 2008 年起未变, ctypes 直连稳定可靠。

## 安装

```bash
# 系统库 (二选一)
sudo apt install libspeexdsp1      # Ubuntu/Debian
brew install speexdsp              # macOS

pip install speexdsp-aec
```

无系统库的特殊环境可用 `SPEEXDSP_LIB` 环境变量指向 .so/.dylib 文件。

## 用法

```python
from speexdsp_aec import SpeexAec

aec = SpeexAec(sample_rate=16000, frame_ms=20, filter_tail_ms=200)
# near: 麦克风混音 int16 数组; ref: 与播放同步的参考信号 (如播放回采通道)
out_bytes = aec.process(near_int16, ref_int16)   # 消回声后的 PCM, 不足一帧时返回 b""
aec.close()
```

## 参数

- `sample_rate`: 采样率 (默认 16000)
- `frame_ms`: speex 内部帧长 (默认 20ms)
- `filter_tail_ms`: 回声拖尾长度 (默认 200ms, 覆盖 50ms 延迟 + 混响余量)

## 收敛特性

- 平稳参考: 数秒内 ERLE >40dB
- 语音参考 (TTS): 持续播放 3~5s 后 ERLE ~15~20dB; 声学路径固定时对话中保持收敛

## 开发

```bash
python -m venv venv && venv/bin/pip install -e ".[dev]"
venv/bin/python -m pytest
```
