构建实时音频增强系统入门：基于 WebRTC 的 Python 实战

def __init__(self, sample_rate=16000, channels=1, frame_size=160,
             auto_gain_dbfs=3, noise_suppression_level=2):
    # 基础音频参数配置
    self.sample_rate = sample_rate
    self.channels = channels
    self.frame_size = frame_size

    # 初始化 WebRTC 音频处理核心
    self.audio_processor = AudioProcessor(auto_gain_dbfs, noise_suppression_level)

    # 初始化 PyAudio 接口和音频缓冲区
    self.p = pyaudio.PyAudio()
    self.audio_buffer = np.array([], dtype=np.int16)
    self.speech_detected = False

def input_callback(self, in_data, frame_count, time_info, status):
    # 1. 将字节数据转换为 numpy 数组
    audio_data = np.frombuffer(in_data, dtype=np.int16)
    # 2. 将新数据追加到缓冲区
    self.audio_buffer = np.concatenate([self.audio_buffer, audio_data])
    # 3. 调用处理函数
    self.process_audio()
    # 4. 返回状态，告知 PyAudio 继续流式传输
    return (in_data, pyaudio.paContinue)

def process_audio(self):
    # 检查缓冲区中是否有足够一帧的数据
    if len(self.audio_buffer) < self.frame_size:
        return

    # 提取一帧音频数据
    audio_chunk = self.audio_buffer[:self.frame_size].astype(np.int16)
    # 从缓冲区中移除已提取的数据
    self.audio_buffer = self.audio_buffer[self.frame_size:]

    # 转换为字节数据并送入 WebRTC 处理器
    audio_bytes_10ms = audio_chunk.tobytes()
    result = self.audio_processor.Process10ms(audio_bytes_10ms)

    # 更新 VAD 状态
    self.speech_detected = result.is_speech
    if result.is_speech:
        print("✓ 检测到语音")

    # 如果设置了自定义回调，则调用（例如用于保存文件）
    if self.processed_audio_callback is not None:
        self.processed_audio_callback(result.audio, result.is_speech)

    # 如果输出流已打开，则播放处理后的音频
    if self.processed_stream is not None:
        self.processed_stream.write(result.audio)

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
WebRTC 音频增强处理器

====================================================================================
模块说明：
====================================================================================
这是一个基于 Google WebRTC 库的实时音频增强处理系统，主要用于改善音频质量。
该模块实现了工业级的音频预处理技术，广泛应用于语音通话、语音识别等场景。

====================================================================================
核心功能：
====================================================================================
1. 自动增益控制 (AGC - Automatic Gain Control)
   - 作用：自动调整音频信号的增益（音量），确保输出音量稳定
   - 原理：监测音频信号的幅度，当声音过小时自动放大，过大时自动衰减
   - 应用场景：防止因说话者距离麦克风远近导致的音量不稳定问题

2. 噪声抑制 (NS - Noise Suppression)
   - 作用：减少背景噪声，提高语音信号的清晰度
   - 原理：使用频谱分析技术，识别并抑制非语音频率成分
   - 应用场景：消除空调、风扇、键盘敲击等环境噪声

3. 语音活动检测 (VAD - Voice Activity Detection)
   - 作用：检测音频中是否包含人声
   - 原理：分析音频的能量、频谱特征和时域特征来判断是否为语音
   - 应用场景：语音唤醒、语音分段、降低数据传输量

====================================================================================
技术规格：
====================================================================================
- 采样率：16kHz（电话质量，适合语音处理）
- 声道数：1（单声道，节省计算资源）
- 量化位数：16-bit（CD质量的一半，平衡音质和性能）
- 处理单元：10ms帧（160个采样点@16kHz）
- 缓冲区大小：320字节（160个16-bit采样点）

====================================================================================
处理流程：
====================================================================================
1. 音频采集：麦克风 → PyAudio输入流 → 音频缓冲区
2. 帧分割：将连续音频流分割成10ms的短帧
3. WebRTC处理：AGC + NS + VAD 同时处理每个音频帧
4. 输出播放：处理后的音频 → PyAudio输出流 → 扬声器
5. 状态反馈：VAD结果用于语音检测状态显示

====================================================================================
依赖库说明：
====================================================================================
- pyaudio: 跨平台音频I/O库，用于音频设备的读写操作
- numpy: 科学计算库，用于音频数据的数组操作和数学运算
- webrtc_noise_gain: Google WebRTC音频处理模块的Python封装
- time: 标准库，用于程序执行流程控制

