# AEC回音消除使用指南

## 概述

AEC（Acoustic Echo Cancellation，声学回声消除）是一种用于消除扬声器播放声音被麦克风再次录制的回声的技术。本模块支持Windows和Linux平台的系统级AEC功能。

## 平台支持

### Windows

**系统级AEC**: 自动使用操作系统提供的回声消除功能

- **无需额外配置**: 开箱即用
- **性能**: 依赖系统音频驱动
- **CPU开销**: 零额外开销
- **延迟**: 最小延迟

**工作原理**:
Windows系统通过音频驱动层自动处理回声消除，应用层无需额外处理。系统会自动检测并消除扬声器到麦克风的回声。

### Linux

**系统级AEC**: 使用PulseAudio模块化AEC

- **优势**: 系统级处理，应用透明
- **原理**: module-echo-cancel + WebRTC算法
- **配置**: 一次性配置，持久生效

#### Linux AEC配置

**方案1: 使用PulseAudio AEC模块**

```bash
# 下载配置脚本
git clone https://github.com/W-E-A/PulseAudio-AEC-Script.git
cd PulseAudio-AEC-Script

# 设置执行权限
chmod +x setup_aec.sh uninstall_aec.sh

# 配置AEC
./setup_aec.sh

# 卸载AEC
./uninstall_aec.sh
```

**方案2: 手动配置PulseAudio**

```bash
# 编辑PulseAudio配置文件
nano ~/.config/pulse/default.pa

# 添加AEC模块
load-module module-echo-cancel aec_args='"frame_size_ms=8"'

# 重启PulseAudio
pulseaudio --kill && pulseaudio --start
```

#### Linux故障排除

**Q1: 脚本运行后找不到 echo cancellation 设备**

```bash
# 检查PulseAudio设备
pactl list sinks short
pactl list sources short

# 重启PulseAudio
pulseaudio --kill && pulseaudio --start
```

**Q2: 配置后音频延迟增加**

```bash
# 检查缓冲区设置
pactl list sources | grep -A10 "echo-cancel"

# 调整延迟参数（可选）
# 编辑 ~/.config/pulse/default.pa
# 添加: load-module module-echo-cancel aec_args='"frame_size_ms=8"'
```

**Q3: AEC效果不明显**

```bash
# 检查AEC模块是否加载
pactl list modules | grep echo-cancel

# 检查音频路由
pactl list sources
pactl list sinks

# 调整AEC参数
# 编辑配置文件，调整frame_size_ms参数
```

## 使用方法

### 基本使用

```python
import asyncio
from wake_word_module import WakeWordDetector, AudioCapture, WakeWordConfig

async def main():
    # 创建配置
    config = WakeWordConfig(
        model_path="models",
        sample_rate=16000,
    )

    # 创建音频采集器（启用AEC）
    audio_capture = AudioCapture(
        sample_rate=16000,
        channels=1,
        enable_aec=True,  # 启用AEC回音消除
    )

    # 创建检测器
    detector = WakeWordDetector(config)

    # 设置回调
    detector.on_detected(lambda r, t: print(f"检测到唤醒词: {r}"))

    # 连接并启动
    audio_capture.add_audio_listener(detector)
    await audio_capture.start()
    await detector.start()

    # 保持运行
    while True:
        await asyncio.sleep(1)

asyncio.run(main())
```

### 不使用AEC

```python
# 创建音频采集器（不启用AEC）
audio_capture = AudioCapture(
    sample_rate=16000,
    channels=1,
    enable_aec=False,  # 不启用AEC
)
```

## AEC工作原理

### Windows平台

```
应用层（Python）
    │
    ▼
┌─────────────────────┐
│  AudioCapture      │
│  - 采集音频       │
│  - 启用AEC标志   │
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Windows音频驱动    │
│  - 系统级AEC      │
│  - 自动回声消除     │
└─────────────────────┘
    │
    ▼
输出音频（已消除回声）
```

**特点**:
- 应用层只需设置`enable_aec=True`
- 系统驱动层自动处理AEC
- 无需参考信号捕获
- 零额外CPU开销

### Linux平台

```
应用层（Python）
    │
    ▼
┌─────────────────────┐
│  AudioCapture      │
│  - 采集音频       │
│  - 启用AEC标志   │
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  PulseAudio        │
│  - AEC模块        │
│  - 回声消除       │
└─────────────────────┘
    │
    ▼
输出音频（已消除回声）
```

**特点**:
- 需要预先配置PulseAudio AEC模块
- 系统级处理，应用透明
- 配置持久生效
- 一次配置，全局生效

## 性能影响

### Windows

- **CPU占用**: 0%（系统级处理）
- **延迟**: 最小（系统级优化）
- **内存**: 无额外开销
- **兼容性**: 依赖音频驱动

### Linux

- **CPU占用**: 1-3%（PulseAudio AEC）
- **延迟**: 低（系统级优化）
- **内存**: 轻微增加（缓冲区）
- **兼容性**: 依赖PulseAudio配置

## 故障排除

### Windows平台

#### 问题: AEC未生效

**解决方案:**
1. 检查音频驱动是否支持AEC
2. 更新音频驱动程序
3. 检查系统音频设置
4. 确认麦克风和扬声器配置正确

#### 问题: 回声消除效果不明显

**解决方案:**
1. 检查音频设备质量
2. 调整麦克风和扬声器位置
3. 检查环境噪声水平
4. 尝试不同的音频设备

### Linux平台

#### 问题: AEC模块未加载

**解决方案:**
1. 检查PulseAudio配置
2. 重启PulseAudio服务
3. 检查模块是否安装
4. 查看系统日志

#### 问题: 配置后音频延迟增加

**解决方案:**
1. 调整AEC参数（frame_size_ms）
2. 减小缓冲区大小
3. 检查系统资源使用

#### 问题: 回声消除效果不明显

**解决方案:**
1. 调整AEC参数
2. 确保音频路由正确
3. 检查音频设备配置
4. 尝试不同的AEC算法

## 高级配置

### Windows高级配置

Windows平台的AEC主要通过系统设置配置：

1. **控制面板** → **声音** → **录制**
2. **控制面板** → **声音** → **播放**
3. 调整麦克风和扬声器设置
4. 启用回声消除选项

### Linux高级配置

**调整AEC参数**:

```bash
# 编辑PulseAudio配置
nano ~/.config/pulse/default.pa

# 调整帧大小（影响延迟和效果）
load-module module-echo-cancel aec_args='"frame_size_ms=8"'  # 8ms帧

# 调整其他参数
load-module module-echo-cancel aec_args='"frame_size_ms=8;filter_length_ms=100"'
```

**参数说明**:
- `frame_size_ms`: 帧大小（8-16ms），越小延迟越低
- `filter_length_ms`: 滤波器长度（50-200ms），越大效果越好

## 注意事项

1. **平台限制**: 本模块仅支持Windows和Linux平台
2. **Windows配置**: 通过系统音频设置配置
3. **Linux配置**: 需要预先配置PulseAudio AEC模块
4. **性能影响**: 系统级AEC对应用性能影响很小
5. **兼容性**: 某些音频设备可能与AEC不兼容
6. **环境因素**: 房间声学特性会影响AEC效果

## 许可证

AEC功能基于操作系统提供的系统级实现，遵循相应操作系统的许可证。