robot-project/wake_word_module/AEC_GUIDE.md

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模块

# 下载配置脚本
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

# 编辑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 设备

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

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

Q2: 配置后音频延迟增加

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

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

Q3: AEC效果不明显

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

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

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

使用方法

基本使用

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

# 创建音频采集器（不启用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参数:

# 编辑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功能基于操作系统提供的系统级实现，遵循相应操作系统的许可证。