====================================================================================
版本: 1.0
创建时间: 2025
用途: 音频处理技术实际应用演示
====================================================================================
"""

# ====================================
# 导入必要的库
# ====================================
import pyaudio          # 音频输入输出接口
import numpy as np      # 数值计算和数组处理
import time            # 时间控制和延迟
from webrtc_noise_gain import AudioProcessor  # WebRTC音频处理核心模块
from typing import Optional, Callable, Tuple, List, Union, Any


# ====================================
# 主要类定义：WebRTC音频增强处理器
# ====================================

class WebRTCAudioEnhancer:
    """
    WebRTC音频增强处理器类
    
    ==================================================================================
    类说明：
    ==================================================================================
    这个类封装了基于Google WebRTC库的实时音频处理功能，提供了一个完整的
    音频增强解决方案。它可以实时处理麦克风输入的音频，应用多种增强算法，
    并将处理后的音频输出到扬声器或其他处理模块。
    
    ==================================================================================
    主要特性：
    ==================================================================================
    1. 实时处理：基于回调函数的异步音频处理，延迟极低
    2. 模块化设计：每个功能模块可以独立配置和控制
    3. 错误恢复：完善的异常处理机制，确保系统稳定性
    4. 设备兼容：支持多种音频设备，自动适配设备参数
    5. 扩展性：提供回调接口，支持自定义音频处理逻辑
    
    ==================================================================================
    使用场景：
    ==================================================================================
    - 语音通话系统：提高通话质量
    - 语音识别前端：预处理语音输入
    - 录音软件：实时音频增强
    - 会议系统：减少环境噪声干扰
    - 语音唤醒：结合VAD进行语音检测
    
    ==================================================================================
    技术原理：
    ==================================================================================
    音频处理采用流式处理模式：
    1. 音频采集线程持续从麦克风读取数据
    2. 数据累积到缓冲区中等待处理
    3. 当缓冲区达到一个完整帧大小时触发处理
    4. WebRTC算法对该帧进行增强处理
    5. 处理结果输出到扬声器或回调函数
    
    ==================================================================================
    """
    
    def __init__(self, sample_rate: int = 16000, channels: int = 1, frame_size: int = 160, 
                 auto_gain_dbfs: int = 3, noise_suppression_level: int = 2) -> None:
        """
        初始化WebRTC音频增强处理器
        
        ============================================================================
        参数说明：
        ============================================================================
        sample_rate (int): 音频采样率，单位Hz
            - 16000: 电话质量，适合语音处理（推荐）
            - 8000:  低质量，节省带宽
            - 44100: CD质量，音乐处理
            - 48000: 专业音频质量
            
        channels (int): 声道数
            - 1: 单声道，节省计算资源和带宽（推荐语音应用）
            - 2: 立体声，提供更好的音频体验
            
        frame_size (int): 每次处理的音频帧大小（采样点数）
            - 计算公式：frame_size = sample_rate * frame_duration_ms / 1000
            - 160: 对应16kHz采样率下的10ms音频
            - 80:  对应8kHz采样率下的10ms音频
            - WebRTC要求固定使用10ms帧
            
        auto_gain_dbfs (int): 自动增益控制目标音量，单位dBFS
            - 0: 禁用自动增益控制
            - 1-31: 启用AGC，数值越大增益越强
            - 3: 推荐值，适中的增益控制
            - dBFS (decibels relative to full scale): 相对于满量程的分贝值
            
        noise_suppression_level (int): 噪声抑制强度级别
            - 0: 禁用噪声抑制
            - 1: 轻度抑制，保留更多原始音频特征
            - 2: 中度抑制，平衡噪声抑制和音质（推荐）
            - 3: 强度抑制，更激进的噪声去除
            - 4: 最强抑制，可能影响语音质量
            
        ============================================================================
        初始化过程：
        ============================================================================
        1. 保存音频参数配置
        2. 创建WebRTC音频处理器实例
        3. 初始化PyAudio音频接口
        4. 创建音频数据缓冲区
        5. 初始化状态跟踪变量
        6. 准备音频流对象（待后续创建）
        """
        
        # ================================
        # 基础音频参数配置
        # ================================
        self.sample_rate = sample_rate      # 采样率：每秒采样次数
        self.channels = channels            # 声道数：1=单声道，2=立体声
        self.frame_size = frame_size        # 帧大小：每次处理的采样点数
        
        # 计算音频帧的时间长度（毫秒）
        # 公式：frame_duration = frame_size / sample_rate * 1000
        frame_duration_ms = (frame_size / sample_rate) * 1000
        print(f"音频帧配置：{frame_size}个采样点 = {frame_duration_ms:.1f}ms @ {sample_rate}Hz")
        
        # ================================
        # WebRTC音频处理器初始化
        # ================================
        # 创建WebRTC AudioProcessor实例，这是音频增强的核心组件
        # 参数1：auto_gain_dbfs - 自动增益控制目标音量
        # 参数2：noise_suppression_level - 噪声抑制强度
        self.audio_processor = AudioProcessor(auto_gain_dbfs, noise_suppression_level)
        print(f"WebRTC处理器配置：AGC目标={auto_gain_dbfs}dBFS, NS级别={noise_suppression_level}")
        
        # ================================
        # PyAudio音频接口初始化
        # ================================
        # PyAudio是Python的音频I/O库，用于与音频硬件交互
        self.p = pyaudio.PyAudio()
        
        # ================================
        # 音频数据缓冲区
        # ================================
        # 使用numpy数组作为音频缓冲区，存储从麦克风读取的原始音频数据
        # dtype=np.int16：16位整数，对应PyAudio的paInt16格式
        self.audio_buffer = np.array([], dtype=np.int16)
        
        # ================================
        # 状态跟踪变量
        # ================================
        self.speech_detected = False           # VAD检测结果：当前是否有语音
        self.processed_audio_callback = None   # 可选回调函数：处理后音频的自定义处理
        
        # ================================
        # 音频流对象（初始化为None，后续创建）
        # ================================
        self.input_stream = None      # 麦克风输入流
        self.processed_stream = None  # 扬声器输出流
        
    def open_streams(self, input_device_index: int, output_device_index: Optional[int] = None) -> None:
        """
        创建并配置音频输入输出流
        
        ============================================================================
        方法说明：
        ============================================================================
        这个方法负责创建PyAudio音频流，包括麦克风输入流和扬声器输出流。
        音频流是音频数据的传输通道，输入流从麦克风获取音频数据，
        输出流将处理后的音频数据发送到扬声器。
        
        ============================================================================
        参数说明：
        ============================================================================
        input_device_index (int): 麦克风设备的索引号
            - 可通过 list_audio_devices() 函数查看可用设备列表
            - 必须选择支持音频输入的设备（maxInputChannels > 0）
            
        output_device_index (int, optional): 扬声器设备的索引号
            - None: 不创建输出流，只进行音频处理不播放
            - 有效索引: 创建输出流，播放处理后的音频
            - 必须选择支持音频输出的设备（maxOutputChannels > 0）
        
        ============================================================================
        工作流程：
        ============================================================================
        1. 设备兼容性检查：验证设备是否支持所需的音频格式
        2. 通道数适配：根据设备能力调整声道数配置
        3. 输出流创建：先创建输出流，避免回调函数中的竞态条件
        4. 输入流创建：创建带回调函数的输入流
        5. 异常处理：确保在出错时正确清理资源
        
        ============================================================================
        技术细节：
        ============================================================================
        - 音频格式：paInt16（16位有符号整数）
        - 缓冲区大小：frame_size（160个采样点）
        - 回调模式：异步处理，低延迟
        - 设备适配：自动调整参数以匹配硬件能力
        """
        try:
            # ========================================================
            # 第一步：获取并验证输入设备信息
            # ========================================================
            # 查询设备信息，包括设备名称、支持的通道数等
            input_device_info = self.p.get_device_info_by_index(input_device_index)
            
            # 设备兼容性处理：选择合适的通道数
            # 如果设备支持的通道数少于请求的通道数，则使用设备支持的最大通道数
            input_channels = min(self.channels, input_device_info['maxInputChannels'])
            
            print(f"输入设备: {input_device_info['name']}")
            print(f"输入通道数: {input_channels} (设备最大输入通道: {input_device_info['maxInputChannels']})")
            
            # ========================================================
            # 第二步：创建音频输出流（可选）
            # ========================================================
            # 注意：先创建输出流可以避免在输入回调函数中出现竞态条件
            # 因为输入回调可能会立即开始执行，如果此时输出流还未创建会导致错误
            if output_device_index is not None:
                try:
                    # 获取输出设备信息
                    output_device_info = self.p.get_device_info_by_index(output_device_index)
                    output_channels = min(self.channels, output_device_info['maxOutputChannels'])
                    
                    print(f"输出设备: {output_device_info['name']}")
                    print(f"输出通道数: {output_channels} (设备最大输出通道: {output_device_info['maxOutputChannels']})")
                    
                    # 验证设备是否支持音频输出
                    if output_device_info['maxOutputChannels'] == 0:
                        print("警告: 选择的设备不支持音频输出，跳过输出流创建")
                        self.processed_stream = None
                    else:
                        # 创建PyAudio输出流
                        # format: 音频数据格式（16位整数）
                        # channels: 声道数
                        # rate: 采样率
                        # output: True表示这是输出流
                        # output_device_index: 指定输出设备
                        # frames_per_buffer: 缓冲区大小
                        self.processed_stream = self.p.open(
                            format=pyaudio.paInt16,
                            channels=output_channels,
                            rate=self.sample_rate,
                            output=True,
                            output_device_index=output_device_index,
                            frames_per_buffer=self.frame_size
                        )
                        print(f"输出流已创建 - 设备索引: {output_device_index}")
                        
                except Exception as e:
                    print(f"创建输出流失败: {e}")
                    print("将继续运行，但不会播放处理后的音频")
                    self.processed_stream = None
            else:
                # 用户选择不创建输出流
                self.processed_stream = None
                print("跳过输出流创建")
            
            # ========================================================
            # 第三步：验证输入设备兼容性
            # ========================================================
            if input_device_info['maxInputChannels'] == 0:
                raise ValueError(f"选择的设备 '{input_device_info['name']}' 不支持音频输入")
            
            # ========================================================
            # 第四步：创建音频输入流（核心）
            # ========================================================
            # 创建PyAudio输入流，这是音频数据的入口
            # stream_callback: 指定回调函数，当有新音频数据时自动调用
            self.input_stream = self.p.open(
                format=pyaudio.paInt16,          # 16位整数格式
                channels=input_channels,          # 声道数
                rate=self.sample_rate,           # 采样率
                input=True,                      # 这是输入流
                input_device_index=input_device_index,  # 指定输入设备
                frames_per_buffer=self.frame_size,       # 缓冲区大小
                stream_callback=self.input_callback     # 回调函数
            )
            print(f"输入流已创建 - 设备索引: {input_device_index}")
            
        except Exception as e:
            print(f"创建音频流时出错: {e}")
            
            # ========================================================
            # 异常处理：清理已创建的资源
            # ========================================================
            # 如果在创建过程中出现异常，需要清理可能已经创建的流
            # 防止资源泄漏
            if hasattr(self, 'processed_stream') and self.processed_stream is not None:
                try:
                    self.processed_stream.close()
                except:
                    pass  # 忽略清理过程中的异常
                self.processed_stream = None
            
            # 重新抛出异常，让调用者知道创建失败
            raise
    
    def input_callback(self, in_data: bytes, frame_count: int, time_info: dict, status: int) -> Tuple[bytes, int]:
        """
        音频输入流的回调函数（异步音频处理的核心）
        
        ============================================================================
        方法说明：
        ============================================================================
        这是PyAudio输入流的回调函数，当麦克风有新的音频数据时，
        PyAudio会自动调用这个函数。这是整个音频处理流程的入口点，
        采用异步处理模式，确保音频流的实时性和低延迟。
        
        ============================================================================
        参数说明（由PyAudio自动传递）：
        ============================================================================
        in_data (bytes): 从麦克风读取的原始音频数据
            - 格式：16位有符号整数（paInt16）
            - 大小：frame_size * channels * 2字节
            - 例如：160样本 * 1声道 * 2字节 = 320字节
            
        frame_count (int): 本次传入的音频帧数量
            - 通常等于创建流时设置的frames_per_buffer
            - 用于验证数据完整性
            
        time_info (dict): 时间戳信息
            - input_buffer_adc_time: ADC采样时间
            - current_time: 当前时间
            - output_buffer_dac_time: DAC输出时间（输出流相关）
            
        status (int): 流状态标志
            - 0: 正常状态
            - 非0: 表示有警告或错误（如缓冲区溢出/欠载）
        
        ============================================================================
        工作流程：
        ============================================================================
        1. 数据转换：将字节数据转换为numpy数组便于处理
        2. 缓冲累积：将新数据追加到音频缓冲区
        3. 触发处理：调用process_audio()进行实际的音频增强
        4. 返回状态：告诉PyAudio继续处理音频流
        
        ============================================================================
        技术要点：
        ============================================================================
        - 异步执行：这个函数在独立线程中运行，不会阻塞主程序
        - 实时性要求：处理时间必须短于音频帧时间（10ms）
        - 缓冲区管理：使用缓冲区解决数据到达时间的不确定性
        - 错误容忍：即使处理出错，也要返回继续状态保持音频流
        """
        
        # ================================================
        # 第一步：音频数据格式转换
        # ================================================
        # 将PyAudio返回的字节流转换为numpy数组
        # frombuffer: 从内存缓冲区创建数组，避免数据拷贝，提高效率
        # dtype=np.int16: 指定数据类型为16位有符号整数
        audio_data = np.frombuffer(in_data, dtype=np.int16)
        
        # ================================================
        # 第二步：数据缓冲区管理
        # ================================================
        # 将新的音频数据追加到缓冲区
        # concatenate: 沿着指定轴连接数组，这里是在时间轴上连接
        # 这种设计可以处理数据到达时间不规律的情况
        self.audio_buffer = np.concatenate([self.audio_buffer, audio_data])
        
        # ================================================
        # 第三步：触发音频处理
        # ================================================
        # 调用音频处理函数，执行WebRTC增强算法
        # 这个函数会检查缓冲区是否有足够数据，如果有就进行处理
        self.process_audio()
        
        # ================================================
        # 第四步：返回处理状态
        # ================================================
        # PyAudio要求回调函数返回元组 (output_data, flag)
        # output_data: 输出数据（输入流通常返回原始数据）
        # flag: 控制标志，paContinue表示继续处理音频流
        return (in_data, pyaudio.paContinue)
    
    def process_audio(self) -> None:
        """
        音频增强处理的核心方法
        
        ============================================================================
        方法说明：
        ============================================================================
        这是音频处理的核心方法，负责将原始音频数据通过WebRTC算法进行增强。
        它实现了帧式处理模式，将连续的音频流分割成固定长度的帧进行处理，
        这是数字音频处理的标准做法。
        
        ============================================================================
        处理流程：
        ============================================================================
        1. 数据检查：确保缓冲区有足够的数据（至少一个完整帧）
        2. 帧提取：从缓冲区提取一个10ms的音频帧
        3. 格式转换：将numpy数组转换为WebRTC需要的字节格式
        4. WebRTC处理：应用AGC、NS、VAD算法
        5. 结果输出：将处理结果发送到输出流和回调函数
        6. 状态更新：更新VAD检测状态
        
        ============================================================================
        技术细节：
        ============================================================================
        - 帧长度：固定10ms（WebRTC标准）
        - 处理单位：160个采样点@16kHz
        - 数据格式：16位有符号整数
        - 字节长度：320字节（160样本 × 2字节/样本）
        - 算法顺序：AGC → NS → VAD（WebRTC内部自动处理）
        """
        
        # ================================================
        # 第一步：数据充足性检查
        # ================================================
        # WebRTC要求固定长度的音频帧（10ms = 160 samples @ 16kHz）
        # 如果缓冲区数据不足一个完整帧，则等待更多数据
        if len(self.audio_buffer) < self.frame_size:
            return  # 数据不足，等待下次调用
        
        try:
            # ================================================
            # 第二步：音频帧提取和预处理
            # ================================================
            # 从缓冲区前端提取一个完整的音频帧
            # astype确保数据类型正确（有些操作可能改变数据类型）
            audio_chunk = self.audio_buffer[:self.frame_size].astype(np.int16)
            
            # 从缓冲区移除已提取的数据，采用滑动窗口的方式
            # 这种方式确保连续的音频数据不会丢失
            self.audio_buffer = self.audio_buffer[self.frame_size:]
            
            # ================================================
            # 第三步：数据格式转换
            # ================================================
            # 将numpy数组转换为字节序列，WebRTC C++库需要字节格式的输入
            # tobytes(): 将数组转换为字节字符串，保持内存布局
            audio_bytes_10ms = audio_chunk.tobytes()
            # 验证字节长度：160样本 × 2字节/样本 = 320字节
            
            # ================================================
            # 第四步：WebRTC音频处理（核心算法）
            # ================================================
            # Process10ms是WebRTC的核心方法，执行以下处理：
            # 1. 自动增益控制 (AGC)：调整音量到目标水平
            # 2. 噪声抑制 (NS)：减少背景噪声
            # 3. 语音活动检测 (VAD)：判断是否有语音
            result = self.audio_processor.Process10ms(audio_bytes_10ms)
            
            # result对象包含两个重要属性：
            # - result.audio: 处理后的音频数据（字节格式）
            # - result.is_speech: VAD检测结果（布尔值）
            
            # ================================================
            # 第五步：VAD状态更新和显示
            # ================================================
            # 更新全局语音检测状态
            self.speech_detected = result.is_speech
            
            # 实时显示语音检测结果（用于调试和监控）
            if result.is_speech:
                print("✓ 检测到语音")  # 可以扩展为更详细的日志
            
            # ================================================
            # 第六步：自定义回调函数处理
            # ================================================
            # 如果用户设置了自定义回调函数，将处理后的音频传递给它
            # 这允许用户实现自定义的音频处理逻辑（如保存到文件、进一步分析等）
            if self.processed_audio_callback is not None:
                try:
                    # 调用用户定义的回调函数
                    # 参数1: 处理后的音频数据
                    # 参数2: VAD检测结果
                    self.processed_audio_callback(result.audio, result.is_speech)
                except Exception as e:
                    print(f"处理后音频回调函数出错: {e}")
                    # 回调函数出错不影响主流程继续执行
            
            # ================================================
            # 第七步：音频输出流写入
            # ================================================
            # 如果创建了输出流，将处理后的音频播放出来
            if self.processed_stream is not None and hasattr(self.processed_stream, 'write'):
                try:
                    # 直接写入处理后的音频字节数据到输出流
                    # PyAudio会自动将这些数据发送到扬声器
                    self.processed_stream.write(result.audio)
                except Exception as e:
                    print(f"写入输出流时出错: {e}")
                    # 如果输出流出现问题，禁用它以避免持续错误
                    self.processed_stream = None
        
        except Exception as e:
            # ================================================
            # 异常处理：确保音频流的稳定性
            # ================================================
            print(f"处理音频时出错: {e}")
            # 注意：这里不重新抛出异常，因为音频处理需要持续进行
            # 一次处理失败不应该中断整个音频流
    
    def set_processed_audio_callback(self, callback: Optional[Callable[[bytes, bool], None]]) -> None:
        """
        设置处理后音频的自定义回调函数
        
        ============================================================================
        方法说明：
        ============================================================================
        这个方法允许用户注册一个自定义的回调函数，用于处理WebRTC增强后的音频数据。
        这提供了极大的扩展性，用户可以实现各种自定义功能，如音频保存、
        进一步分析、网络传输等。
        
        ============================================================================
        参数说明：
        ============================================================================
        callback (function): 用户定义的回调函数
            - 函数签名：callback(audio_data, is_speech)
            - audio_data (bytes): 处理后的音频数据，可直接播放或保存
            - is_speech (bool): VAD检测结果，True表示检测到语音
        
        ============================================================================
        使用示例：
        ============================================================================
        def my_audio_handler(audio_data, is_speech):
            if is_speech:
                # 只有检测到语音时才保存
                with open('speech.raw', 'ab') as f:
                    f.write(audio_data)
        
        enhancer.set_processed_audio_callback(my_audio_handler)
        
        ============================================================================
        应用场景：
        ============================================================================
        - 音频录制：保存增强后的音频到文件
        - 语音识别：将音频发送到ASR引擎
        - 网络传输：实时传输清洁的音频数据
        - 质量监控：统计音频质量指标
        - 语音激活：基于VAD结果触发其他功能
        """
        self.processed_audio_callback = callback
    
    def is_speech_detected(self) -> bool:
        """
        获取当前语音活动检测状态
        
        ============================================================================
        方法说明：
        ============================================================================
        返回最近一次音频帧的VAD（语音活动检测）结果。这个方法提供了
        一个简单的接口来查询当前是否有语音活动，可用于实现语音触发、
        音频录制控制等功能。
        
        ============================================================================
        返回值：
        ============================================================================
        bool: 语音检测状态
            - True: 当前检测到语音活动
            - False: 当前未检测到语音活动
        
        ============================================================================
        使用注意：
        ============================================================================
        - 状态基于最后处理的音频帧
        - VAD结果可能有轻微延迟（10ms帧间隔）
        - 建议结合音频回调函数使用获得实时性
        """
        return self.speech_detected
    
    def start(self) -> None:
        """
        启动音频增强处理系统
        
        ============================================================================
        方法说明：
        ============================================================================
        这是系统的主入口点，启动音频流处理并进入主循环。这个方法会阻塞
        当前线程，直到用户按Ctrl+C或发生错误。音频处理在独立的线程中
        异步进行，确保实时性。
        
        ============================================================================
        工作流程：
        ============================================================================
        1. 检查初始化状态：确保音频流已正确创建
        2. 启动音频流：开始从麦克风采集音频数据
        3. 进入主循环：保持程序运行，监听中断信号
        4. 异常处理：优雅地处理各种异常情况
        5. 资源清理：确保所有资源正确释放
        
        ============================================================================
        异常处理：
        ============================================================================
        - KeyboardInterrupt: 用户按Ctrl+C，正常退出
        - 其他异常: 系统错误，记录日志后退出
        - 资源清理: 无论如何退出都会清理资源
        
        ============================================================================
        使用说明：
        ============================================================================
        调用此方法前必须先调用open_streams()创建音频流。
        程序运行期间，音频处理自动进行，无需用户干预。
        """
        
        # ================================================
        # 第一步：检查系统初始化状态
        # ================================================
        if self.input_stream is None:
            print("错误：输入流未创建，请先调用 open_streams()")
            return
            
        print("开始音频增强处理（降噪、自动增益、VAD）...")
        
        try:
            # ================================================
            # 第二步：启动音频输入流
            # ================================================
            # start_stream()开始音频数据的异步采集
            # 此后input_callback函数将在独立线程中被定期调用
            self.input_stream.start_stream()
            print("音频流已启动，按 Ctrl+C 停止...")
            
            # ================================================
            # 第三步：主循环 - 保持程序运行
            # ================================================
            # 主线程进入睡眠循环，让音频处理线程工作
            # 0.1秒的间隔提供了响应中断的机会
            while True:
                time.sleep(0.1)  # 小间隔睡眠，避免CPU占用过高
                
        except KeyboardInterrupt:
            # ================================================
            # 用户主动中断（Ctrl+C）
            # ================================================
            print("\n用户中断，正在停止...")
            self.stop()
            
        except Exception as e:
            # ================================================
            # 系统异常处理
            # ================================================
            print(f"音频处理过程中出错: {e}")
            self.stop()
    
    def stop(self) -> None:
        """
        停止音频处理并清理所有资源
        
        ============================================================================
        方法说明：
        ============================================================================
        这个方法负责安全地停止音频处理系统并释放所有占用的资源。
        它采用多层错误处理机制，确保即使某个步骤失败，其他资源
        仍能正确释放，避免资源泄漏。
        
        ============================================================================
        清理流程：
        ============================================================================
        1. 停止音频输入流：停止麦克风数据采集
        2. 关闭音频输入流：释放输入流资源
        3. 停止音频输出流：停止扬声器播放
        4. 关闭音频输出流：释放输出流资源
        5. 终止PyAudio实例：释放音频系统资源
        
        ============================================================================
        错误处理策略：
        ============================================================================
        - 独立处理：每个清理步骤独立异常处理
        - 继续执行：单步失败不影响后续清理
        - 日志记录：记录所有清理过程中的错误
        - 状态重置：确保对象状态正确重置
        
        ============================================================================
        调用时机：
        ============================================================================
        - 正常退出：用户按Ctrl+C
        - 异常退出：系统发生错误
        - 手动调用：程序需要停止音频处理
        - 析构时：对象销毁时的资源清理
        """
        
        print("停止音频处理")
        
        # ================================================
        # 第一步：停止和关闭音频输入流
        # ================================================
        if self.input_stream is not None:
            try:
                # 检查流是否处于活动状态，避免重复停止
                if self.input_stream.is_active():
                    self.input_stream.stop_stream()  # 停止数据流
                    
                self.input_stream.close()  # 关闭流，释放资源
                
            except Exception as e:
                print(f"关闭输入流时出错: {e}")
                # 继续执行，不让这个错误影响其他清理工作
                
            finally:
                # 无论是否出错，都重置流对象状态
                self.input_stream = None
        
        # ================================================
        # 第二步：停止和关闭音频输出流
        # ================================================
        if self.processed_stream is not None:
            try:
                # 某些PyAudio版本可能没有is_active方法，需要检查
                if hasattr(self.processed_stream, 'is_active') and self.processed_stream.is_active():
                    self.processed_stream.stop_stream()  # 停止播放
                    
                self.processed_stream.close()  # 关闭流，释放资源
                
            except Exception as e:
                print(f"关闭输出流时出错: {e}")
                # 继续执行后续清理工作
                
            finally:
                # 重置输出流对象状态
                self.processed_stream = None
        
        # ================================================
        # 第三步：终止PyAudio音频系统
        # ================================================
        try:
            # terminate()释放PyAudio占用的系统资源
            # 这是最重要的清理步骤，确保音频系统正确关闭
            self.p.terminate()
            
        except Exception as e:
            print(f"终止 PyAudio 时出错: {e}")
            # 即使终止失败，也要继续完成清理流程
        
        print("音频处理已停止，资源已清理")

# ====================================
# 工具函数：音频设备管理
# ====================================

def list_audio_devices() -> Tuple[List[Tuple[int, str]], List[Tuple[int, str]]]:
    """
    列出系统中所有可用的音频设备
    
    ==================================================================================
    函数说明：
    ==================================================================================
    这个工具函数扫描并显示系统中所有的音频设备，包括输入设备（麦克风）
    和输出设备（扬声器）。它帮助用户识别正确的设备索引，这是配置
    音频流的前提条件。
    
    ==================================================================================
    功能特性：
    ==================================================================================
    1. 设备枚举：遍历所有PyAudio可识别的音频设备
    2. 能力分析：检测每个设备的输入输出能力
    3. 分类显示：分别列出输入设备和输出设备
    4. 详细信息：显示设备名称、通道数、设备类型
    5. 友好格式：以用户友好的方式组织和显示信息
    
    ==================================================================================
    返回值：
    ==================================================================================
    tuple: (input_devices, output_devices)
        - input_devices: List[Tuple[int, str]] - 输入设备列表
            - 每个元素为 (设备索引, 设备名称)
        - output_devices: List[Tuple[int, str]] - 输出设备列表
            - 每个元素为 (设备索引, 设备名称)
    
    ==================================================================================
    使用示例：
    ==================================================================================
    input_devs, output_devs = list_audio_devices()
    
    # 选择第一个输入设备
    if input_devs:
        mic_index = input_devs[0][0]
        
    # 选择第一个输出设备
    if output_devs:
        speaker_index = output_devs[0][0]
    
    ==================================================================================
    技术细节：
    ==================================================================================
    - 设备检测：使用PyAudio的设备枚举API
    - 能力判断：通过maxInputChannels和maxOutputChannels判断设备类型
    - 资源管理：临时创建PyAudio实例，使用后立即释放
    - 错误容忍：单个设备查询失败不影响整体枚举
    """
    
    # ================================
    # 初始化PyAudio和数据结构
    # ================================
    # 创建临时PyAudio实例用于设备查询
    p = pyaudio.PyAudio()
    
    print("可用的音频设备:")
    print()
    
    # 用于存储分类后的设备列表
    input_devices = []   # 支持音频输入的设备（麦克风）
    output_devices = []  # 支持音频输出的设备（扬声器）
    
    # ================================
    # 遍历所有音频设备
    # ================================
    for i in range(p.get_device_count()):
        try:
            # 获取设备详细信息
            info = p.get_device_info_by_index(i)
            
            # ================================
            # 设备能力分析和分类
            # ================================
            device_type = []  # 存储设备类型标签
            
            # 检查是否支持音频输入（麦克风功能）
            if info['maxInputChannels'] > 0:
                device_type.append("输入")
                input_devices.append((i, info['name']))
            
            # 检查是否支持音频输出（扬声器功能）
            if info['maxOutputChannels'] > 0:
                device_type.append("输出")
                output_devices.append((i, info['name']))
            
            # 生成设备类型描述字符串
            type_str = "/".join(device_type) if device_type else "无"
            
            # ================================
            # 设备信息格式化显示
            # ================================
            print(f"{i}: {info['name']} " +
                  f"(输入通道: {info['maxInputChannels']}, " +
                  f"输出通道: {info['maxOutputChannels']}) " +
                  f"[{type_str}]")
                  
        except Exception as e:
            # 某些设备可能查询失败，跳过继续处理其他设备
            print(f"{i}: 设备信息获取失败 - {e}")
    
    # ================================
    # 分类设备列表显示
    # ================================
    print()
    print("适合做麦克风的设备 (有输入通道):")
    if input_devices:
        for idx, name in input_devices:
            print(f"  {idx}: {name}")
    else:
        print("  未找到可用的输入设备")
    
    print()
    print("适合做扬声器的设备 (有输出通道):")
    if output_devices:
        for idx, name in output_devices:
            print(f"  {idx}: {name}")
    else:
        print("  未找到可用的输出设备")
    
    # ================================
    # 清理资源
    # ================================
    # 释放PyAudio资源
    p.terminate()
    
    # 返回分类后的设备列表供程序使用
    return input_devices, output_devices

# ====================================
# 主程序：音频增强系统演示
# ====================================

if __name__ == "__main__":
    """
    主程序入口点 - WebRTC音频增强系统演示
    
    ==================================================================================
    程序说明：
    ==================================================================================
    这是一个完整的音频增强系统演示程序，展示了如何使用WebRTC技术对实时
    音频进行增强处理。程序提供了交互式的设备选择界面，让用户可以方便地
    配置和测试音频增强功能。
    
    ==================================================================================
    程序流程：
    ==================================================================================
    1. 设备发现：扫描并显示系统中所有的音频设备
    2. 用户交互：让用户选择麦克风和扬声器设备
    3. 设备验证：确保选择的设备支持相应的音频功能
    4. 系统初始化：创建并配置WebRTC音频处理器
    5. 音频流创建：建立音频输入输出流
    6. 实时处理：启动音频增强处理系统
    7. 优雅退出：处理用户中断和系统异常
    
    ==================================================================================
    使用方法：
    ==================================================================================
    1. 运行程序：python3 aec.py
    2. 查看设备列表：程序会自动显示所有可用音频设备
    3. 选择麦克风：输入对应的设备索引号
    4. 选择扬声器：输入设备索引号或回车跳过
    5. 开始测试：对着麦克风说话，观察处理效果
    6. 停止程序：按Ctrl+C退出
    
    ==================================================================================
    配置说明：
    ==================================================================================
    程序使用以下音频配置（可在代码中修改）：
    - 采样率：16kHz（语音处理的标准采样率）
    - 声道数：1（单声道，节省资源）
    - 帧大小：160个采样点（对应10ms音频）
    - AGC目标：3dBFS（中等自动增益控制）
    - NS级别：2（中等噪声抑制强度）
    
    ==================================================================================
    """
    
    try:
        # ================================================
        # 第一步：音频设备发现和显示
        # ================================================
        print("=" * 80)
        print("WebRTC 音频增强处理器")
        print("=" * 80)
        print()
        
        # 扫描并显示所有可用的音频设备
        # 这一步帮助用户了解系统中有哪些音频设备可用
        input_devices, output_devices = list_audio_devices()
        
        # 检查是否有可用的音频设备
        if not input_devices:
            print("错误：系统中没有找到可用的音频输入设备（麦克风）")
            print("请检查：")
            print("1. 麦克风是否正确连接")
            print("2. 音频驱动是否正常安装")
            print("3. 设备是否被其他程序占用")
            exit(1)
        
        # ================================================
        # 第二步：用户交互 - 输入设备选择
        # ================================================
        print()
        print("=" * 50)
        print("设备配置")
        print("=" * 50)
        
        # 获取用户选择的麦克风设备索引
        while True:
            try:
                input_device_index = int(input("请输入麦克风设备索引: "))
                break
            except ValueError:
                print("请输入有效的数字索引")
        
        # ================================================
        # 第三步：输入设备验证
        # ================================================
        # 验证用户选择的设备是否支持音频输入
        if not any(idx == input_device_index for idx, _ in input_devices):
            print(f"错误: 设备 {input_device_index} 不支持音频输入！")
            print("请选择有输入通道的设备。")
            exit(1)
        
        # ================================================
        # 第四步：用户交互 - 输出设备选择（可选）
        # ================================================
        output_device_index_input = input("请输入扬声器设备索引（可选，直接回车跳过）: ")
        
        # 处理输出设备索引，支持跳过输出
        if output_device_index_input.strip():
            try:
                output_device_index = int(output_device_index_input)
            except ValueError:
                print("警告: 无效的输出设备索引，将跳过音频播放")
                output_device_index = None
        else:
            output_device_index = None
        
        # ================================================
        # 第五步：输出设备验证
        # ================================================
        if output_device_index is not None:
            if not any(idx == output_device_index for idx, _ in output_devices):
                print(f"警告: 设备 {output_device_index} 不支持音频输出！")
                print("将跳过音频播放，但音频处理会继续进行。")
                output_device_index = None
        
        # ================================================
        # 第六步：WebRTC音频处理器创建和配置
        # ================================================
        print()
        print("=" * 50)
        print("系统初始化")
        print("=" * 50)
        
        # 创建WebRTC音频增强处理器实例
        # 这里使用推荐的参数配置，适合大多数语音处理场景
        audio_enhancer = WebRTCAudioEnhancer(
            sample_rate=16000,           # 16kHz采样率：语音处理的标准
            channels=1,                  # 单声道：节省计算资源
            frame_size=160,              # 160个采样点：对应10ms@16kHz
            auto_gain_dbfs=3,           # 中等自动增益控制：平衡音量
            noise_suppression_level=2    # 中等噪声抑制：平衡降噪和音质
        )
        
        print("\n参数配置说明：")
        print("- 采样率: 16000Hz (电话质量，适合语音)")
        print("- 声道数: 1 (单声道)")
        print("- 帧大小: 160个采样点 (10ms音频帧)")
        print("- 自动增益: 3dBFS (中等强度)")
        print("- 噪声抑制: 级别2 (中等强度)")
        
        # ================================================
        # 第七步：音频流创建
        # ================================================
        print("\n正在创建音频流...")
        
        # 创建音频输入输出流
        # 这一步会实际连接到音频硬件
        audio_enhancer.open_streams(input_device_index, output_device_index)
        
        # ================================================
        # 第八步：启动音频增强处理
        # ================================================
        print()
        print("=" * 50)
        print("开始音频处理")
        print("=" * 50)
        print("💡 测试说明：")
        print("1. 对着麦克风说话，观察语音检测提示")
        print("2. 注意音频增强效果（降噪、音量调整）")
        print("3. 按 Ctrl+C 停止程序")
        print()
        
        # 启动音频处理系统（阻塞调用）
        # 这个方法会一直运行直到用户中断
        audio_enhancer.start()
        
    except KeyboardInterrupt:
        # ================================================
        # 用户主动中断处理
        # ================================================
        print("\n" + "=" * 50)
        print("程序被用户中断")
        print("=" * 50)
        
    except ValueError as e:
        # ================================================
        # 输入验证错误处理
        # ================================================
        print("\n" + "=" * 50)
        print("输入错误")
        print("=" * 50)
        print(f"错误信息: {e}")
        print("解决方案: 请确保输入有效的设备索引号")
        print("提示: 设备索引应该是上面列表中显示的数字")
        
    except Exception as e:
        # ================================================
        # 系统异常处理
        # ================================================
        print("\n" + "=" * 50)
        print("系统错误")
        print("=" * 50)
        print(f"错误信息: {e}")
        print("可能的原因:")
        print("1. 音频设备被其他程序占用")
        print("2. 音频驱动程序问题")
        print("3. 权限不足无法访问音频设备")
        print("4. webrtc_noise_gain库未正确安装")
        print()
        print("解决建议:")
        print("1. 关闭其他使用音频的程序")
        print("2. 重新插拔音频设备")
        print("3. 以管理员权限运行程序")
        print("4. 检查依赖库安装: pip3 install webrtc-noise-gain")
        
    finally:
        # ================================================
        # 程序结束清理
        # ================================================
        print()
        print("=" * 50)
        print("程序已结束")
        print("=" * 50)
        print("感谢使用 WebRTC 音频增强处理器！")